movementkit-cli 1.0.15 → 1.0.16

package/dist/index.js

@@ -2912,7 +2912,7 @@ var cac = (name = "") => new CAC(name);
 // src/index.ts
 var import_picocolors9 = __toESM(require_picocolors(), 1);
 // package.json
-var version = "1.0.15";
+var version = "1.0.16";
 
 // node_modules/@clack/core/dist/index.mjs
 var import_sisteransi = __toESM(require_src(), 1);

package/kits/engineer/.claude/agents/smart-contract.md

@@ -72,6 +72,34 @@ movement move publish --url https://full.testnet.movementinfra.xyz/v1 --named-ad
 
 **IMPORTANT:** Always run `movement init` first to set up your account before compiling.
 
+## Project Structure (Multi-Module)
+
+For complex DeFi applications, organize modules by concern:
+```
+my_project/
+├── sources/
+│   ├── errors.move      # Shared error codes (base layer)
+│   ├── math.move        # Math utilities (depends on errors)
+│   ├── token.move       # Token/LP token (depends on math)
+│   ├── pool.move        # Core logic (depends on token)
+│   └── factory.move     # Registry (depends on pool)
+├── Move.toml
+└── scripts/             # Optional deployment scripts
+```
+
+**Module Dependency Hierarchy:**
+```
+errors.move (base - no dependencies)
+    ↓
+math.move (utilities)
+    ↓
+token.move (LP token management)
+    ↓
+pool.move (core AMM/DeFi logic)
+    ↓
+factory.move (pool registry)
+```
+
 ## Move.toml Configuration
 
 ```toml
@@ -419,33 +447,139 @@ public fun get_count(addr: address): u64 acquires Counter {
 }
 ```
 
-### Token/NFT Collection Pattern
+### Fungible Asset (Token) Pattern
 ```move
-struct Collection has key {
-    items: vector<Item>,
-    next_id: u64,
+module module_addr::my_token {
+    use std::string;
+    use std::option;
+    use aptos_framework::object;
+    use aptos_framework::fungible_asset::{Self, MintRef, BurnRef, TransferRef};
+    use aptos_framework::primary_fungible_store;
+
+    const ASSET_SYMBOL: vector<u8> = b"MYTOKEN";
+
+    struct Management has key {
+        mint_ref: MintRef,
+        burn_ref: BurnRef,
+        transfer_ref: TransferRef,
+    }
+
+    fun init_module(admin: &signer) {
+        let constructor_ref = &object::create_named_object(admin, ASSET_SYMBOL);
+
+        primary_fungible_store::create_primary_store_enabled_fungible_asset(
+            constructor_ref,
+            option::none(), // max supply (none = unlimited)
+            string::utf8(b"My Token"),
+            string::utf8(ASSET_SYMBOL),
+            8, // decimals
+            string::utf8(b"https://example.com/icon.png"),
+            string::utf8(b"https://example.com"),
+        );
+
+        let mint_ref = fungible_asset::generate_mint_ref(constructor_ref);
+        let burn_ref = fungible_asset::generate_burn_ref(constructor_ref);
+        let transfer_ref = fungible_asset::generate_transfer_ref(constructor_ref);
+
+        move_to(admin, Management { mint_ref, burn_ref, transfer_ref });
+    }
+
+    public entry fun mint(admin: &signer, to: address, amount: u64) acquires Management {
+        let management = borrow_global<Management>(@module_addr);
+        let tokens = fungible_asset::mint(&management.mint_ref, amount);
+        primary_fungible_store::deposit(to, tokens);
+    }
 }
+```
+
+### AMM Pool Pattern (Uniswap V2 Style)
+```move
+module module_addr::pool {
+    use aptos_framework::coin::{Self, Coin};
+
+    struct LiquidityPool<phantom X, phantom Y> has key {
+        reserve_x: Coin<X>,
+        reserve_y: Coin<Y>,
+        total_lp_supply: u64,
+    }
 
-struct Item has store, drop {
-    id: u64,
-    name: String,
-    owner: address,
+    /// Constant product formula: x * y = k
+    public fun get_amount_out(amount_in: u64, reserve_in: u64, reserve_out: u64): u64 {
+        let amount_in_with_fee = (amount_in as u128) * 997; // 0.3% fee
+        let numerator = amount_in_with_fee * (reserve_out as u128);
+        let denominator = ((reserve_in as u128) * 1000) + amount_in_with_fee;
+        ((numerator / denominator) as u64)
+    }
+
+    /// Safe math: multiply then divide using u128 to prevent overflow
+    public fun safe_mul_div(a: u64, b: u64, c: u64): u64 {
+        assert!(c > 0, 1); // E_DIVISION_BY_ZERO
+        let result = ((a as u128) * (b as u128)) / (c as u128);
+        (result as u64)
+    }
 }
+```
 
