movementkit-cli 1.0.1 → 1.0.3

package/kits/engineer/docs/MOVE_LANGUAGE_REFERENCE.md

@@ -0,0 +1,560 @@
+# Move Language Reference for Movement Blockchain
+
+This document provides a comprehensive reference for writing Move smart contracts on the Movement blockchain.
+
+## Movement Network Configuration
+
+### Network Endpoints
+```
+Mainnet: https://full.mainnet.movementinfra.xyz/v1 (Chain ID: 126)
+Testnet: https://full.testnet.movementinfra.xyz/v1 (Chain ID: 250)
+Faucet:  https://faucet.movementnetwork.xyz/
+Explorer: https://explorer.movementnetwork.xyz/
+```
+
+### CLI Commands
+```bash
+# Initialize a new Move project
+movement move init --name project_name
+
+# Compile contracts
+movement move compile
+
+# Run tests
+movement move test
+
+# Publish to testnet
+movement move publish --url https://full.testnet.movementinfra.xyz/v1 --named-addresses module_addr=default
+
+# Publish to mainnet
+movement move publish --url https://full.mainnet.movementinfra.xyz/v1 --named-addresses module_addr=default
+```
+
+## Move.toml Configuration
+
+```toml
+[package]
+name = "project_name"
+version = "1.0.0"
+authors = []
+
+[addresses]
+module_addr = "_"
+
+[dependencies]
+AptosFramework = { git = "https://github.com/aptos-labs/aptos-core.git", subdir = "aptos-move/framework/aptos-framework", rev = "mainnet" }
+AptosStdlib = { git = "https://github.com/aptos-labs/aptos-core.git", subdir = "aptos-move/framework/aptos-stdlib", rev = "mainnet" }
+MoveStdlib = { git = "https://github.com/aptos-labs/aptos-core.git", subdir = "aptos-move/framework/move-stdlib", rev = "mainnet" }
+```
+
+## Module Structure
+
+```move
+module module_addr::module_name {
+    // Imports
+    use std::signer;
+    use std::string::String;
+    use std::vector;
+    use std::option::{Self, Option};
+    use aptos_framework::event;
+    use aptos_framework::account;
+    use aptos_framework::timestamp;
+    use aptos_framework::coin;
+    use aptos_framework::aptos_coin::AptosCoin;
+
+    // Error codes (constants)
+    const E_NOT_AUTHORIZED: u64 = 1;
+    const E_ALREADY_EXISTS: u64 = 2;
+    const E_NOT_FOUND: u64 = 3;
+    const E_INSUFFICIENT_BALANCE: u64 = 4;
+
+    // Resources (structs with 'key' ability)
+    struct ResourceName has key, store {
+        field1: u64,
+        field2: String,
+        field3: vector<u8>,
+    }
+
+    // Events
+    #[event]
+    struct EventName has drop, store {
+        actor: address,
+        value: u64,
+        timestamp: u64,
+    }
+
+    // Entry functions (callable from transactions)
+    public entry fun function_name(
+        account: &signer,
+        param1: u64,
+    ) acquires ResourceName {
+        // Implementation
+    }
+
+    // View functions (read-only, callable without transaction)
+    #[view]
+    public fun get_value(addr: address): u64 acquires ResourceName {
+        borrow_global<ResourceName>(addr).field1
+    }
+
+    // Internal functions
+    fun internal_helper(): u64 {
+        42
+    }
+}
+```
+
+## Primitive Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `u8` | 8-bit unsigned integer | `let x: u8 = 255;` |
+| `u16` | 16-bit unsigned integer | `let x: u16 = 65535;` |
+| `u32` | 32-bit unsigned integer | `let x: u32 = 100;` |
+| `u64` | 64-bit unsigned integer | `let x: u64 = 1000000;` |
+| `u128` | 128-bit unsigned integer | `let x: u128 = 1000000;` |
+| `u256` | 256-bit unsigned integer | `let x: u256 = 1000000;` |
+| `bool` | Boolean | `let b: bool = true;` |
+| `address` | 32-byte address | `let a: address = @0x1;` |
+| `vector<T>` | Dynamic array | `let v: vector<u8> = vector[];` |
+| `String` | UTF-8 string | `use std::string::String;` |
+
+## Abilities
+
+| Ability | Description |
+|---------|-------------|
+| `copy` | Value can be copied |
+| `drop` | Value can be dropped (destroyed) |
+| `store` | Value can be stored in global storage |
+| `key` | Value can be used as a key in global storage |
+
+```move
+// Resource that can be stored globally
+struct MyResource has key, store {
+    value: u64,
+}
+
+// Struct that can be copied and dropped
+struct MyData has copy, drop, store {
+    value: u64,
+}
+
+// Event struct (must have drop and store)
+#[event]
+struct MyEvent has drop, store {
+    value: u64,
+}
+```
+
+## Global Storage Operations
+
+```move
+// Store a resource at an address
+move_to<ResourceName>(account, ResourceName { field1: 0, field2: string::utf8(b"hello") });
+
+// Check if resource exists
+exists<ResourceName>(addr)
+
+// Borrow immutable reference
+let resource_ref = borrow_global<ResourceName>(addr);
+
+// Borrow mutable reference
+let resource_mut = borrow_global_mut<ResourceName>(addr);
+
+// Remove resource from storage
+let resource = move_from<ResourceName>(addr);
+```
+
+## Signer Operations
+
+```move
+use std::signer;
+
+public entry fun my_function(account: &signer) {
+    // Get address from signer
+    let addr = signer::address_of(account);
+
+    // Validate caller
+    assert!(addr == @admin_address, E_NOT_AUTHORIZED);
+}
+```
+
+## Events
+
+```move
+use aptos_framework::event;
+
+// Define event struct
+#[event]
+struct TransferEvent has drop, store {
+    from: address,
+    to: address,
+    amount: u64,
+}
+
+// Emit event
+event::emit(TransferEvent {
+    from: sender_addr,
+    to: recipient_addr,
+    amount: 100,
+});
+```
+
+## Vectors
+
+```move
+use std::vector;
+
+// Create empty vector
+let v: vector<u64> = vector[];
+
+// Create with initial values
+let v = vector[1, 2, 3];
+
+// Push element
+vector::push_back(&mut v, 4);
+
+// Pop element
+let last = vector::pop_back(&mut v);
+
+// Get length
+let len = vector::length(&v);
+
+// Check if empty
+let is_empty = vector::is_empty(&v);
+
+// Get element by index (immutable)
+let elem = vector::borrow(&v, 0);
+
+// Get element by index (mutable)
+let elem_mut = vector::borrow_mut(&mut v, 0);
+
+// Check if contains
+let contains = vector::contains(&v, &42);
+```
+
+## Strings
+
+```move
+use std::string::{Self, String};
+
+// Create from bytes
+let s: String = string::utf8(b"Hello, World!");
+
+// Get length
+let len = string::length(&s);
+
+// Check if empty
+let is_empty = string::is_empty(&s);
+
+// Append
+string::append(&mut s, string::utf8(b" More text"));
+
+// Convert to bytes
+let bytes: vector<u8> = *string::bytes(&s);
+```
+
+## Options
+
+```move
+use std::option::{Self, Option};
+
+// Create Some
+let opt: Option<u64> = option::some(42);
+
+// Create None
+let none: Option<u64> = option::none();
+
+// Check if some
+let is_some = option::is_some(&opt);
+
+// Check if none
+let is_none = option::is_none(&none);
+
+// Extract value (aborts if none)
+let value = option::extract(&mut opt);
+
+// Get with default
+let value = option::get_with_default(&opt, 0);
+
+// Borrow value
+let value_ref = option::borrow(&opt);
+```
+
+## Coin Operations
+
+```move
+use aptos_framework::coin;
+use aptos_framework::aptos_coin::AptosCoin;
+
+// Register coin store for account
+coin::register<AptosCoin>(account);
+
+// Get balance
+let balance = coin::balance<AptosCoin>(addr);
+
+// Transfer coins
+coin::transfer<AptosCoin>(from, to_addr, amount);
+
+// Withdraw coins
+let coins = coin::withdraw<AptosCoin>(account, amount);
+
+// Deposit coins
+coin::deposit(to_addr, coins);
+```
+
+## Timestamp
+
+```move
+use aptos_framework::timestamp;
+
+// Get current timestamp in seconds
+let now_seconds = timestamp::now_seconds();
+
+// Get current timestamp in microseconds
+let now_microseconds = timestamp::now_microseconds();
+```
+
+## Testing
+
+### Basic Test
+```move
+#[test_only]
+module module_addr::module_name_tests {
+    use std::signer;
+    use module_addr::module_name;
+
+    #[test(account = @0x1)]
+    fun test_basic_function(account: &signer) {
+        // Setup
+        let addr = signer::address_of(account);
+
+        // Action
+        module_name::initialize(account);
+
+        // Assert
+        assert!(module_name::get_value(addr) == 0, 0);
+    }
+}
+```
+
+### Test with Expected Failure
+```move
+#[test]
+#[expected_failure(abort_code = module_name::E_NOT_AUTHORIZED)]
+fun test_unauthorized_access() {
+    // This should fail with E_NOT_AUTHORIZED
+    module_name::admin_only_function();
+}
+```
+
+### Test with Multiple Signers
+```move
+#[test(admin = @0x1, user = @0x2)]
+fun test_with_multiple_accounts(admin: &signer, user: &signer) {
+    // Setup admin
+    module_name::initialize(admin);
+
+    // User interacts
+    module_name::user_action(user);
+}
+```
+
+### Test with Framework
+```move
+#[test(aptos_framework = @aptos_framework, account = @0x1)]
+fun test_with_framework(aptos_framework: &signer, account: &signer) {
+    // Setup timestamp for testing
+    timestamp::set_time_has_started_for_testing(aptos_framework);
+
+    // Now timestamp::now_seconds() works in tests
+    module_name::time_dependent_function(account);
+}
+```
+
+## Common Patterns
+
+### Initialization Pattern
+```move
+struct Config has key {
+    admin: address,
+    is_initialized: bool,
+}
+
+public entry fun initialize(admin: &signer) {
+    let admin_addr = signer::address_of(admin);
+    assert!(!exists<Config>(admin_addr), E_ALREADY_EXISTS);
+
+    move_to(admin, Config {
+        admin: admin_addr,
+        is_initialized: true,
+    });
+}
+```
+
+### Admin-Only Pattern
+```move
+public entry fun admin_function(admin: &signer) acquires Config {
+    let admin_addr = signer::address_of(admin);
+    let config = borrow_global<Config>(@module_addr);
+    assert!(config.admin == admin_addr, E_NOT_AUTHORIZED);
+
+    // Admin-only logic
+}
+```
+
+### Counter Pattern
+```move
+struct Counter has key {
+    value: u64,
+}
+
+public entry fun increment(account: &signer) acquires Counter {
+    let addr = signer::address_of(account);
+
+    if (!exists<Counter>(addr)) {
+        move_to(account, Counter { value: 0 });
+    };
+
+    let counter = borrow_global_mut<Counter>(addr);
+    counter.value = counter.value + 1;
+
+    event::emit(CounterIncremented {
+        account: addr,
+        new_value: counter.value
+    });
+}
+
+#[view]
+public fun get_count(addr: address): u64 acquires Counter {
+    if (!exists<Counter>(addr)) {
+        return 0
+    };
+    borrow_global<Counter>(addr).value
+}
+```
+
+### Token/NFT Collection Pattern
+```move
+struct Collection has key {
+    items: vector<Item>,
+    next_id: u64,
+}
+
+struct Item has store, drop {
+    id: u64,
+    name: String,
+    owner: address,
+}
+
+public entry fun mint(account: &signer, name: String) acquires Collection {
+    let addr = signer::address_of(account);
+    let collection = borrow_global_mut<Collection>(@module_addr);
+
+    let item = Item {
+        id: collection.next_id,
+        name,
+        owner: addr,
+    };
+
+    vector::push_back(&mut collection.items, item);
+    collection.next_id = collection.next_id + 1;
+
+    event::emit(ItemMinted { id: collection.next_id - 1, owner: addr });
+}
+```
+
+## Security Best Practices
+
+1. **Always validate signers** - Check that the caller has permission
+2. **Use assert! with error codes** - Provide clear error messages
+3. **Emit events for state changes** - Enable off-chain tracking
+4. **Check for resource existence** - Use `exists<T>(addr)` before accessing
+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
+
+## Complete Example: Simple Token
+
+```move
+module module_addr::simple_token {
+    use std::signer;
+    use std::string::String;
+    use aptos_framework::event;
+
+    // Errors
+    const E_NOT_INITIALIZED: u64 = 1;
+    const E_INSUFFICIENT_BALANCE: u64 = 2;
+
+    // Resources
+    struct TokenInfo has key {
+        name: String,
+        symbol: String,
+        total_supply: u64,
+    }
+
+    struct Balance has key {
+        value: u64,
+    }
+
+    // Events
+    #[event]
+    struct Transfer has drop, store {
+        from: address,
+        to: address,
+        amount: u64,
+    }
+
+    // Initialize token
+    public entry fun initialize(
+        admin: &signer,
+        name: String,
+        symbol: String,
+        initial_supply: u64,
+    ) {
+        let admin_addr = signer::address_of(admin);
+
+        move_to(admin, TokenInfo {
+            name,
+            symbol,
+            total_supply: initial_supply,
+        });
+
+        move_to(admin, Balance { value: initial_supply });
+    }
+
+    // Transfer tokens
+    public entry fun transfer(
+        from: &signer,
+        to: address,
+        amount: u64,
+    ) acquires Balance {
+        let from_addr = signer::address_of(from);
+
+        // Deduct from sender
+        let from_balance = borrow_global_mut<Balance>(from_addr);
+        assert!(from_balance.value >= amount, E_INSUFFICIENT_BALANCE);
+        from_balance.value = from_balance.value - amount;
+
+        // Add to recipient
+        if (!exists<Balance>(to)) {
+            // Create balance for new recipient (requires signer, simplified here)
+            // In practice, recipient would need to register first
+        };
+        let to_balance = borrow_global_mut<Balance>(to);
+        to_balance.value = to_balance.value + amount;
+
+        event::emit(Transfer { from: from_addr, to, amount });
+    }
+
+    // View balance
+    #[view]
+    public fun balance_of(addr: address): u64 acquires Balance {
+        if (!exists<Balance>(addr)) {
+            return 0
+        };
+        borrow_global<Balance>(addr).value
+    }
+}
+```
+

package/kits/engineer/frontend/.env.example

@@ -0,0 +1,9 @@
+# Movement Network Configuration
+VITE_NETWORK=testnet
+VITE_MODULE_ADDRESS=0x1
+VITE_MODULE_NAME=module_name
+VITE_API_URL=http://localhost:3001
+
+# Optional: Aptos API Key for wallet adapter
+# VITE_APTOS_API_KEY=your_api_key_here
+

package/kits/engineer/frontend/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Movement dApp</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+

package/kits/engineer/frontend/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "movement-dapp-frontend",
+  "version": "1.0.0",
+  "description": "Frontend for Movement blockchain dApp",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage"
+  },
+  "dependencies": {
+    "@aptos-labs/ts-sdk": "^1.33.1",
+    "@aptos-labs/wallet-adapter-react": "^3.0.0",
+    "@radix-ui/react-dialog": "^1.0.5",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "typescript": "^5.3.0",
+    "vite": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}
+

package/kits/engineer/frontend/src/App.tsx

@@ -0,0 +1,41 @@
+import { WalletProvider } from "./contexts/WalletContext";
+import { WalletConnect } from "./components/WalletConnect";
+
+function App() {
+  return (
+    <WalletProvider>
+      <div className="app">
+        <header>
+          <h1>🚀 Movement dApp</h1>
+          <p>Built with Movement Kit</p>
+        </header>
+
+        <main>
+          <div className="card">
+            <WalletConnect />
+          </div>
+
+          <div className="card">
+            <h2>Getting Started</h2>
+            <p>Connect your wallet to interact with the Movement blockchain.</p>
+          </div>
+        </main>
+
+        <footer>
+          <p>
+            <a href="https://explorer.movementnetwork.xyz/" target="_blank" rel="noopener noreferrer">
+              Movement Explorer
+            </a>
+            {" | "}
+            <a href="https://faucet.movementnetwork.xyz/" target="_blank" rel="noopener noreferrer">
+              Faucet
+            </a>
+          </p>
+        </footer>
+      </div>
+    </WalletProvider>
+  );
+}
+
+export default App;
+