-public entry fun mint(account: &signer, name: String) acquires Collection {
-    let addr = signer::address_of(account);
-    let collection = borrow_global_mut<Collection>(@module_addr);
+### Collateral Position Pattern (DeFi)
+```move
+module module_addr::vault {
+    const MIN_COLLATERAL_RATIO: u64 = 15000; // 150% in basis points
+    const BASIS_POINTS: u64 = 10000;
 
-    let item = Item {
-        id: collection.next_id,
-        name,
-        owner: addr,
-    };
+    struct CollateralPosition has key {
+        collateral_amount: u64,
+        minted_amount: u64,
+    }
+
+    fun is_position_healthy(collateral: u64, minted: u64, price: u64): bool {
+        if (minted == 0) return true;
+        let collateral_value = collateral * price;
+        let required = (minted * MIN_COLLATERAL_RATIO) / BASIS_POINTS;
+        collateral_value >= required
+    }
 
-    vector::push_back(&mut collection.items, item);
-    collection.next_id = collection.next_id + 1;
+    public entry fun deposit_and_mint(
+        user: &signer,
+        collateral_amount: u64,
+        mint_amount: u64
+    ) acquires CollateralPosition {
+        // Validate position remains healthy after mint
+        assert!(is_position_healthy(collateral_amount, mint_amount, get_price()), E_UNDERCOLLATERALIZED);
+        // ... deposit collateral and mint tokens
+    }
+}
+```
+
+### Math Utilities Module
+```move
+module module_addr::math {
+    const E_DIVIDE_BY_ZERO: u64 = 100;
+    const E_OVERFLOW: u64 = 101;
+
+    /// Safe multiply then divide using u256 to prevent overflow
+    public fun mul_div(a: u64, b: u64, c: u64): u64 {
+        assert!(c > 0, E_DIVIDE_BY_ZERO);
+        let result = ((a as u256) * (b as u256)) / (c as u256);
+        assert!(result <= 18446744073709551615, E_OVERFLOW); // u64 max
+        (result as u64)
+    }
 
-    event::emit(ItemMinted { id: collection.next_id - 1, owner: addr });
+    /// Square root using Newton's method (for LP token calculation)
+    public fun sqrt(x: u128): u128 {
+        if (x == 0) return 0;
+        let z = (x + 1) / 2;
+        let y = x;
+        while (z < y) {
+            y = z;
+            z = (x / z + z) / 2;
+        };
+        y
+    }
+
+    /// Calculate minimum of two values
+    public fun min(a: u64, b: u64): u64 {
+        if (a < b) a else b
+    }
 }
 ```
 
@@ -458,6 +592,8 @@ public entry fun mint(account: &signer, name: String) acquires Collection {
 5. **Avoid unbounded loops** - Can cause out-of-gas errors
 6. **Use acquires annotation** - Declare all resources accessed
 7. **Initialize before use** - Ensure resources exist before borrowing
+8. **Use u128/u256 for intermediate math** - Prevent overflow in calculations
+9. **Validate collateral ratios** - Always check positions remain healthy
 
 ## Complete Example: Simple Token
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "movementkit-cli",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "CLI tool for bootstrapping and updating Movement Kit projects for Movement blockchain development",
   "type": "module",
   "repository": {