package/kits/engineer/frontend/src/components/WalletConnect.tsx

@@ -0,0 +1,54 @@
+import { useWallet } from "@aptos-labs/wallet-adapter-react";
+
+export function WalletConnect() {
+  const { 
+    connect, 
+    disconnect, 
+    account, 
+    connected, 
+    wallets,
+    isLoading,
+  } = useWallet();
+
+  // Format address for display
+  const formatAddress = (address: string) => {
+    return `${address.slice(0, 6)}...${address.slice(-4)}`;
+  };
+
+  if (isLoading) {
+    return <div>Loading wallet...</div>;
+  }
+
+  if (connected && account) {
+    return (
+      <div className="wallet-connected">
+        <p>
+          <strong>Connected:</strong> {formatAddress(account.address.toString())}
+        </p>
+        <button onClick={disconnect}>
+          Disconnect Wallet
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="wallet-connect">
+      <h3>Connect Wallet</h3>
+      <div className="wallet-options">
+        {wallets?.filter(wallet => wallet.readyState === "Installed").map((wallet) => (
+          <button 
+            key={wallet.name} 
+            onClick={() => connect(wallet.name)}
+          >
+            Connect {wallet.name}
+          </button>
+        ))}
+        {wallets?.filter(wallet => wallet.readyState === "Installed").length === 0 && (
+          <p>No wallets detected. Please install a wallet extension.</p>
+        )}
+      </div>
+    </div>
+  );
+}
+