You Onchain Bio

Your name:

Your Bio:

</div>

<div className="row">
          <button onClick={registerBio}>Register Bio</button>
        </div>

<div className="row">
          <button onClick={fetchBio}>Fetch Bio</button>
        </div>

<div className="row">
          <center>
            <h3>Your Name:</h3>
            <p>{currentName}</p>
          </center>
        </div>

<div className="row">
          <center>
            <h3>Your Bio:</h3>
            <p>{currentBio}</p>
          </center>
        </div>

</div>
    </>
  );
}

export default App;
```

Lastly replace the code in the `index.css`

```css
:root {
    font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
    line-height: 1.5;
    font-weight: 400;
  
    font-synthesis: none;
    text-rendering: optimizeLegibility;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
    -webkit-text-size-adjust: 100%;
  }
  body {
    margin: 0;
  }
  
  h1, h3 {
    margin-bottom: 5px;
  }
  h3 {
    margin-top: 0;
  }
  
  .navbar {
    display: flex;
    justify-content: space-between;
    align-items: center;
    background-color: #333;
    color: #fff;
    padding: 10px 20px;
  }
  
  .navbar-text {
    font-size: 20px;
  }
  
  .center-container {
    display: flex;
    flex-direction: column;
    
    align-items: center;
    height: 100vh; /* Adjust this to control vertical centering */
  }
  
  .row {
    display: flex;
    justify-content: center;
  }
  
  .name {
    margin-bottom: 10px;
    width: 200px;
  }
  
  .bio {
    margin-bottom: 10px;
    width: 300px;
    height: 200px;
    resize: vertical; 
  }
```

Your locally-running app should now look like this:

![app](./imgs/localapp.png)

Feel free to style the app however you prefer.

## Using your App

To use the dApp, first configure an Aptos wallet to testnet.

Head over to the [Movement Faucet](https://faucet.movementnetwork.xyz/) and fund your wallet.

Enter a name and bio. Click the Register Bio button. The wallet should pop up for you to sign. After the transaction has been submitted to the blockchain, you'll see your onchain bio information updated:

![apupdate](./imgs/localupdated.png)

## What dApps will you build on Movement?

Now you know how to deploy an Aptos dApp for testnet.

Check out `onchain_bio.move` logic, try a redeployment by tinkering with it. As a challenge, try modifying the Front End to better display your name and bio!

We can't wait to see what dApps you build and deploy to Movement Network!

# Deploy
URL: /devs/tutorials/deploy

🚀 If you already have a Move module written, you can deploy it to the Movement Network using the Movement CLI or Aptos CLI.

For a full guide on how to install the CLI and get your development environment setup, please see our [First Move Module](/devs/firstMoveContract) guide.

## Check Config

Ensure your `config.yaml` is configured to the correct network for the profile you are using. This can be found in the `.movement` directory at the root of your project.

```
---
profiles:
  default:
    network: Custom
    private_key: "0xYOUR_PRIVATE_KEY"
    public_key: "0xYOUR_PRIVATE_KEY"
    account: "account_address"
    rest_url: "https://testnet.movementnetwork.xyz/v1"
    faucet_url: "https://faucet.testnet.movementnetwork.xyz/"
```

## Add Address to Move.Toml

To make compiling, testing, and of course deploying your Move module easier, you can add your address to the `move.toml` file at the root of your Move project.

```
[addresses]
default = "YOUR_ADDRESS"
```

## Deploy to Movement Network

Run the following command to deploy your Move module to the Movement Network:

```
movement move publish
```

You'll be prompted to confirm the transaction and spend a small amount of testnet tokens:

```
Do you want to submit this transaction? [Y/n]
```

Type `Y` and press **Enter**.

> **Ensure you have sufficient testnet tokens from the faucet before proceeding.**

# Move Slayers (On-chain RPG)
URL: /devs/tutorials/move_slayers

# 🎮 Building an On-Chain RPG with Move: A Complete Educational Guide

This guide walks through every line of code in the [`move_slayers`](https://github.com/movement-network/move-slayers) game, explaining how to build an on-chain RPG using the Move language on Movement.

## 📚 What You'll Learn

* **Move Language Fundamentals**: Structs, functions, resource management
* **On-Chain Game Design**: State management, player progression, combat systems
* **Best Practices**: Resource safety, error handling, modular design
* **Real-World Patterns**: How to structure complex on-chain applications

***

## 🏗️ Project Structure

```
move_slayers/
├── sources/
│   ├── hero.move      # Player logic and game mechanics
│   └── enemies.move   # Enemy definitions and combat
├── tests/
│   └── hero_tests.move # Comprehensive test suite
└── Move.toml          # Project configuration
```

***

## 📦 Module 1: Hero System (`sources/hero.move`)

### 🔧 Module Declaration and Imports

```
module move_slayers::hero {

use std::signer;
    use std::vector;
    use std::string;
    use std::option;
    use move_slayers::enemies;
```

**Explanation:**

* `module move_slayers::hero` - Declares this as a Move module named `hero` in the `move_slayers` package
* `use std::signer` - Imports the signer type for account authentication
* `use std::vector` - For dynamic arrays (inventory system)
* `use std::string` - For human-readable item names
* `use std::option` - For optional values (equipment slots can be empty)
* `use move_slayers::enemies` - Imports our enemy module for combat

### 🏷️ Constants and Type Definitions

```
    const TYPE_SWORD: u8 = 0;
    const TYPE_SHIELD: u8 = 1;
    const TYPE_ARMOR: u8 = 2;
    const TYPE_POTION: u8 = 3;
```

**Explanation:**

* These constants define item types using `u8` (8-bit unsigned integers)
* Using constants instead of magic numbers makes code more readable
* `u8` is memory-efficient for simple enums

### 📦 Item Structure

```
    struct Item has copy, drop, store {
        id: u64,
        name: string::String,
        item_type: u8,
        power: u64,
    }
```

**Explanation:**

* `struct Item` - Defines a custom data type for game items
* `has copy, drop, store` - Move capabilities:
  * `copy`: Can be duplicated (useful for testing)
  * `drop`: Can be discarded (when items are consumed)
  * `store`: Can be stored in global storage (inventory)
* `id: u64` - Unique identifier for each item
* `name: string::String` - Human-readable item name
* `item_type: u8` - References our constants (0=sword, 1=shield, etc.)
* `power: u64` - Effect strength (damage for weapons, heal for potions)

### 👤 Player Structure

```
    struct Player has key {
        level: u8,
        exp: u64,
        health: u64,
        mana: u64,
        max_health: u64,
        max_mana: u64,
        inventory: vector<Item>,
        equipped_sword: option::Option<Item>,
        equipped_shield: option::Option<Item>,
        equipped_armor: option::Option<Item>,
    }
```

**Explanation:**

* `struct Player has key` - Player is a resource stored at an account address
* `has key` - Can be stored as a top-level resource in global storage
* `level: u8` - Player level (1-255, sufficient for most games)
* `exp: u64` - Experience points (64-bit allows for large numbers)
* `health/mana` - Current values
* `max_health/max_mana` - Maximum values (increase with level)
* `inventory: vector<Item>` - Dynamic array of items
* `equipped_*: option::Option<Item>` - Optional equipment slots (can be empty)

### 🎮 Player Initialization

```
    /// Initializes a new player with base stats and empty inventory
    public fun init_player(account: &signer) {
        move_to(account, Player {
            level: 1,
            exp: 0,
            health: 100,
            mana: 50,
            max_health: 100,
            max_mana: 50,
            inventory: vector::empty<Item>(),
            equipped_sword: option::none<Item>(),
            equipped_shield: option::none<Item>(),
            equipped_armor: option::none<Item>(),
        });
    }
```

**Explanation:**

* `public fun` - Function accessible from other modules
* `account: &signer` - Reference to the account that will own the player
* `move_to(account, Player {...})` - Creates and stores the Player resource at the account's address
* `vector::empty<Item>()` - Creates an empty vector to hold items
* `option::none<Item>()` - Creates empty optional values for equipment slots

### 🎒 Inventory Management

```
    /// Adds an item to the player's inventory
    public fun add_item(account: &signer, item: Item) acquires Player {
        let player = borrow_global_mut<Player>(signer::address_of(account));
        vector::push_back(&mut player.inventory, item);
    }
```

**Explanation:**

* `acquires Player` - Tells Move this function will access the Player resource
* `borrow_global_mut<Player>(signer::address_of(account))` - Gets mutable reference to Player resource
* `signer::address_of(account)` - Converts signer to account address
* `vector::push_back(&mut player.inventory, item)` - Adds item to end of inventory

### ⚔️ Equipment System

```
    /// Equips a sword from inventory
    public fun equip_sword(account: &signer, item_id: u64): bool acquires Player {
        let player = borrow_global_mut<Player>(signer::address_of(account));
        equip_specific(&mut player.inventory, item_id, TYPE_SWORD, &mut player.equipped_sword)
    }
```

**Explanation:**

* Returns `bool` - Success/failure of equipping
* `equip_specific()` - Helper function that handles the actual equipping logic
* `TYPE_SWORD` - Ensures only swords can be equipped in this slot

### 🔧 Helper Function: Equipment Logic

```
    /// Helper: equips item of specific type if found in inventory
    fun equip_specific(
        inventory: &mut vector<Item>, 
        item_id: u64, 
        required_type: u8,
        equip_slot: &mut option::Option<Item>
    ): bool {
        let i = 0;
        let len = vector::length(inventory);
        while (i < len) {
            let item_ref = vector::borrow(inventory, i);
            if (item_ref.id == item_id && item_ref.item_type == required_type) {
                let item = vector::remove(inventory, i);
                *equip_slot = option::some(item);
                return true;
            };
            i = i + 1;
        };
        false
    }
```

**Explanation:**

* `fun` (no `public`) - Private helper function
* `&mut vector<Item>` - Mutable reference to inventory
* `while (i < len)` - Manual loop through inventory
* `vector::borrow(inventory, i)` - Gets reference to item at index i
* `vector::remove(inventory, i)` - Removes and returns item at index i
* `*equip_slot = option::some(item)` - Stores item in equipment slot
* Returns `false` if item not found

### 🧪 Potion System

```
    /// Uses a potion to restore health
    public fun use_potion(account: &signer, item_id: u64): bool acquires Player {
        let player = borrow_global_mut<Player>(signer::address_of(account));
        let i = 0;
        let len = vector::length(&player.inventory);
        while (i < len) {
            let item_ref = vector::borrow(&player.inventory, i);
            if (item_ref.id == item_id && item_ref.item_type == TYPE_POTION) {
                let potion = vector::remove(&mut player.inventory, i);
                player.health = min(player.health + potion.power, player.max_health);
                return true;
            };
            i = i + 1;
        };
        false
    }
```

**Explanation:**

* Searches inventory for potion with matching ID
* `min(player.health + potion.power, player.max_health)` - Heals but doesn't exceed max health
* Consumes potion by removing it from inventory
* Returns `true` if potion used, `false` if not found

### ⚔️ Combat System

```
    /// Player attacks an enemy. If enemy survives, it counterattacks. If enemy dies, player gains EXP.
    public fun attack_enemy(account: &signer, enemy: &mut enemies::Enemy): bool acquires Player {
        let player = borrow_global_mut<Player>(signer::address_of(account));

let damage = if (option::is_some(&player.equipped_sword)) {
            let sword_ref = option::borrow(&player.equipped_sword);
            sword_ref.power
        } else {
            5 // base attack
        };

let killed = enemies::take_damage(enemy, damage);

if (killed) {
            slay_enemy(account, enemies::get_exp_reward(enemy));
            true
        } else {
            // Enemy counterattacks
            let attack = enemies::get_attack(enemy);
            if (player.health <= attack) {
                player.health = 0; // player dies
            } else {
                player.health = player.health - attack;
            };
            false
        }
    }
```

**Explanation:**

* `enemy: &mut enemies::Enemy` - Mutable reference to enemy (can modify its health)
* `option::is_some(&player.equipped_sword)` - Checks if sword is equipped
* `option::borrow(&player.equipped_sword)` - Gets reference to equipped sword
* `enemies::take_damage(enemy, damage)` - Calls enemy module to apply damage
* If enemy killed: calls `slay_enemy()` to award EXP
* If enemy survives: enemy counterattacks and damages player

### ⭐ Leveling System

```
    /// Awards EXP for slaying an enemy and handles leveling
    public fun slay_enemy(account: &signer, exp_reward: u64) acquires Player {
        let player = borrow_global_mut<Player>(signer::address_of(account));
        player.exp = player.exp + exp_reward;

let required_exp = exp_required(player.level);
        while (player.exp >= required_exp) {
            player.exp = player.exp - required_exp;
            player.level = player.level + 1;
            player.max_health = player.max_health + 20;
            player.max_mana = player.max_mana + 10;
            player.health = player.max_health;
            player.mana = player.max_mana;
            required_exp = exp_required(player.level);
        };
    }
```

**Explanation:**

* `while (player.exp >= required_exp)` - Handles multiple level-ups at once
* `player.exp = player.exp - required_exp` - Subtracts used EXP
* `player.max_health = player.max_health + 20` - Increases max stats
* `player.health = player.max_health` - Full heal on level up
* `required_exp = exp_required(player.level)` - Recalculates for next level

### 📊 EXP Calculation

```
    /// Returns EXP required to level up (exponential)
    fun exp_required(level: u8): u64 {
        100 * (1u64 << (level - 1))
    }
```

**Explanation:**

* `1u64 << (level - 1)` - Bit shift for exponential growth
* Level 1→2: 100 \* 2^0 = 100 EXP
* Level 2→3: 100 \* 2^1 = 200 EXP
* Level 3→4: 100 \* 2^2 = 400 EXP

### 🛠️ Utility Functions

```
    /// Helper: finds minimum of two values
    fun min(a: u64, b: u64): u64 {
        if (a < b) a else b
    }

/// Helper: finds maximum of two values
    fun max(a: u64, b: u64): u64 {
        if (a > b) a else b
    }
```

**Explanation:**

* Simple utility functions for common operations
* Used in potion healing to prevent exceeding max health

### 🔍 Public Getters

```
    /// Public getters for Player fields
    public fun get_level(player: &Player): u8 { player.level }
    public fun get_exp(player: &Player): u64 { player.exp }
    public fun get_health(player: &Player): u64 { player.health }
    public fun get_mana(player: &Player): u64 { player.mana }
    public fun get_max_health(player: &Player): u64 { player.max_health }
    public fun get_max_mana(player: &Player): u64 { player.max_mana }
```

**Explanation:**

* Read-only access to player stats
* Useful for UI/display purposes
* Follows encapsulation principles

***

## 🐗 Module 2: Enemy System (`sources/enemies.move`)

### 🔧 Module Declaration

```
module move_slayers::enemies {

use std::string;
```

**Explanation:**

* Simple module with just string import for enemy names
* Focused on enemy creation and combat interaction

### 👹 Enemy Structure

```
    /// Enemy definition
    struct Enemy has copy, drop, store {
        name: string::String,
        health: u64,
        attack: u64,
        exp_reward: u64,
    }
```

**Explanation:**

* `has copy, drop, store` - Can be duplicated, discarded, and stored
* `name` - Human-readable enemy name
* `health` - Current health points
* `attack` - Damage dealt when counterattacking
* `exp_reward` - Experience points awarded when killed

### 🐗 Enemy Creation

```
    /// Spawns a weak early-game boar
    public fun spawn_boar(): Enemy {
        Enemy {
            name: string::utf8(b"Boar"),
            health: 30,
            attack: 5,
            exp_reward: 50,
        }
    }
```

**Explanation:**

* `string::utf8(b"Boar")` - Creates string from byte array
* `b"Boar"` - Byte literal syntax
* Balanced stats for early-game progression

### ⚔️ Combat Mechanics

```
    /// Applies damage to the enemy. Returns true if enemy is killed.
    public fun take_damage(enemy: &mut Enemy, amount: u64): bool {
        if (enemy.health <= amount) {
            enemy.health = 0;
            true
        } else {
            enemy.health = enemy.health - amount;
            false
        }
    }
```

**Explanation:**

* `&mut Enemy` - Mutable reference to modify enemy health
* Returns `bool` - Whether enemy was killed
* Sets health to 0 if damage exceeds current health
* Otherwise subtracts damage from health

### 🔍 Public Getters

```
    /// Public getters for Enemy fields
    public fun get_health(enemy: &Enemy): u64 { enemy.health }
    public fun get_attack(enemy: &Enemy): u64 { enemy.attack }
    public fun get_exp_reward(enemy: &Enemy): u64 { enemy.exp_reward }
    public fun get_name(enemy: &Enemy): &string::String { &enemy.name }
```

**Explanation:**

* Read-only access to enemy properties
* `&string::String` - Returns reference to avoid copying

### 🏭 Factory Function

```
    /// Public factory for Enemy (for testing)
    public fun make_enemy(name: string::String, health: u64, attack: u64, exp_reward: u64): Enemy {
        Enemy { name, health, attack, exp_reward }
    }
```

**Explanation:**

* Factory pattern for creating custom enemies
* Useful for testing and future expansion
* Allows creation of different enemy types

***

## 🧪 Testing (`tests/hero_tests.move`)

### 🔧 Test Module Setup

```
#[test_only]
module move_slayers::hero_tests {

use std::signer;
    use std::string;
    use std::vector;
    use std::option;
    use std::account;
    use move_slayers::hero;
    use move_slayers::enemies;
```

**Explanation:**

* `#[test_only]` - Compile-time attribute for test-only code
* `use std::account` - For creating test accounts
* Imports all necessary modules for testing

### 🎯 Test Helper

```
    // Test account addresses
    const PLAYER_ADDR: address = @0x1;

// Test helper: creates a test signer
    fun create_test_signer(): signer {
        account::create_account_for_test(PLAYER_ADDR)
    }
```

**Explanation:**

* `@0x1` - Address literal syntax
* `account::create_account_for_test()` - Creates test account
* Reusable helper for all tests

### ✅ Sample Test

```
    #[test]
    fun test_hero_creation() {
        let player = create_test_signer();
        hero::init_player(&player);
        // Test that player was created successfully by trying to add an item
        let test_item = hero::make_item(1, string::utf8(b"Test Item"), hero::type_sword(), 10);
        hero::add_item(&player, test_item);
    }
```

**Explanation:**

* `#[test]` - Marks function as a test
* Creates player and adds item to verify initialization worked
* Tests basic functionality without explicit assertions

***

## 🚀 Key Learning Points

### 1. **Resource Safety**

* Move's type system prevents common bugs
* Resources can't be accidentally duplicated or lost
* Global storage is type-safe

### 2. **Modular Design**

* Separate modules for different concerns
* Clear interfaces between modules
* Easy to extend and maintain

### 3. **On-Chain State Management**

* Player data stored as resources
* Immutable references for reading
* Mutable references for writing

### 4. **Error Handling**

* Return `bool` for success/failure
* Use `option::Option<T>` for optional values
* Graceful handling of edge cases

### 5. **Testing Best Practices**

* Comprehensive test coverage
* Test-only modules
* Helper functions for common test setup

***

## 🎯 Next Steps

### Ideas for Extension:

1. **More Enemy Types** - Different stats and behaviors
2. **Item Effects** - Shields reduce damage, armor provides defense
3. **Spell System** - Mana-based abilities
4. **Quest System** - Objectives and rewards
5. **Multiplayer** - Player vs player combat
6. **NFT Integration** - Unique items as NFTs

### Advanced Concepts to Explore:

* **Events** - Emit game events for frontend
* **Capabilities** - Fine-grained access control
* **Generics** - Reusable code patterns
* **Abort Codes** - Custom error handling

# Stablecoin Example
URL: /devs/tutorials/stablecoin

<Callout type="warning">
  This code is not audited, if you are building on this code, ensure that you complete an audit before deploying to mainnet.
</Callout>

In this tutorial, we'll build **mFUSD** - a collateralized stablecoin on the Movement Network. This stablecoin maintains a 1:1 peg with USD through over-collateralization with APT tokens.

If you would like to see the finished code, you can find it [here](https://github.com/movement-network/movement-defi-examples).

The finished code also includes a module for a more basic fiat backed stablecoin.

## What You'll Learn

* How to create a fungible asset (FA) token on Movement
* Implementing collateralized debt positions (CDPs)
* Building mint, burn, and liquidation mechanics
* Managing collateral vaults and positions
* Deploying on Movement testnet

## Prerequisites

* Movement CLI installed
* Basic understanding of Move language
* Testnet account with Move tokens

## Core Concepts

### Collateralized Stablecoin Model

mFUSD follows a collateralized debt position (CDP) model:

* Users deposit APT as collateral
* They can mint mFUSD up to a safe collateralization ratio
* Minimum collateralization ratio: 150% (1.5x over-collateralized)
* If positions fall below 150%, they can be liquidated

### Key Components

1. **Fungible Asset (FA)**: The mFUSD token itself
2. **Collateral Vault**: Holds deposited Move tokens
3. **Collateral Positions**: Tracks each user's debt and collateral
4. **Protocol Stats**: Global statistics for monitoring

## Module Structure

### 1. Data Structures

```move
/// Manages minting and burning capabilities
struct Management has key {
    mint_ref: MintRef,
    burn_ref: BurnRef,
    transfer_ref: TransferRef,
}

/// Vault holding all collateral
struct CollateralVault has key {
    move_balance: Coin<AptosCoin>,
}

/// Individual user position
struct CollateralPosition has key {
    collateral_amount: u64,
    minted_amount: u64,
}

/// Global protocol statistics
struct ProtocolStats has key {
    total_collateral: u64,
    total_minted: u64,
}
```

### 2. Constants

```move
const MIN_COLLATERAL_RATIO: u64 = 15000; // 150% in basis points
const BASIS_POINTS: u64 = 10000;
const ASSET_SYMBOL: vector<u8> = b"mFUSD";
```

## Core Functions

### 1. Initialization

```move
fun init_module(admin: &signer) {
    // Create the fungible asset
    let constructor_ref = &object::create_named_object(
        admin,
        ASSET_SYMBOL,
    );
    
    primary_fungible_store::create_primary_store_enabled_fungible_asset(
        constructor_ref,
        option::none(),
        string::utf8(b"Movement USD"),
        string::utf8(ASSET_SYMBOL),
        8, // decimals
        string::utf8(b"https://example.com/mfusd-icon.png"),
        string::utf8(b"https://movementlabs.xyz"),
    );
    
    // Store management capabilities
    let management = Management {
        mint_ref,
        burn_ref,
        transfer_ref,
    };
    
    // Initialize vault and stats
    move_to(admin, management);
    move_to(admin, CollateralVault { move_balance: coin::zero<AptosCoin>() });
    move_to(admin, ProtocolStats { total_collateral: 0, total_minted: 0 });
}
```

### 2. Deposit and Mint

```move
public entry fun deposit_and_mint(
    user: &signer,
    collateral_amount: u64,
    mint_amount: u64
) {
    // Deposit collateral
    let coins = coin::withdraw<AptosCoin>(user, collateral_amount);
    coin::merge(&mut vault.move_balance, coins);
    
    // Create or update position
    if (!exists<CollateralPosition>(user_addr)) {
        move_to(user, CollateralPosition {
            collateral_amount: 0,
            minted_amount: 0,
        });
    }
    
    // Check collateralization ratio
    assert!(is_position_healthy(
        position.collateral_amount + collateral_amount,
        position.minted_amount + mint_amount
    ), EUNDERCOLLATERALIZED);
    
    // Mint mFUSD to user
    let tokens = fungible_asset::mint(&management.mint_ref, mint_amount);
    primary_fungible_store::deposit(user_addr, tokens);
}
```

### 3. Health Check

```move
fun is_position_healthy(collateral: u64, minted: u64): bool {
    if (minted == 0) return true;
    
    let collateral_value_cents = collateral * get_apt_price_in_cents();
    let minted_value_cents = minted * 100; // mFUSD = $1
    let required_collateral_value = (minted_amount * MIN_COLLATERAL_RATIO) / BASIS_POINTS;
    
    collateral_value_cents >= required_collateral_value
}
```

### 4. Liquidation

<Callout type="info">
  Our Contract is using fixed prices and not an oracle. This Liquidation process will not actually take place unless you implement an oracle.
</Callout>

```move
public entry fun liquidate(
    liquidator: &signer,
    user_to_liquidate: address
) {
    // Check if position is unhealthy
    assert!(!is_position_healthy(
        position.collateral_amount,
        position.minted_amount
    ), EUNDERCOLLATERALIZED);
    
    // Liquidator repays debt
    let tokens = fungible_asset::withdraw(liquidator, position.minted_amount);
    fungible_asset::burn(&management.burn_ref, tokens);
    
    // Liquidator receives collateral
    let seized_coins = coin::extract(&mut vault.move_balance, position.collateral_amount);
    coin::deposit(liquidator_addr, seized_coins);
    
    // Clear position
    position.collateral_amount = 0;
    position.minted_amount = 0;
}
```

## Deployment Guide

### 1. Setup Project

```bash
# Initialize project
movement move init --name stablecoin

# Update Move.toml with your address
[addresses]
mfusd = "0xYOUR_ADDRESS_HERE"
```

### 2. Compile and Test

```bash
# Compile the module
movement move compile

# Run tests
movement move test
```

### 3. Deploy to Testnet

```bash
# Deploy
movement move publish
```

# Uniswap V2 AMM Example
URL: /devs/tutorials/uniswap_v2_example

# Movement DeFi: Uniswap V2 AMM Implementation

<Callout type="warning">
  This code is not audited, if you are building on this code, ensure that you complete an audit before deploying to mainnet.
</Callout>

A complete, production-ready Automated Market Maker (AMM) implementation built for Movement. This project demonstrates advanced DeFi mechanics including constant product formula pools, LP token management, and factory registry patterns.

The complete Movement DeFi Examples repository can be found [here](https://github.com/movement-network/movement-defi-examples)

## 🚀 Quick Start

### Prerequisites

* [Movement CLI](https://docs.movementnetwork.xyz/devs/movementcli) installed and configured
* Basic understanding of the Move programming language and DeFi concepts
* Movement testnet account with sufficient funds

### Installation & Setup

1. **Clone the repository:**
   ```bash
   git clone https://github.com/movement-network/movement-defi-examples.git
   cd univ2
   ```

2. **Install dependencies and compile:**
   ```bash
   movement move compile --skip-fetch-latest-git-deps
   ```

3. **Configure your deployment profile and deploy:**
   ```bash
   # Setup and deployment (see Movement CLI docs for profile configuration)
   movement move publish --profile your-profile-name
   ```

## 📚 Educational Overview

This implementation serves as a comprehensive educational resource for understanding AMM mechanics, Move programming patterns, and DeFi protocol design. It's structured to demonstrate real-world smart contract development practices while maintaining educational clarity.

### What You'll Learn

* **AMM Mathematics**: Constant product formula (`x × y = k`) implementation
* **Move Resource Management**: Safe handling of digital assets using Move's ownership model
* **Generic Programming**: Type-safe token pair operations with compile-time guarantees
* **Event-Driven Architecture**: Comprehensive event emission for off-chain indexing
* **Security Patterns**: Slippage protection, access control, and arithmetic safety
* **Gas Optimization**: Efficient storage operations and algorithmic implementations

## 🏗️ Architecture Deep Dive

### Module Dependency Hierarchy

The codebase follows a clean dependency structure that prevents circular dependencies and promotes modularity:

```
errors.move (base layer - no dependencies)
    ↓
math.move (mathematical utilities)
    ↓
lp_token.move (LP token management)
    ↓
pool.move (core AMM logic) 
    ↓
factory.move (pool registry)
```

### Core Components

#### 1. Pool Module (`sources/pool.move`)

The heart of the AMM implementation, handling all liquidity and swap operations.

**Key Functions:**

* `add_liquidity_entry()` - Adds tokens to liquidity pools, mints LP tokens
* `remove_liquidity_entry()` - Burns LP tokens, returns underlying assets
* `swap_x_to_y_entry()` / `swap_y_to_x_entry()` - Token swap operations
* `get_reserves()` - View function for current pool reserves

**Mathematical Foundation:**

```move
// Constant product formula: x × y = k
let new_reserve_x = old_reserve_x + amount_x_in;
let new_reserve_y = (old_reserve_x * old_reserve_y) / new_reserve_x;
let amount_y_out = old_reserve_y - new_reserve_y;
```

**Security Features:**

* Minimum liquidity requirement (1000 tokens burned on first mint)
* Slippage protection via minimum output amounts
* Fee calculation (0.3%) with precision maintenance
* Safe arithmetic operations to prevent overflow

#### 2. Factory Module (`sources/factory.move`)

Manages pool creation and registry, serving as the central coordinator for the AMM ecosystem.

**Key Functions:**

* `initialize()` - Sets up factory with fee recipient configuration
* `create_pool_entry()` - Creates new trading pairs
* `get_pool()` - Retrieves pool information for token pairs
* `all_pools_length()` - Returns total number of created pools

**Design Patterns:**

* Uses `SimpleMap` for efficient O(1) pool lookups
* Maintains ordered type pairs to prevent duplicate pools
* Event emission for off-chain pool discovery

#### 3. Math Module (`sources/math.move`)

Provides essential mathematical utilities with safety guarantees.

**Key Functions:**

* `sqrt()` - Integer square root with overflow protection
* `safe_mul_div()` - Multiplication and division with overflow checks
* `minimum_liquidity()` - Returns the minimum LP tokens burned on first mint

**Safety Guarantees:**

* All operations check for overflow conditions
* Square root handles edge cases (0, 1, large numbers)
* Maintains precision in fee calculations

#### 4. LP Token Module (`sources/lp_token.move`)

Manages liquidity provider tokens using Movement's native coin framework.

**Key Functions:**

* `initialize()` - Creates LP token type for a trading pair
* `mint()` - Issues new LP tokens to liquidity providers
* `burn()` - Destroys LP tokens when removing liquidity
* `get_balance()` / `get_supply()` - Query functions for balances and supply

**Features:**

* Uses Movement's fungible asset framework
* Automatic supply tracking for accurate share calculations
* Generic implementation for any token pair

### Advanced Features

#### Type Ordering System

```move
fun is_ordered<X, Y>(): bool {
    let x_struct_name = type_info::struct_name(&x_type_info);
    let y_struct_name = type_info::struct_name(&y_type_info);
    &x_struct_name < &y_struct_name
}
```

This ensures consistent pool addressing and prevents duplicate pools for the same pair.

#### Event-Driven Architecture

All major operations emit comprehensive events:

* `MintEvent` - Liquidity additions with amounts and recipient
* `BurnEvent` - Liquidity removal with amounts and recipient
* `SwapEvent` - Token swaps with input/output amounts
* `PoolCreatedEvent` - New pool creation with token types

These events enable:

* Off-chain indexing and analytics
* Real-time monitoring and alerting
* Historical transaction analysis
* Integration with external systems

## 🛠️ Complete Tutorial: Build Your Own AMM

### Step 1: Environment Setup

Ensure you have the Movement CLI installed and configured. For installation and profile setup instructions, see the [Movement CLI documentation](https://docs.movementnetwork.xyz/devs/movementcli).

### Step 2: Project Compilation

Navigate to your project directory and compile the contracts:

```bash
# Compile without fetching latest dependencies (for faster builds)
movement move compile --skip-fetch-latest-git-deps

# Alternative: Full compilation with latest dependencies
movement move compile
```

**Understanding the Compilation:**

* Verifies Move syntax and type safety
* Checks module dependencies
* Generates bytecode for deployment
* Validates resource usage patterns

### Step 3: Contract Deployment

Deploy your AMM to the Movement network:

```bash
# Deploy to your configured network
movement move publish --profile my-amm-profile
```

**What Happens During Deployment:**

* Contracts are published to your account address
* Module dependencies are resolved
* Test tokens (TokenA and TokenB) are automatically initialized
* Factory and pool templates become available

### Step 4: Factory Initialization

Initialize the AMM factory with your address as the fee setter:

```bash
movement move run \
  --function-id 'YOUR_ADDRESS::factory::initialize' \
  --args address:YOUR_ADDRESS \
  --profile my-amm-profile
```

**Replace `YOUR_ADDRESS`** with your actual deployment address.

### Step 5: Test Token Setup

Mint test tokens to your account for AMM testing:

```bash
# Mint Token A (1000 tokens)
movement move run \
  --function-id 'YOUR_ADDRESS::token_a::mint_entry' \
  --args address:YOUR_ADDRESS u64:100000000000 \
  --profile my-amm-profile

# Mint Token B (1000 tokens)  
movement move run \
  --function-id 'YOUR_ADDRESS::token_b::mint_entry' \
  --args address:YOUR_ADDRESS u64:100000000000 \
  --profile my-amm-profile
```

**Token Decimals:** All amounts use 8 decimal places (10^8 = 1 token).

### Step 6: Pool Creation

Create a liquidity pool for your token pair:

```bash
movement move run \
  --function-id 'YOUR_ADDRESS::factory::create_pool_entry' \
  --type-args 'YOUR_ADDRESS::token_a::TokenA' 'YOUR_ADDRESS::token_b::TokenB' \
  --profile my-amm-profile
```

**Type Arguments:** Specify the exact token types in the correct order (alphabetically sorted).

### Step 7: Adding Initial Liquidity

Provide initial liquidity to establish the trading pair:

```bash
# Add 100 tokens of each type
movement move run \
  --function-id 'YOUR_ADDRESS::pool::add_liquidity_entry' \
  --type-args 'YOUR_ADDRESS::token_a::TokenA' 'YOUR_ADDRESS::token_b::TokenB' \
  --args u64:10000000000 u64:10000000000 \
  --profile my-amm-profile
```

**Initial Liquidity Math:**

* Sets the initial price ratio (1:1 in this example)
* Mints √(x × y) LP tokens minus minimum liquidity
* Burns 1000 LP tokens permanently (prevents division by zero attacks)

### Step 8: Testing Token Swaps

Execute token swaps to test the AMM functionality:

```bash
# Swap Token A for Token B (1 token input)
movement move run \
  --function-id 'YOUR_ADDRESS::pool::swap_x_to_y_entry' \
  --type-args 'YOUR_ADDRESS::token_a::TokenA' 'YOUR_ADDRESS::token_b::TokenB' \
  --args u64:100000000 u64:90000000 \
  --profile my-amm-profile

# Swap Token B for Token A (1 token input)
movement move run \
  --function-id 'YOUR_ADDRESS::pool::swap_y_to_x_entry' \
  --type-args 'YOUR_ADDRESS::token_a::TokenA' 'YOUR_ADDRESS::token_b::TokenB' \
  --args u64:100000000 u64:90000000 \
  --profile my-amm-profile
```

**Slippage Parameters:**

* First argument: Input amount (100000000 = 1 token)
* Second argument: Minimum output (90000000 = 0.9 tokens, 10% slippage tolerance)

### Step 9: Querying Pool State

Monitor your pool's state using view functions:

```bash
# Check pool reserves and timestamp
movement move view \
  --function-id 'YOUR_ADDRESS::pool::get_reserves' \
  --type-args 'YOUR_ADDRESS::token_a::TokenA' 'YOUR_ADDRESS::token_b::TokenB' \
  --profile my-amm-profile

# Check your LP token balance
movement move view \
  --function-id 'YOUR_ADDRESS::lp_token::get_balance' \
  --type-args 'YOUR_ADDRESS::token_a::TokenA' 'YOUR_ADDRESS::token_b::TokenB' \
  --args address:YOUR_ADDRESS \
  --profile my-amm-profile

# Check total LP token supply
movement move view \
  --function-id 'YOUR_ADDRESS::lp_token::get_supply' \
  --type-args 'YOUR_ADDRESS::token_a::TokenA' 'YOUR_ADDRESS::token_b::TokenB' \
  --profile my-amm-profile
```

### Step 10: Removing Liquidity

Test liquidity removal functionality:

```bash
# Remove small amount (1 LP token)
movement move run \
  --function-id 'YOUR_ADDRESS::pool::remove_liquidity_entry' \
  --type-args 'YOUR_ADDRESS::token_a::TokenA' 'YOUR_ADDRESS::token_b::TokenB' \
  --args u64:100000000 \
  --profile my-amm-profile
```

## 🧪 Testing & Development

### Running Tests

Execute the comprehensive test suite:

```bash
# Run all tests
movement move test

# Run specific test modules
movement move test --filter math_test
movement move test --filter pool_test
movement move test --filter factory_test
movement move test --filter integration_test

# Run with verbose output
movement move test -v
```

### Test Categories

1. **Unit Tests** (`tests/`)
   * Mathematical function accuracy
   * Individual module functionality
   * Edge case handling

2. **Integration Tests**
   * Cross-module interactions
   * End-to-end workflows
   * Real-world scenarios

3. **Security Tests**
   * Overflow protection
   * Access control validation
   * Slippage protection verification

### Development Workflow

```bash
# Standard development cycle
movement move compile && movement move test

# Deploy and test on network
movement move publish --profile your-profile
# ... run integration tests
```

## 🔒 Security Considerations

### Arithmetic Safety

**Overflow Protection:**

```move
public fun safe_mul_div(a: u64, b: u64, c: u64): u64 {
    assert!(c > 0, errors::division_by_zero());
    let result = ((a as u128) * (b as u128)) / (c as u128);
    assert!(result <= (U64_MAX as u128), errors::mul_div_overflow());
    (result as u64)
}
```

**Key Safety Measures:**

* All multiplication/division uses 128-bit intermediate calculations
* Explicit overflow checks before casting to smaller types
* Square root implementation handles edge cases properly
* Fee calculations maintain precision while preventing manipulation

### Access Control

**Factory Administration:**

* Fee recipient changes require proper signer authorization
* Pool creation is permissionless but validated
* No privileged operations in core pool functionality

**Resource Protection:**

* Move's ownership model prevents resource duplication
* Explicit resource transfers with clear ownership
* No external access to internal pool resources

### MEV Protection

**Slippage Protection:**

* All swaps require minimum output amount specification
* Deadline enforcement prevents transaction replay attacks
* Price impact is predictable via constant product formula

**Front-Running Mitigation:**

* Atomic operations prevent sandwich attacks within single transaction
* Transparent pricing removes information asymmetries
* Gas-efficient operations reduce MEV extraction opportunities

## ⚡ Performance & Optimization

### Gas Efficiency

**Storage Optimization:**

* Minimal storage operations per transaction
* Efficient data structures (SimpleMap for O(1) lookups)
* Event-based state tracking for off-chain queries

**Algorithmic Efficiency:**

* Square root uses Newton's method for optimal convergence
* Fee calculations avoid repeated division operations
* Batch operations where possible to reduce transaction costs

### Memory Management

**Resource Lifecycle:**

* Explicit resource creation and destruction
* Move's automatic memory management prevents leaks
* Efficient handling of temporary calculations

## 🚀 Advanced Features & Extensions

### Multi-Hop Router (Future Enhancement)

A multi-hop routing system could be implemented to enable swaps through multiple pools:

```move
// Future: Multi-hop swap execution
public entry fun execute_swap_path<X, Y>(
    account: &signer,
    path: vector<TypeInfo>,
    amount_in: u64,
    amount_out_min: u64,
    deadline: u64
) {
    // Implementation needed - would iterate through pools
    // and execute sequential swaps for optimal pricing
}
```

### Price Oracle Integration

Framework for TWAP (Time-Weighted Average Price) implementation:

```move
struct PriceOracle<phantom X, phantom Y> has key {
    price_cumulative_last_x: u128,
    price_cumulative_last_y: u128,
    last_update_timestamp: u64,
}
```

### Fee Tier Support

Extension point for multiple fee tiers:

```move
const FEE_TIER_LOW: u64 = 5;     // 0.05%
const FEE_TIER_MEDIUM: u64 = 30; // 0.30%  
const FEE_TIER_HIGH: u64 = 100;  // 1.00%
```

## 🛣️ Future Development Roadmap

This AMM provides a solid foundation that developers can extend with additional DeFi features:

### Routing & Optimization

* **Multi-Hop Router** - Enable swaps through multiple pools for better pricing
* **Path Optimization** - Algorithms to find optimal swap routes automatically
* **MEV Protection** - Advanced slippage protection and transaction ordering

### Oracle & Pricing

* **TWAP Integration** - Time-weighted average price feeds for accurate market data
* **External Oracle Support** - Integration with Chainlink or other price feed providers
* **Dynamic Fee Adjustment** - Fee tiers that adjust based on market volatility

### Advanced Features

* **Flash Loans** - Uncollateralized lending within single transactions
* **Concentrated Liquidity** - UniswapV3-style position management for capital efficiency
* **Limit Orders** - Advanced order types beyond simple market swaps
* **Fee Tier Variety** - Multiple fee levels (0.05%, 0.3%, 1%) for different scenarios

### Governance & Management

* **Protocol Governance** - Decentralized parameter management and upgrades
* **Fee Distribution** - Automated protocol fee collection and distribution
* **Emergency Controls** - Circuit breakers and pause functionality

### Cross-Chain & Scaling

* **Multi-Chain Deployment** - Deploy on multiple Movement-compatible networks
* **Bridge Integration** - Cross-chain liquidity aggregation
* **Layer 2 Optimization** - Gas efficiency improvements and batch operations

# M1 Architecture
URL: /general/l1/architecture

M1 is designed as a high-performance, native Move blockchain with a modular architecture that separates concerns while maintaining tight integration for optimal performance. This document covers the high-level system architecture, while detailed implementation of individual node components is covered in the [Node-Level Architecture](/general/l1/node-level-architecture).

## Core Layers

The M1 architecture is organized into five core layers, each handling specific aspects of the blockchain system while working together to provide a complete, high-performance platform. This high-level architecture is implemented through individual nodes that follow the same five-layer structure, as detailed in the [node-level architecture](/general/l1/node-level-architecture) documentation.

```
┌─────────────────────────────────────────────────────────────────┐
│                           M1 Network                            │
├─────────────────────────────────────────────────────────────────┤
│  Application Layer                                              │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                │
│  │    DeFi     │ │    NFTs     │ │ Enterprise  │                │
│  │    DApps    │ │   Games     │ │   Apps      │                │
│  └─────────────┘ └─────────────┘ └─────────────┘                │
├─────────────────────────────────────────────────────────────────┤
│  1. API Layer                                                   │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                │
│  │  REST API   │ │ WebSocket   │ │   GraphQL   │                │
│  │  Endpoints  │ │   Events    │ │   Queries   │                │
│  └─────────────┘ └─────────────┘ └─────────────┘                │
├─────────────────────────────────────────────────────────────────┤
│  2. Execution Layer                                             │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                │
│  │   MoveVM    │ │ Transaction │ │   State     │                │
│  │  Runtime    │ │  Pipeline   │ │ Management  │                │
│  └─────────────┘ └─────────────┘ └─────────────┘                │
├─────────────────────────────────────────────────────────────────┤
│  3. Storage Layer                                               │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                │
│  │   Merkle    │ │   Account   │ │  Transaction│                │
│  │    Trees    │ │    Store    │ │   History   │                │
│  └─────────────┘ └─────────────┘ └─────────────┘                │
├─────────────────────────────────────────────────────────────────┤
│  4. Consensus Layer                                             │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                │
│  │   Leader    │ │  Validator  │ │    BFT      │                │
│  │  Selection  │ │   Network   │ │  Consensus  │                │
│  └─────────────┘ └─────────────┘ └─────────────┘                │
├─────────────────────────────────────────────────────────────────┤
│  5. Network Layer                                               │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                │
│  │   P2P       │ │  Mempool    │ │  Message    │                │
│  │  Protocol   │ │  Management │ │  Routing    │                │
│  └─────────────┘ └─────────────┘ └─────────────┘                │
└─────────────────────────────────────────────────────────────────┘
```

### 1. API Layer

#### REST API

The REST API provides ***standard endpoints*** for common blockchain operations, enabling ***direct resource queries*** to Move resources and ***secure transaction submission*** for broadcasting. The API supports ***state inspection*** and querying capabilities. For real-time data access, applications must implement polling mechanisms using these REST endpoints.

#### WebSocket Events

Nodes do not provide WebSocket endpoints for real-time block or event streaming at this point. For real-time data access, applications must use polling via RPC endpoints or utilize third-party indexer services.

#### GraphQL Interface

The GraphQL interface enables ***flexible queries*** for complex multi-resource operations, providing ***type-safe query construction*** through schema definition and supporting ***efficient data aggregation*** and computation. The system includes ***query result caching*** for performance optimization.

### 2. Execution Layer

#### Move Virtual Machine (MoveVM)

The MoveVM provides ***native execution*** of Move bytecode, featuring ***precise gas metering*** that accounts for instruction, storage, and payload costs. It enforces ***type safety*** through Move's static and dynamic safety checks, including resource ownership rules, and ensures ***sandboxing*** by isolating transaction execution within the VM environment.

#### Transaction Pipeline

The transaction pipeline enables ***parallel processing*** through [Block-STM](https://arxiv.org/abs/2203.06871), which applies ***dynamic dependency resolution*** to detect read/write conflicts and order transactions consistently. The system supports ***speculative execution*** with optimistic parallel execution, where transactions may be aborted and re-executed as needed, and Block-STM guarantees that transactions are only ***committed in deterministic order*** once all prior dependencies are finalized.

#### State Management

State management maintains a ***consistent global state view*** of all account and resource data. It integrates with [Block-STM](https://arxiv.org/abs/2203.06871) to provide ***deterministic commit ordering*** of state changes. For performance, it uses ***in-memory buffering and caching*** during execution. Finalized state updates are written through ***efficient serialization*** and stored in ***authenticated data structures***, ensuring both persistence and verifiability.

### 3. Storage Layer

#### Account Store

The account store implements ***address-based*** direct mapping from addresses to account data, providing ***native storage*** of Move resources with ***optimized access patterns*** for common operations. The system includes ***state data compression*** for storage efficiency.

#### Merkle Trees

Merkle trees provide a ***cryptographic state root*** commitment to global state, enabling ***efficient proof generation*** for state verification and supporting ***incremental updates*** with minimal computation for state changes. The system ensures ***fast verification*** of state transitions.

#### Transaction History

Transaction history maintains a ***complete ledger*** with full history of all transactions, featuring ***efficient indexing*** for querying by various criteria and ***optional pruning*** of historical data for storage optimization. The system provides an ***immutable audit trail*** of all state changes.

### 4. Consensus Layer

#### Byzantine Fault Tolerant (BFT) Consensus

The BFT consensus mechanism uses a ***modified HotStuff-based algorithm*** designed for high throughput, providing ***safety*** guarantees that ensure consistency even with up to 1/3 malicious validators. The system maintains ***liveness*** by ensuring progress under network asynchrony, while delivering ***single-slot finality*** for fast transaction confirmation.

#### Validator Network

The validator network operates on a ***proof-of-stake*** model that enables energy-efficient validation through token staking, featuring a ***dynamic set*** where validators can join or leave based on their stake and performance. The system implements ***regular leader rotation*** for decentralization and includes ***slashing*** mechanisms that impose penalties for malicious or negligent behavior.

#### Leader Selection

Leader selection employs a ***deterministic*** approach with cryptographically verifiable selection that is ***weighted*** based on validator stake, ensuring ***fair*** distribution and preventing leader monopolization while maintaining ***efficient*** operation with minimal computational overhead.

### 5. Network Layer

#### Peer-to-Peer Protocol

The peer-to-peer protocol implements a ***gossip network*** for efficient information dissemination, featuring ***automatic peer discovery*** of network participants and ***robust connection management*** with handling and recovery capabilities. The system includes ***cryptographic message authentication*** for verification.

#### Mempool

The mempool manages ***pending transactions*** in a transaction pool, implementing ***priority-based ordering*** for transaction selection and providing ***spam protection*** against malicious transactions. The system includes ***broadcast optimization*** for efficient transaction propagation.

## Security Architecture

#### Cryptographic Primitives

The system employs ***Ed25519 digital signatures*** for transaction authentication, ***SHA-3 hash functions*** for data integrity and commitments, and ***efficient Merkle proofs*** for state and transaction verification. The architecture includes ***verifiable random beacons*** for leader selection.

#### Access Control

Access control implements an ***address-based account model*** with ***Move's resource ownership model*** for asset safety, featuring ***fine-grained permission systems*** for management and ***multi-signature support*** for transaction authorization.

#### Network Security

Network security provides ***DDoS protection*** against network attacks, implements ***rate limiting*** to prevent resource exhaustion, and ensures ***cryptographic validator authentication*** for identity verification. The system includes ***slashing conditions*** that create economic incentives for honest behavior.

## Performance Characteristics

#### Throughput

The system targets ***10,000+ transactions per second*** with ***burst capacity*** for higher throughput during brief periods. Future development includes ***horizontal scaling through sharding*** and ***continuous performance optimization*** for sustained improvements.

#### Latency

The system achieves ***1-2 second block production*** with ***single-block finality*** and ***sub-second transaction confirmation***. The architecture minimizes ***network propagation delay*** for optimal performance.

#### Storage

Storage management implements ***bounded state growth*** through pruning mechanisms, ***configurable history retention*** for transaction data, and ***efficient data compression*** techniques. The system includes ***long-term archival solutions*** for data preservation.

## Governance and Upgrades

#### On-Chain Governance

On-chain governance implements a ***structured proposal system*** for governance mechanisms, featuring ***token-weighted voting*** on protocol changes and ***automatic execution*** of approved proposals. The system includes ***emergency procedures*** with fast-track processes for critical issues.

#### Protocol Upgrades

Protocol upgrades feature ***coordinated version management*** for updates, maintaining ***backward compatibility*** where possible and providing ***automated migration tools*** for existing state. The process includes ***comprehensive testing*** before mainnet deployment.

# Overview
URL: /general/l1

import React from 'react';

M1 (Movement L1) is a native Move blockchain that provides high-throughput execution through the MoveVM.

## Documentation

* **[What is M1](/general/l1/what-is-movement-l1)** - Learn about M1 components and capabilities
* **[Move Language](/general/l1/move-language)** - High level overview of the Move Language
* **[M1 Architecture](/general/l1/architecture)** - Detailed architecture of M1
* **[Node-Level Architecture](/general/l1/node-level-architecture)** - Detailed node-level architecture and components
* **[Node Operations](/general/l1/nodes)** - Information about running M1 nodes
* **[Staking and Delegation](/general/l1/staking)** - Understanding staking states, delegation pools, and reward distribution
* **[M1 Whitepaper](/general/l1/protocol-specification)** - Whitepaper for M1
* **[MiCA Whitepaper](/general/l1/mica-whitepaper)** - Movement's MiCA compliance whitepaper

## Networks

M1 currently operates:

* **[Mainnet](/general/networks/mainnet)** - The production network serving real economic value
* **[Testnet](/general/networks/testnet)** - Production-ready testing environment

## Whitepaper

For further information about M1, please refer to our [M1 Whitepaper](/general/l1/protocol-specification).

# MiCA Whitepaper
URL: /general/l1/mica-whitepaper

The MiCA (Markets in Crypto-Assets) whitepaper outlines Movement's approach to regulatory compliance under the European Union's MiCA framework.

<a href="/mica-whitepaper.pdf" target="_blank" rel="noopener noreferrer">
  Read the full MiCA Whitepaper
</a>

# Move Language
URL: /general/l1/move-language

Move is a safe and secure programming language designed by Facebook for smart contracts that emphasize ownership and safety. Assets in Move are represented as resources. Owing to Move's strong ownership model and explicit resource abilities, Move simplifies the development of safe smart contracts for common blockchain tasks such as transferring ownership of assets, minting, and destroying.

The chart below compares common non-Move runtimes against Aptos and Sui Move runtimes, underscoring the different models and benefits of Move.

|                           | Aptos / Move                                                 | Solana / SeaLevel                                           | EVM                                                        | Sui / Move                            |
| ------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------- |
| **Data storage**          | Stored at a global address or within the owner's account     | Stored within the owner's account associated with a program | Stored within the account associated with a smart contract | Stored at a global address            |
| **Parallelization**       | Capable of inferring parallelization at runtime within Aptos | Requires specifying all data accessed                       | Currently serial, nothing in production                    | Requires specifying all data accessed |
| **Transaction safety**    | Sequence number                                              | Transaction uniqueness                                      | Nonces, similar to sequence numbers                        | Transaction uniqueness                |
| **Type safety**           | Module structs and generics                                  | Program structs                                             | Contract types                                             | Module structs and generics           |
| **Function calling**      | Static dispatch                                              | Static dispatch                                             | Dynamic dispatch                                           | Static dispatch                       |
| **Authenticated Storage** | Yes                                                          | No                                                          | Yes                                                        | No                                    |
| **Object accessibility**  | Guaranteed to be globally accessible                         | Not applicable                                              | Not applicable                                             | Can be hidden                         |

# Node-Level Architecture
URL: /general/l1/node-level-architecture

This document provides a detailed view of the internal architecture of M1 nodes, covering the various components, their interactions, and the data flows within a single node instance. For the high-level system architecture and network design, see [M1 Architecture](/general/l1/architecture).

## Core Layers

The M1 node architecture is organized into five core layers, each handling specific aspects of node functionality while working together to provide a complete, high-performance blockchain node. These layers correspond directly to the [M1 Architecture](/general/l1/architecture) but focus on the internal implementation details of individual nodes rather than the overall system design.

```
┌─────────────────────────────────────────────────────────────────────┐
│                            M1 Node                                  │
├─────────────────────────────────────────────────────────────────────┤
│  1. API Layer                                                       │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                    │
│  │   RPC/API   │ │  WebSocket  │ │   Metrics   │                    │
│  │   Server    │ │   Server    │ │   Exporter  │                    │
│  └─────────────┘ └─────────────┘ └─────────────┘                    │
├─────────────────────────────────────────────────────────────────────┤
│  2. Storage Layer                                                   │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │
│  │   State     │ │ Transaction │ │   Event     │ │   Config    │    │
│  │   Store     │ │    Store    │ │   Store     │ │   Store     │    │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘    │
├─────────────────────────────────────────────────────────────────────┤
│  3. Execution Layer                                                 │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                    │
│  │ Transaction │ │   Executor  │ │ State Cache │                    │
│  │  Validator  │ │   Engine    │ │   Manager   │                    │
│  └─────────────┘ └─────────────┘ └─────────────┘                    │
├─────────────────────────────────────────────────────────────────────┤
│  4. Consensus Layer                                                 │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │
│  │  Consensus  │ │   Voting    │ │   Leader    │ │   Safety    │    │
│  │   Engine    │ │   Module    │ │  Election   │ │   Module    │    │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘    │
├─────────────────────────────────────────────────────────────────────┤
│  5. Network Layer                                                   │
│  ┌─────────────┐ ┌─────────────┐                                    │
│  │   P2P Net   │ │   Mempool   │                                    │
│  │   Handler   │ │   Manager   │                                    │
│  └─────────────┘ └─────────────┘                                    │
└─────────────────────────────────────────────────────────────────────┘
```

### 1. API Layer

#### RPC/API Server

The RPC/API Server provides external API access to node functionality.
The RPC/API Server provides ***transaction submission*** endpoints for submitting signed transactions to the network, ***state queries*** for querying account states and resource data, ***block information*** retrieval for block and transaction data, and ***network status*** endpoints for getting node and network health information. For real-time data access, applications must implement polling mechanisms using these RPC endpoints.

#### WebSocket Server

Nodes do not provide WebSocket endpoints for real-time block or event streaming at this point. The WebSocket Server component is not available for external clients. For real-time data access, applications must use polling via RPC endpoints or utilize third-party indexer services.

#### Metrics Exporter

The Metrics Exporter exports node performance and health metrics.
It tracks ***performance metrics*** including transaction throughput, latency, and CPU usage, ***network metrics*** such as peer count, message rates, and bandwidth usage, ***storage metrics*** covering database size, disk I/O, and cache hit rates, and ***consensus metrics*** including participation rates and voting statistics.

### 2. Storage Layer

#### State Store

The State Store provides persistent storage of global blockchain state. It supports ***efficient read operations*** with Merkle proofs for state queries, ***atomic write operations*** with versioning for state updates, ***proof generation*** for cryptographic proofs of state, and ***state synchronization*** to sync state with other nodes.

#### Transaction Store

The Transaction Store stores the complete transaction history and metadata

#### Event Store and Indexing

The Event Store provides indexing ***by event key*** for fast queries of specific event streams, ***by type*** to query events by Move type, ***by transaction*** to find all events from a specific transaction, and ***by block*** to retrieve all events from a block.

#### Configuration Store

The Configuration Store stores node configuration and network parameters.
The Configuration Store manages ***network configuration*** for peer discovery and connection limits, ***consensus configuration*** for voting timeouts and block limits, ***execution configuration*** for gas prices and resource limits, and ***API configuration*** for rate limits and authentication settings.

### 3. Execution Layer

#### Transaction Validator

The Transaction Validator validates transaction signatures, format, and basic checks in the following steps:

1. **Signature Verification**: Cryptographic signature validation
2. **Format Checking**: Transaction structure and field validation
3. **Sequence Validation**: Account sequence number verification
4. **Gas Validation**: Gas price and limit verification
5. **Balance Checking**: Sufficient balance for transaction fees

#### Executor Engine

The Executor Engine executes validated transactions using the MoveVM and through the following pipeline:

1. **Transaction Preparation**: Load account states and dependencies
2. **MoveVM Execution**: Execute Move bytecode in sandboxed environment
3. **State Updates**: Apply changes to global state
4. **Event Generation**: Generate events for state changes
5. **Gas Accounting**: Calculate and charge gas fees

#### State Cache Manager

The State Cache Manager manages in-memory caching of frequently accessed state.
The State Cache Manager maintains an ***account cache*** for recently accessed account states, a ***resource cache*** for frequently queried Move resources, a ***module cache*** for compiled Move module bytecode, and a ***Merkle cache*** for recently computed Merkle tree nodes.

### 4. Consensus Layer

#### Consensus Engine

The Consensus Engine coordinates the Byzantine Fault Tolerant consensus protocol through the following flow:

1. **Block Proposal**: Leader proposes a block containing transactions and a Quorum Certificate (QC) for its parent.
2. **Voting Phase**: Validators verify the proposal and cast ***vote messages***.
3. **QC Formation**: Votes are aggregated into a ***Quorum Certificate*** attesting to the block's validity.
4. **Block Commit**: Once a 3-chain of consecutive certified blocks is formed, the earliest block in the chain is ***finalized*** and added to the ledger.

#### Voting Module

The Voting Module handles vote creation, validation, aggregation, and timeout votes for liveness. It has the following vote types:

* ***block vote***: validator’s signature attesting to a proposed block.
* ***timeout vote***: issued if no valid proposal is received in time, can aggregate into a Timeout Certificate (TC) to trigger a new leader view.

#### Leader Election

The Leader Election determines which validator proposes the next block.
The Leader Election uses ***weighted selection*** with probability proportional to validator stake, ensuring ***deterministic*** selection where the same leader is chosen by all honest validators. The algorithm implements ***regular rotation*** to prevent centralization and guarantees ***liveness*** with progress even when some validators are offline.

#### Safety Module

The Safety Module ensures consensus safety properties are maintained.
The Safety Module performs ***conflicting vote detection*** to prevent double voting, ***fork detection*** to identify potential blockchain forks, ***slashing evidence*** collection for malicious behavior, and implements ***recovery mechanisms*** to handle network partitions and attacks.

### 5. Network Layer

#### P2P Network Handler

The P2P Network Handler manages peer-to-peer communication with other nodes.
The P2P Network Handler consists of a ***connection manager*** that establishes and maintains connections to peers, a ***message router*** that routes incoming messages to appropriate handlers, a ***gossip protocol*** that implements efficient information dissemination, and ***peer discovery*** mechanisms that discover and connect to new network peers.

#### Mempool Manager

The Mempool Manager manages pending transactions before consensus.
The Mempool Manager includes a ***transaction pool*** for in-memory storage of pending transactions, a ***priority queue*** that orders transactions by gas price and priority, a ***spam filter*** that prevents spam and invalid transactions, and an ***expiration manager*** that removes expired transactions.

## Node Types and Specialization

#### Validator Nodes

Validator nodes provide ***active consensus participation*** in block production, performing ***state validation*** by verifying all state transitions and contributing to ***network security*** through staking mechanisms. These nodes participate in ***protocol governance*** decisions and include ***full consensus participation*** with complete consensus engine activation, ***block production*** capabilities for proposing and creating blocks, ***validator key management*** for secure storage of validator keys, and ***slashing protection*** against slashing conditions.

#### Full Nodes

Full nodes maintain ***complete state synchronization*** of the blockchain state, providing ***transaction relay*** services that forward transactions to the validator network and offering ***API services*** with endpoints for applications. These nodes ensure ***data availability*** for network participants and are configured with ***complete state synchronization*** for state replication, ***full API services*** with complete endpoint availability, ***real-time event streaming*** for notifications, and ***mempool participation*** for transaction relay and validation.

#### Light Nodes

Light nodes implement ***selective synchronization*** by syncing only relevant account data, performing ***proof verification*** without maintaining full state and achieving ***resource efficiency*** with minimal storage and bandwidth requirements. These nodes provide ***mobile support*** optimized for mobile and embedded devices, with ***reduced storage*** requirements and ***bandwidth optimization*** through efficient data transfer protocols.

## Performance Optimization

#### Caching Strategies

Performance optimization employs ***LRU cache*** with Least Recently Used eviction for hot data, ***write-through cache*** for consistent caching with persistent storage, ***bloom filters*** for fast negative lookups of non-existent data, and ***data compression*** for storage and network transfer efficiency.

#### Parallel Processing

The system implements ***transaction parallelization*** for concurrent execution of independent transactions, ***I/O parallelization*** through asynchronous disk and network operations, ***multi-threading*** for CPU-intensive operations on multiple cores, and ***pipeline processing*** to overlap computation and I/O operations.

#### Resource Management

Resource management includes ***memory pools*** with pre-allocated memory for frequent operations, ***connection pooling*** to reuse database and network connections, ***efficient garbage collection*** for cleanup of temporary data, and ***rate limiting*** to prevent resource exhaustion from excessive load.

## Monitoring and Diagnostics

#### Health Checks

Health checks monitor ***network connectivity*** for peer connection status, ***consensus participation*** including voting and block production rates, ***storage health*** for database integrity and performance, and ***resource utilization*** covering CPU, memory, and disk usage.

#### Logging and Tracing

The system implements ***structured logging*** with machine-readable log formats, ***distributed tracing*** for request tracing across components, ***performance metrics*** with detailed timing and throughput data, and ***comprehensive error tracking*** for error collection and analysis.

#### Debugging Tools

Debugging tools provide ***state inspection*** capabilities for examining blockchain state, ***transaction simulation*** for testing transaction execution, ***network analysis*** to analyze peer connections and message flow, and ***performance profiling*** to identify performance bottlenecks.

# M1 백서
URL: /general/l1/protocol-specification-ko

> 이 문서는 [M1 백서(영문)](/general/l1/protocol-specification)의 한국어 번역본입니다. 원문 제목: *M1 Whitepaper* · 번역일: 2026-06-11

## 초록

M1(Movement L1)은 Move 프로그래밍 언어의 잠재력을 온전히 실현하기 위해 구축된 블록체인 인프라입니다. M1은 탈중앙화 애플리케이션, 온체인 금융, 디지털 네이티브 조직을 위한 안전하고 리소스 지향적인 기반을 제공합니다.

성능과 안전성을 넘어, M1은 단순한 전제 위에 설계되었습니다. 기술은 사용자의 역량을 확장해야 합니다. M1은 글로벌 모바일 우선 경제에 열린 참여, 공동 소유권, 검증 가능한 신뢰라는 가치를 회복하기 위해 존재합니다.

이 문서는 Move의 효율성과 접근성 및 커뮤니티 소유권에 기반한 설계 철학을 결합한 사람 중심의 레이어 1 네트워크인 M1의 동기, 원칙, 상위 수준 아키텍처를 설명합니다.

***

## 1. 소개

### 1.1 배경

블록체인 생태계는 확장성, 보안, 탈중앙화 사이의 긴장을 해결하려는 반복적인 시도를 거치며 발전해 왔습니다. 각 세대의 네트워크는 진전을 이루었지만, 성능과 개방성 사이의 트레이드오프는 계속 남아 있었습니다. 그 결과 오늘날의 환경은 혁신만큼이나 분절성으로 정의됩니다. 이는 종종 사용자가 아니라 자본에 최적화된 특화 시스템들의 집합입니다.

Diem 프로젝트를 위해 처음 개발된 Move 프로그래밍 언어는 이러한 흐름에서 분명한 전환점을 제시합니다. 리소스 지향 설계, 타입 안전성, 형식 검증은 Move를 검증 가능한 금융 시스템 구축에 특히 적합하게 만듭니다. M1은 이 비전을 프로토콜 계층 자체로 확장하여, 기술적으로 견고하면서도 그 네트워크에 의존하는 커뮤니티와 사회적으로 정렬된 네트워크를 만듭니다.

### 1.2 비전과 동기

Movement는 접근성, 커뮤니티 참여, 지속 가능한 온체인 경제에 새롭게 초점을 맞추며 Move 기반 블록체인 인프라의 진화를 이어갑니다. 목표는 기존 기반을 더 포용적이고 목적 지향적인 네트워크로 정교하게 발전시키는 것입니다.

현대 블록체인은 성공을 TVL이나 수수료 같은 시장 지표로 주로 측정하는 경우가 많습니다. Movement는 그 초점을 사용자 영향으로 되돌립니다. 즉, 네트워크가 사람들이 만들고, 벌고, 조율하도록 얼마나 효과적으로 힘을 부여하는지에 집중합니다. Movement는 성숙한 기술을 실제 커뮤니티를 위한 열린 인프라로 전환합니다.

주권적 레이어 1은 이러한 방향을 가능하게 합니다. Movement는 자체 L1을 운영함으로써 경제 모델, 거버넌스, 조율 메커니즘을 포용성과 회복탄력성에 맞춰 설계할 수 있습니다. 예를 들어 검증자를 통해 지역 허브로 가치를 흘러가게 할 수 있습니다. 그 결과 커뮤니티 규모의 애플리케이션, 의미 있는 커뮤니티 참여, 실물자산, 모바일 네이티브 금융에 최적화된 네트워크가 됩니다. 이는 투기보다 사용성과 공동의 이익을 우선하는 시스템입니다.

### 1.3 지침 원칙

Movement의 개발은 시스템의 모든 계층에 영향을 주는 몇 가지 타협 불가능한 원칙에 의해 추진됩니다.

1. **사람 우선**: 기술은 사용자의 능력을 확장해야 하며, 가두어서는 안 됩니다.
2. **인프라로서의 커뮤니티**: 탈중앙화는 기술적일 뿐 아니라 사회적입니다.
3. **엣지에서의 접근성**: 다음 10억 명의 사용자는 모바일, 개발도상 환경, 제한된 대역폭 환경에서 올 것입니다.
4. **목적 있는 조합성**: 프로토콜과 애플리케이션은 고립된 사일로가 아니라 일관된 경제적 메시로 상호 연결되어야 합니다.
5. **투기보다 지속 가능성**: 가치는 빌더, 검증자, 커뮤니티 사이를 순환하며 장기 성장을 위한 안정적 기반을 형성해야 합니다.

### 1.4 애플리케이션과 생태계

M1은 온체인 금융부터 디지털 신원 및 조율 시스템까지 폭넓은 탈중앙화 애플리케이션을 지원하는 범용 레이어 1로 설계되었습니다. M1의 아키텍처는 조합성, 검증 가능성, 예측 가능한 성능을 강조하여 개발자가 안전성이나 접근성을 희생하지 않고 구축할 수 있게 합니다.

네트워크의 초점은 투기적 활동이 아니라 실제 효용에 있습니다. Movement의 설계에서 가장 큰 이점을 얻는 애플리케이션은 다음과 같습니다.

* **탈중앙화 금융 및 자산 발행**: 투명성과 검증 가능한 실행이 필수적인 시장, 결제 레일, 신용 시스템.
* **실물자산 통합**: Movement 네트워크에서 운영되는 인가 금융기관은 유형 자산의 표현을 토큰화하여, 소유권과 수익을 수탁 기관에 집중시키는 대신 규정을 준수하고 투명한 방식으로 커뮤니티에 분배할 수 있습니다.
* **모바일 네이티브 경험**: 사용자가 어떤 기기에서든 직접 거래하고 상호작용할 수 있게 하는 경량 클라이언트와 지갑.
* **신원 및 평판 프레임워크**: 신뢰, 기여 이력, 거버넌스 참여를 온체인에서 확립하기 위한 시스템.
* **커뮤니티 주도 거버넌스와 조율**: 이해관계자가 제안하고, 투표하고, 집단적 결정을 안전하게 실행할 수 있게 하는 메커니즘.

이러한 범주는 Movement 생태계가 지향하는 형태를 정의합니다. 즉, 애플리케이션이 경제적 가치를 인간의 기여와 정렬시키는 실용적이고 검증 가능한 네트워크입니다.

### 1.5 M1 설계 철학

M1은 사회-기술 시스템입니다. M1의 목적은 또 하나의 토큰 시장을 만드는 것이 아니라, 조율과 소유권을 위한 지속 가능한 프레임워크를 구축하는 것입니다. 네트워크는 검증, 거버넌스, 개발, 교육에 이르는 모든 기여를 가치의 구성 요소로 봅니다.

이런 의미에서 Movement는 제품이라기보다 공공 유틸리티에 가깝습니다. 노력은 가치로, 기여는 소유권으로, 참여는 집단적 힘으로 전환되는 시스템입니다.

### 1.6 M1 핵심 기능

M1은 다음 핵심 기능을 구현합니다.

1. **Move 런타임**: 블록체인 실행을 위한 MoveVM 구현.
2. **고처리량 합의**: 부하 상황에서 확장하기 위한 Jolteon 계열 및 Quorum Store와 유사한 전파 계층.
3. **병렬 실행**: 처리량 증가를 위한 트랜잭션 병렬화.
4. **상태 관리**: 상태 저장 및 관리 솔루션.
5. **개발자 도구**: 개발 환경 및 디버깅 도구.

## 2. 기술 아키텍처

### 2.1 시스템 개요

M1은 블록체인 운영의 여러 측면을 처리하는 별도 계층을 가진 모듈형 아키텍처를 사용합니다.

```
애플리케이션 계층 │ DApps, DeFi, NFTs, 엔터프라이즈 애플리케이션
API 계층          │ REST, WebSocket, Indexer GraphQL 인터페이스
실행 계층         │ MoveVM 런타임, 트랜잭션 처리
스토리지 계층     │ 상태 저장소, 트랜잭션 이력, 이벤트
합의 계층         │ BFT 합의, 검증자 네트워크
네트워크 계층     │ P2P 통신, 멤풀 관리, 메시지 라우팅
```

### 2.2 합의 프로토콜

#### 2.2.1 Jolteon

M1은 [Jolteon](https://arxiv.org/abs/2106.10362) 스타일의 BFT 프로토콜을 채택합니다. Jolteon은 지연 시간을 줄이고 빠른 복구를 보장하기 위해 2-chain 커밋 규칙과 이차적 뷰 변경(pacemaker)을 도입합니다. 정상 경로에서는 한 라운드 확인으로 선형 메시지 복잡도를 달성하며, 스트레스 상황에서도 견고성을 유지합니다.

프로토콜은 최대 1/3의 비잔틴 검증자까지 일관성을 통해 \_**안전성**\_을 보장하고, 네트워크 비동기성 하에서도 진행을 통해 \_**활성성**\_을 보장하며, 빠른 확인을 위한 2-chain 커밋으로 \_**최종성**\_을 제공하고, 최적화된 메시지 복잡도와 라운드 지속 시간으로 \_**효율성**\_을 유지합니다.

#### 2.2.2 검증자 선택

네트워크는 지분에 비례하여 검증자 선택 확률이 결정되는 ***가중 선택*** 방식의 Proof-of-Stake(PoS)를 사용합니다. 검증자는 지분과 성과에 따라 참여하거나 이탈할 수 있는 \_**동적 집합**\_을 구성하며, 정직한 검증과 블록 생산에 대해 스테이킹 \_**보상**\_을 받습니다. (참고: 슬래싱은 프로토콜에 정의되어 있으나 현재 활성화되어 있지 않습니다.)

#### 2.2.3 블록 생산

블록 생산은 결정론적 리더 선택 알고리즘을 따릅니다.

```rust
// Note: This is a simplified pseudocode representation.
// Deterministic, stake/reputation-weighted round-robin (illustrative)
fn select_leader(set: &ValidatorSet, round: u64) -> ValidatorId {
let order = set.weighted_order_by_stake_and_rep(); // fixed per epoch
order[(round as usize) % order.len()]
}
```

#### 2.2.4 데이터 전파

Quorum Store 스타일의 전파를 사용합니다. 이는 트랜잭션 전파와 순서 지정을 분리하여 버스트성 부하에서 처리량을 안정화합니다. 낮은 부하에서는 최소 지연 시간을 위해 우회할 수 있습니다.

### 2.3 Move 가상 머신

#### 2.3.1 런타임 최적화

M1의 MoveVM 구현에는 검증된 바이트코드를 사용하는 ***최적화된 인터프리터***, 반복 실행을 위해 컴파일된 바이트코드를 캐싱하는 ***명령 캐싱***, 정밀한 가스 계량과 최소 오버헤드를 갖춘 ***가스 최적화***, 효율적인 메모리 할당과 가비지 컬렉션을 갖춘 \_**메모리 관리**\_가 포함됩니다.

#### 2.3.2 보안 기능

MoveVM은 이중 지출과 리소스 누수를 방지하는 ***리소스 안전성***, 컴파일 시점 및 런타임 타입 검사를 통한 ***타입 안전성***, 세밀한 권한 관리를 통한 ***접근 제어***, 컨트랙트 정확성의 수학적 증명을 위한 ***형식 검증*** 지원 등 내장 보안 보장을 제공합니다.

#### 2.3.3 병렬 실행

의존성이 허용하는 경우 트랜잭션 실행은 병렬화될 수 있습니다(**Block-STM** 접근 방식).

```rust
// Note: This is a simplified pseudocode representation.
struct ParallelExecutor {
    worker_pool: ThreadPool,
    dependency_graph: DependencyAnalyzer,
    conflict_detector: ConflictDetector,
}

impl ParallelExecutor {
    fn execute_batch(&self, transactions: Vec<Transaction>) -> Vec<ExecutionResult> {
        let dependency_groups = self.dependency_graph.analyze(&transactions);
        let results = dependency_groups.par_iter()
            .map(|group| self.execute_group(group))
            .collect();
        self.resolve_conflicts(results)
    }
}
```

### 2.4 상태 관리

#### 2.4.1 글로벌 상태 모델

M1은 계정 주소별로 구성된 글로벌 상태를 유지합니다. 각 주소가 여러 리소스와 모듈을 보유할 수 있는 ***계정 모델***, Move 리소스 및 타입 정보의 네이티브 저장을 위한 ***리소스 스토리지***, 메타데이터가 포함된 컴파일된 Move 모듈을 위한 ***모듈 스토리지***, 원장 버전별로 인덱싱되는 \_**버전 관리 상태**\_를 사용하며, Jellyfish Merkle Tree를 통해 인증된 증명을 제공합니다.

#### 2.4.2 Jellyfish Merkle Tree(JMT)

M1은 상태 커밋을 위해 Jellyfish Merkle Tree를 사용합니다. 이 구조는 효율적인 상태 증명을 가능하게 하고, 라이트 클라이언트와 풀 노드를 위한 확장 가능한 검증을 지원합니다.

```
State Root (Jellyfish Merkle Tree)
├── Account Subtree
│   ├── Address_1 → {Resources, Modules}
│   ├── Address_2 → {Resources, Modules}
│   └── ...
├── Events Subtree
│   ├── Event_Stream_1 → [Event_1, Event_2, ...]
│   └── ...
└── Metadata Subtree
    ├── Validator Set
    ├── Network Configuration
    └── ...
```

#### 2.4.3 스토리지 최적화

여러 최적화가 스토리지 효율성을 개선합니다. 여기에는 오래된 상태 버전 제거를 위한 ***상태 프루닝***(설정 가능), 데이터 저장 및 전송을 위한 ***RocksDB 수준 압축***, 일반적인 쿼리 패턴을 위한 효율적 ***인덱싱***, 자주 접근되는 데이터를 위한 다단계 \_**캐싱**\_이 포함됩니다.

### 2.5 네트워크 프로토콜

#### 2.5.1 P2P 통신

네트워크 통신은 가십 기반 프로토콜을 사용합니다. 여기에는 네트워크 피어의 자동 발견 및 연결을 위한 ***피어 디스커버리***, 메시지 유형과 우선순위에 따른 효율적 라우팅을 위한 ***메시지 라우팅***, 네트워크 메시지의 압축 및 배칭을 통한 ***대역폭 최적화***, 암호학적 인증과 메시지 무결성을 통한 \_**보안**\_이 포함됩니다.

#### 2.5.2 트랜잭션 전파

트랜잭션 전파는 낮은 지연 시간에 맞춰 최적화됩니다.

1. **클라이언트 제출**: 트랜잭션이 네트워크의 어느 노드로든 제출됩니다.
2. **초기 검증**: 기본 검증이 수행됩니다(서명, 형식, 잔액).
3. **멤풀 삽입**: 유효한 경우 로컬 멤풀에 추가됩니다.
4. **가십 프로토콜**: 연결된 피어로 전파됩니다.
5. **합의 포함**: 다음 블록에 포함되도록 선택됩니다.

## 3. 경제 모델

### 3.1 토크노믹스

#### 3.1.1 MOVE 토큰

네이티브 MOVE 토큰은 여러 목적을 수행합니다. 여기에는 트랜잭션 실행 및 저장소 비용 지불을 위한 ***트랜잭션 수수료***, 검증자 스테이킹과 네트워크 보안을 위한 ***스테이킹***, 프로토콜 업그레이드와 매개변수에 대한 투표를 위한 ***거버넌스***, 검증자와 네트워크 참여자에게 지급되는 \_**보상 인센티브**\_가 포함됩니다.

#### 3.1.2 토큰 분배

#### 3.1.3 수수료 구조

트랜잭션 수수료는 리소스 소비를 기준으로 계산됩니다.

```rust
// Note: This is a simplified pseudocode representation.
// Fee model: gas unit price × gas used, minus storage refund
struct GasSchedule {
    instruction_costs: HashMap<Opcode, Gas>,
    storage_costs: StorageGasSchedule,
}

fn calculate_fee(gas_used: Gas, gas_unit_price: Octa, storage_refund: Octa) -> Fee {
    gas_used * gas_unit_price - storage_refund
}
```

#### 3.1.4 스테이킹 메커니즘

검증자 스테이킹은 다음 원칙을 따릅니다. 검증자 참여를 위한 ***최소 지분*** 요건, 토큰 보유자가 검증자에게 지분을 위임할 수 있는 ***위임***, 지분과 성과에 비례한 ***보상***, 그리고 프로토콜에는 정의되어 있으나 2025년 기준 메인넷에서는 활성화되지 않은 \_**슬래싱**\_이 포함됩니다.

#### 3.1.5 수수료 및 스테이킹 보상 흐름

스테이커와 위임 스테이커는 Reward-and-Gas-Pool에서 보상을 받습니다.

이 풀에는 두 가지 유입 흐름이 있습니다. 첫째, 수수료가 직접 풀로 수집되어 지속 가능한 보상 모델을 위한 자연스러운 경로를 만듭니다. 둘째, 풀은 정기적으로 보충되는 스테이킹 보상 트레저리로부터 자금을 공급받습니다.

네트워크 보안을 강화하기 위해 스테이킹 보상 트레저리는 지분을 위임합니다. 보상은 트레저리로 반환되기 때문에 유통 공급량에 기여하지 않으며, 런웨이를 줄이지도 않습니다. 트레저리로 반환된 보상은 풀의 수명도 늘려 장기적으로 더 지속 가능한 모델을 추진합니다. 스테이킹 보상 트레저리가 Reward-and-Gas-Pool로의 지급을 통해 시간이 지나며 감소하기 때문에, 거버넌스와 운영에 대한 트레저리의 영향력도 시간이 지나며 감소합니다.

이 설계에는 두 가지 장점이 있습니다. 첫째, 부트스트래핑 기간 동안 트레저리는 네트워크에 중요한 보안을 제공합니다. 둘째, 네트워크와 토큰 분배가 성숙해짐에 따라 이러한 부트스트래핑 풀의 필요성은 낮아지고, 지속적인 감소는 커뮤니티의 완전한 소유권으로 가는 길을 점진적으로 엽니다.

### 3.2 거버넌스 모델

#### 3.2.1 온체인 거버넌스

거버넌스 결정은 온체인 투표를 통해 이루어집니다. 여기에는 이해관계자가 거버넌스 제안을 제출할 수 있는 ***제안 제출***, 활성 제안에 대한 시간 제한 투표를 위한 ***투표 기간***, 승인된 제안의 자동 \_**실행**\_이 포함됩니다.

#### 3.2.2 매개변수 관리

핵심 네트워크 매개변수는 거버넌스를 통해 조정될 수 있습니다. 여기에는 기본 가스 가격과 수수료 구조를 위한 ***가스 가격***, 블록 크기와 시간 및 트랜잭션 한도를 위한 ***블록 매개변수***, 최소 지분과 보상률 및 슬래싱 조건을 위한 ***스테이킹 매개변수***, 검증자 집합 크기와 합의 타임아웃을 위한 \_**네트워크 구성**\_이 포함됩니다.

## 4. 보안 분석

### 4.1 위협 모델

#### 4.1.1 네트워크 공격

다양한 네트워크 수준 공격에 대한 보호가 포함됩니다. 여기에는 속도 제한과 트래픽 분석을 통한 ***DDoS 공격*** 대응, 피어 다양성과 연결 관리를 통한 ***이클립스 공격*** 대응, Proof-of-Stake와 신원 검증을 통한 ***시빌 공격*** 대응, 체크포인팅과 약한 주관성을 이용한 ***장거리 공격*** 대응이 포함됩니다.

#### 4.1.2 합의 공격

합의 수준 공격에 대한 보호 장치에는 이중 투표에 대한 경제적 페널티를 통한 ***nothing-at-stake*** 방지, 높은 경제적 비용과 증명 가능한 악의적 행위 페널티를 통한 ***슈퍼메이저리티(투표권 2/3 이상 장악)*** 억제, 결정론적 지분 가중 리더 스케줄을 통한 ***그라인딩 및 리더 조작*** 감소, 투표 책임성과 악의적 행위 증명을 통한 ***뇌물 공격*** 방지가 포함됩니다.

#### 4.1.3 스마트 컨트랙트 보안

Move 언어 기능은 스마트 컨트랙트 보안을 강화합니다. 여기에는 이중 지출과 자산 복제를 방지하는 ***리소스 모델***, 일반적인 취약점을 컴파일 시점에 방지하는 ***타입 안전성***, 세밀한 권한 및 capability 시스템을 통한 ***접근 제어***, 컨트랙트 정확성의 수학적 증명을 위한 ***형식 검증*** 지원이 포함됩니다.

### 4.2 암호학적 프리미티브

#### 4.2.1 디지털 서명

M1은 트랜잭션 인증을 위해 Ed25519 서명을 사용합니다. 이는 트랜잭션 승인 증명을 위한 ***트랜잭션 인증***, 합의 투표 인증을 위한 ***검증자 서명***, P2P 메시지 인증을 위한 ***메시지 무결성***, Multi-Ed25519 임계값 방식을 통한 \_**다중 서명**\_을 제공합니다.

#### 4.2.2 해시 함수

SHA-3(Keccak)는 시스템 전반에서 사용됩니다. \_**블록 해싱**\_에서는 고유한 블록 식별을 위해 사용되고, \_**Jellyfish Merkle Tree**\_에서는 인증된 상태 및 트랜잭션 커밋을 위해 사용됩니다. 합의는 결정론적 리더 선택을 사용하며, 작업증명이나 랜덤 비콘은 없습니다.

### 4.3 감사 및 검증

#### 4.3.1 코드 감사

정기적인 독립 보안 감사는 시스템 무결성을 보장합니다. 감사 범위에는 합의 및 네트워킹 컴포넌트를 포함한 ***핵심 프로토콜***, 가상 머신 및 실행 엔진을 위한 ***MoveVM 구현***, 모든 암호학 구현을 위한 ***암호학 라이브러리***, 시스템 컨트랙트와 모듈을 포함한 \_**스마트 컨트랙트**\_가 포함됩니다.

#### 4.3.2 형식 검증

중요 컴포넌트의 수학적 검증에는 기반 Jolteon 프로토콜의 일관성에 대한 형식 증명을 통한 ***합의 안전성***, Move Prover를 통한 언어 안전 속성의 자동 검증을 포함한 \_**Move 의미론**\_이 포함됩니다. 인센티브 경제와 거버넌스 기반 업그레이드는 동일한 수준의 형식 증명 대상이 아닙니다.

## 5. 개발 생태계

### 5.1 개발자 도구

#### 5.1.1 Movement CLI

종합적인 명령줄 인터페이스입니다.

```bash
# Note: This is a simplified pseudocode representation.
# Create new Move project
movement init my-project

# Compile Move modules
movement build

# Deploy to testnet
movement deploy --network testnet

# Run local testnet
movement node run-local

# Interact with deployed contracts
movement call --function transfer --args 0x123 100
```

#### 5.1.2 IDE 통합

널리 쓰이는 개발 환경을 지원합니다.

* **VS Code 확장**: 구문 강조, 디버깅, IntelliSense.
* **IntelliJ 플러그인**: 고급 기능을 포함한 완전한 IDE 지원.
* **Language Server**: 편집기 통합을 위한 Language Server Protocol.
* **Web IDE**: 브라우저 기반 개발 환경.

#### 5.1.3 테스트 프레임워크

종합적인 테스트 인프라입니다.

```move
// Note: This is a simplified pseudocode representation.
#[test]
public fun test_transfer() {
    let sender = @0x1;
    let receiver = @0x2;
    let amount = 100;

// Setup test environment
    let state = create_test_state();

// Execute transfer
    let result = transfer(sender, receiver, amount);

// Verify results
    assert!(result.success, 1);
    assert!(balance_of(receiver) == amount, 2);
}
```

***

*이 프로토콜 명세는 살아 있는 문서이며, M1이 계속 발전하고 성숙함에 따라 업데이트될 예정입니다.*

# M1 Whitepaper
URL: /general/l1/protocol-specification

## Abstract

M1 (Movement L1) is a blockchain infrastructure built to realize the full potential of the Move programming language. It provides a secure, resource-oriented foundation for decentralized applications, on-chain finance, and digitally native organizations.

Beyond performance and safety, M1 is designed around a simple premise: technology should empower its users. It exists to restore the values of open participation, shared ownership, and verifiable trust to a global, mobile-first economy.

This document outlines the motivation, principles, and high-level architecture of M1 - a people-centered Layer 1 network that unites the efficiency of Move with a design philosophy grounded in accessibility and community ownership.

***

## 1. Introduction

### 1.1 Background

The blockchain ecosystem has evolved through repeated attempts to resolve the tension between scalability, security, and decentralization. Each generation of networks made progress, yet the trade-offs between performance and openness have persisted. The result is a landscape defined as much by fragmentation as by innovation — a collection of specialized systems often optimized for capital, not users.

The Move programming language, originally developed for the Diem project, represents a clean break from that trend. Its resource-oriented design, type safety, and formal verification make it uniquely suited for building verifiable financial systems. M1 extends this vision to the protocol layer itself, creating a network that is both technically robust and socially aligned with the community that depends on it.

### 1.2 Vision and Motivation

Movement continues the evolution of Move-based blockchain infrastructure with a renewed focus on accessibility, community participation, and sustainable on-chain economies. Its aim is to refine existing foundations toward a more inclusive and purposeful network.

Modern blockchains often measure success primarily through market metrics such as TVL or fees. Movement shifts that focus back to user impact — to how effectively a network can empower people to build, earn, and coordinate. It transforms mature technology into open infrastructure for a real community.

A sovereign Layer 1 enables this direction. By operating its own L1, Movement can shape its economics, governance, and coordination mechanisms around inclusivity and resilience — for instance, by driving value to regional hubs through its validators. The result is a network optimized for community-scale applications, meaningful community participation, real-world assets, and mobile-native finance — a system that prioritizes usability and shared benefit over speculation.

### 1.3 Guiding Principles

Movement's development is driven by a small set of non-negotiable principles that inform every layer of the system:

1. **People first** : technology should expand agency, not enclose it.
2. **Community as infrastructure** : decentralization is not only technical; it is social.
3. **Accessibility at the edge** : the next billion users will come from mobile, developing, and bandwidth-limited environments.
4. **Composability with purpose** : protocols and applications should interconnect into a coherent economic mesh rather than isolated silos.
5. **Sustainability over speculation** : value should circulate between builders, validators, and community, forming a stable foundation for long-term growth.

### 1.4 Applications and Ecosystem

M1 is designed as a general-purpose Layer 1 that supports a wide spectrum of decentralized applications, from on-chain finance to digital identity and coordination systems. Its architecture emphasizes composability, verifiability, and predictable performance, allowing developers to build without compromising safety or accessibility.

The network's focus is on real utility rather than speculative activity. Applications that benefit most from Movement's design include:

* **Decentralized finance and asset issuance** : markets, payment rails, and credit systems where transparency and verifiable execution are essential.
* **Real-world asset integration** : Accredited financial institutions operating on the Movement network can tokenize representations of tangible assets, enabling ownership and yield to be distributed among the community in a compliant and transparent manner, rather than concentrated in custodial entities.
* **Mobile-native experiences** : lightweight clients and wallets enabling users to transact and interact directly from any device.
* **Identity and reputation frameworks** : systems for establishing trust, contribution history, and governance participation on-chain.
* **Community-driven governance and coordination** : mechanisms that allow stakeholders to propose, vote, and execute collective decisions securely.

Together, these categories define the intended shape of the Movement ecosystem: a practical, verifiable network where applications align economic value with human contribution.

### 1.5 M1 Design Philosophy

M1 is a social-technical system. Its purpose is not to create another marketplace for tokens but to establish a durable framework for coordination and ownership. The network treats every contribution — from validation to governance to development to education — as a building block of value.

In this sense, Movement is less a product than a public utility: a system where effort converts into value, contribution into ownership, and participation into collective strength.

### 1.6 M1 Key Features

M1 implements the following key features:

1. **Move Runtime**: MoveVM implementation for blockchain execution.
2. **High-Throughput Consensus**: Jolteon lineage and a Quorum Store–like dissemination layer for scaling under load.
3. **Parallel Execution**: transaction parallelization for increased throughput.
4. **State Management**: state storage and management solutions.
5. **Developer Tooling**: development environment and debugging tools.

## 2. Technical Architecture

### 2.1 System Overview

M1 employs a modular architecture with distinct layers handling different aspects of blockchain operation:

```
Application Layer    │ DApps, DeFi, NFTs, Enterprise Applications
API Layer            │ REST, WebSocket, Indexer GraphQL Interfaces
Execution Layer      │ MoveVM Runtime, Transaction Processing
Storage Layer        │ State Store, Transaction History, Events
Consensus Layer      │ BFT Consensus, Validator Network
Network Layer        │ Peer-to-peer communication, Mempool management, Message routing
```

### 2.2 Consensus Protocol

#### 2.2.1 Jolteon

M1 adopts a [Jolteon](https://arxiv.org/abs/2106.10362)-style BFT protocol. Jolteon introduces a 2-chain commit rule and a quadratic view change (pacemaker) to reduce latency and ensure fast recovery. In the happy path it achieves linear message complexity with one-round confirmations; under stress it remains robust.

The protocol guarantees ***safety*** with consistency up to 1/3 Byzantine validators, ensures ***liveness*** with progress under network asynchrony, provides ***finality*** through 2-chain commit for fast confirmations, and maintains ***efficiency*** with optimized message complexity and round duration.

#### 2.2.2 Validator Selection

The network employs Proof-of-Stake (PoS) with ***weighted selection*** where validator selection probability is proportional to stake, a ***dynamic set*** allowing validators to join/leave based on stake and performance, and ***rewards*** with staking rewards for honest validation and block production. (Note: slashing is defined in protocol but not currently active.)

#### 2.2.3 Block Production

Block production follows a deterministic leader selection algorithm:

#### 2.2.4 Data Dissemination

Quorum Store–style dissemination: separate transaction dissemination from ordering to stabilize throughput under bursty load; bypass under low load for minimal latency.

### 2.3 Move Virtual Machine

#### 2.3.1 Runtime Optimization

M1's MoveVM implementation includes an ***optimized interpreter*** with verified bytecode, ***instruction caching*** for caching of compiled bytecode for repeated execution, ***gas optimization*** with precise gas metering and minimal overhead, and ***memory management*** with efficient memory allocation and garbage collection.

#### 2.3.2 Security Features

The MoveVM provides built-in security guarantees including ***resource safety*** to prevent double-spending and resource leaks, ***type safety*** with compile-time and runtime type checking, ***access control*** with fine-grained permission management, and ***formal verification*** support for mathematical proof of contract correctness.

#### 2.3.3 Parallel Execution

Transaction execution can be parallelized when dependencies allow (**Block-STM** approach):

### 2.4 State Management

#### 2.4.1 Global State Model

M1 maintains a global state organized by account addresses using an ***account model*** where each address can hold multiple resources and modules, ***resource storage*** with native storage of Move resources and type information, ***module storage*** for compiled Move modules with metadata, and ***versioned state*** indexed by ledger version, with authenticated proofs via the Jellyfish Merkle Tree.

#### 2.4.2 Jellyfish Merkle Tree (JMT)

State commitment uses the Jellyfish Merkle Tree:

M1 uses a Jellyfish Merkle Tree for state commitment. This structure enables efficient proofs of state and supports scalable verification for light clients and full nodes.

#### 2.4.3 Storage Optimization

Several optimizations improve storage efficiency including ***state pruning*** for removal of old state versions (configurable), ***RocksDB-level compression*** for data storage and transfer, ***indexing*** with efficient indexing for common query patterns, and ***caching*** with multi-level caching for frequently accessed data.

### 2.5 Network Protocol

#### 2.5.1 Peer-to-Peer Communication

Network communication uses a gossip-based protocol with ***peer discovery*** for automatic discovery and connection to network peers, ***message routing*** for efficient routing of messages based on type and priority, ***bandwidth optimization*** through compression and batching of network messages, and ***security*** with cryptographic authentication and message integrity.

#### 2.5.2 Transaction Propagation

Transaction propagation is optimized for low latency:

1. **Client Submission**: Transaction submitted to any network node
2. **Initial Validation**: Basic validation (signature, format, balance)
3. **Mempool Insertion**: Addition to local mempool if valid
4. **Gossip Protocol**: Propagation to connected peers
5. **Consensus Inclusion**: Selection for inclusion in next block

## 3. Economic Model

### 3.1 Tokenomics

#### 3.1.1 MOVE Token

The native MOVE token serves multiple purposes including ***transaction fees*** for payment of transaction execution and storage, ***staking*** for validator staking and network security, ***governance*** for voting on protocol upgrades and parameters, and ***incentives*** for rewards to validators and network participants.

#### 3.1.2 Token Distribution

#### 3.1.3 Fee Structure

Transaction fees are calculated based on resource consumption:

fn calculate_fee(gas_used: Gas, gas_unit_price: Octa, storage_refund: Octa) -> Fee {
    gas_used * gas_unit_price - storage_refund
}
```

#### 3.1.4 Staking Mechanism

Validator staking follows these principles including ***minimum stake*** requirements for validator participation, ***delegation*** allowing token holders to delegate stake to validators, ***rewards*** with proportional rewards based on stake and performance, and ***slashing*** defined in protocol but not active on mainnet as of 2025.

#### 3.1.5 Fee and Staking reward flow

Stakers (and delegated stakers) receive rewards from the Reward-and-Gas-Pool.

This pool has two inflow streams. First, fees are collected directly into the pool, paving a natural way for a sustainable reward model. Second, the pool is funded by the staking reward treasury, which refills regularly.

To enhance the security of the network, the staking reward treasury delegates stakes. Since rewards are returned to the treasury, this does not contribute to the circulating supply, nor does it reduce runway. The rewards returned to the treasury also add to the longevity of the pool, driving a more sustainable model long term. Since the staking reward treasury reduces over time through payouts to the Reward-and-Gas-Pool, the treasury's influence on governance and operation will also reduce over time.

This design has two advantages. First, in the bootstrapping period, the treasury provides critical security to the network. Second, as the network and token distribution mature, the necessity for such a bootstrapping pool becomes less important, and its continuous reduction gradually opens the path to full ownership by the community.

### 3.2 Governance Model

#### 3.2.1 On-Chain Governance

Governance decisions are made through on-chain voting with ***proposal submission*** allowing stakeholders to submit governance proposals, ***voting periods*** with time-bounded voting on active proposals, and ***execution*** with automatic execution of approved proposals.

#### 3.2.2 Parameter Management

Key network parameters can be adjusted through governance including ***gas prices*** for base gas price and fee structure, ***block parameters*** for block size, time, and transaction limits, ***staking parameters*** for minimum stake, reward rates, and slashing conditions, and ***network configuration*** for validator set size and consensus timeouts.

## 4. Security Analysis

### 4.1 Threat Model

#### 4.1.1 Network Attacks

Protection against various network-level attacks includes ***DDoS attacks*** with rate limiting and traffic analysis, ***eclipse attacks*** through peer diversity and connection management, ***sybil attacks*** via Proof-of-Stake and identity verification, and ***long-range attacks*** using checkpointing and weak subjectivity.

#### 4.1.2 Consensus Attacks

Safeguards against consensus-level attacks include ***nothing-at-stake*** protection with economic penalties for equivocation, ***supermajority (≥ 2/3 voting-power capture)*** deterrence through high economic cost and provable misbehavior penalties, ***grinding and leader manipulation*** reduction via a deterministic stake-weighted leader schedule, and ***bribe attacks*** prevention through accountability of votes and misbehavior proofs.

#### 4.1.3 Smart Contract Security

Move language features enhance smart contract security through a ***resource model*** that prevents double-spending and asset duplication, ***type safety*** with compile-time prevention of common vulnerabilities, ***access control*** with fine-grained permission and capability systems, and ***formal verification*** support for mathematical proofs of contract correctness.

### 4.2 Cryptographic Primitives

#### 4.2.1 Digital Signatures

M1 uses Ed25519 signatures for ***transaction authentication*** providing proof of transaction authorization, ***validator signatures*** for consensus vote authentication, ***message integrity*** for P2P message authentication, and ***multi-signatures*** via Multi-Ed25519 threshold schemes.

#### 4.2.2 Hash Functions

SHA-3 (Keccak) is used throughout the system for ***block hashing*** with unique block identification and in the ***Jellyfish Merkle Tree*** for authenticated state and transaction commitments. Consensus uses deterministic leader selection; there is no proof-of-work or random beacon.

### 4.3 Audit and Verification

#### 4.3.1 Code Audits

Regular independent security audits ensure system integrity covering the ***core protocol*** including consensus and networking components, ***MoveVM implementation*** for the virtual machine and execution engine, ***cryptographic libraries*** for all cryptographic implementations, and ***smart contracts*** including system contracts and modules.

#### 4.3.2 Formal Verification

Mathematical verification of critical components includes ***consensus safety*** with formal proofs of consistency for the underlying Jolteon protocol and ***Move semantics*** with automated verification of language safety properties through the Move Prover. Incentive economics and governance-driven upgrades are not subject to the same level of formal proof.

## 5. Development Ecosystem

### 5.1 Developer Tools

#### 5.1.1 Movement CLI

Comprehensive command-line interface:

```bash
# Note: This is a simplified pseudocode representation.
# Create new Move project
movement init my-project

# Compile Move modules
movement build

# Deploy to testnet
movement deploy --network testnet

# Run local testnet
movement node run-local

# Interact with deployed contracts
movement call --function transfer --args 0x123 100
```

#### 5.1.2 IDE Integration

Support for popular development environments:

* **VS Code Extension**: Syntax highlighting, debugging, IntelliSense
* **IntelliJ Plugin**: Full IDE support with advanced features
* **Language Server**: Language Server Protocol for editor integration
* **Web IDE**: Browser-based development environment

#### 5.1.3 Testing Framework

Comprehensive testing infrastructure:

```move
// Note: This is a simplified pseudocode representation.
#[test]
public fun test_transfer() {
    let sender = @0x1;
    let receiver = @0x2;
    let amount = 100;

// Setup test environment
    let state = create_test_state();

// Execute transfer
    let result = transfer(sender, receiver, amount);

// Verify results
    assert!(result.success, 1);
    assert!(balance_of(receiver) == amount, 2);
}
```

***

*This protocol specification is a living document and will be updated as M1 continues to evolve and mature.*

# Staking and Delegation
URL: /general/l1/staking

This document explains how staking and delegation work on M1, including stake lifecycle states, delegation pools, reward distribution, and the synchronization mechanism.

## Stake States (Lifecycle)

Staked tokens progress through different states during their lifecycle:

**State Descriptions**

* **pending\_active** — Just deposited; will become active next epoch
* **active** — Earning staking rewards
* **pending\_inactive** — Delegator requested unlock; waiting for lockup to expire. Still earns rewards during the lockup duration!
* **inactive** — Lockup expired; can be withdrawn

**Key point:** `pending_inactive` still earns rewards until the lockup period ends.

## Shares vs Tokens: How Delegation Pools Work

When staking to a delegation pool, delegators receive **SHARES** rather than holding tokens directly. Shares represent proportional ownership of the pool's total token balance.

**Key Definitions**

* **SHARES** — Unit of ownership in the pool (delegator shares count stays constant)
* **SHARE PRICE** — `total_tokens / total_shares` (increases as rewards accumulate)
* **VALUE** — `shares × share_price` (a delegator's stake worth in TOKEN)

**What Happens to a Delegator After Rewards**

* Delegator shares count stays constant (e.g., 100 shares → 100 shares)
* But share PRICE increases (e.g., 1.00 → 1.05 TOKEN/SHARE)
* So delegator VALUE increases (100 × 1.00 = 100 TOKEN → 100 × 1.05 = 105 TOKEN)

See [The Gap](#the-gap) section for a detailed example showing how 5.5 tokens total rewards (5 tokens to user after 0.5 token commission) result in a share price increase from 1.0 to 1.05 TOKEN/SHARE.

**Reward Distribution Process**

When the pool earns staking rewards:

1. **Commission deducted** — The operator's commission percentage is calculated from the gross rewards.
2. **Remainder added to pool** — The net rewards (after commission) are added to `total_tokens` while `total_shares` remains constant, causing the share price to increase.
3. **Operator mints new shares** — The operator uses their commission to buy shares at the new (post-appreciation) share price.

This ordering ensures the operator cannot benefit from appreciation on rewards they didn't earn.

**Benefits**

* O(1) gas cost for reward distribution
* Proportional allocation without per-account calculations
* Reduced rounding errors

## Architecture: StakePool and DelegationPool

These are two separate structs stored at the same address (the resource account address):

### StakePool

A separate struct holding actual tokens. Earns rewards from consensus. Can only have ONE owner (the delegation pool's resource account).

**Fields:**

| Field              | What it contains                     | Earns rewards |
| ------------------ | ------------------------------------ | ------------- |
| `active`           | Stake participating in consensus     | ✅ Yes         |
| `pending_active`   | Added this epoch, active next epoch  | ❌ No          |
| `pending_inactive` | Unlocked, waiting to be withdrawable | ✅ Yes         |
| `inactive`         | Ready to withdraw                    | ❌ No          |

**Total stake** = `active` + `pending_active` + `pending_inactive` + `inactive`

### DelegationPool

The main struct that tracks ownership via shares. Contains `pool_u64::Pool` instances (generic share-tracking pools) that map delegator addresses to their share balances.

**Shares Pools:**

1. **active\_shares** (`pool_u64::Pool`)
   * Tracks: `StakePool.active` + `StakePool.pending_active`
   * One pool for all active stake

2. **inactive\_shares** (`Table<ObservedLockupCycle, pool_u64::Pool>`)
   * Tracks: `StakePool.pending_inactive` (until lockup expires)
   * One pool per lockup cycle
   * When lockup ends, `pending_inactive` → `inactive`

**Why Two Types of Shares Pools?**

* **Different lifecycles:** active can receive deposits; pending\_inactive cannot
* **Multiple lockup cycles:** each cycle has its own pending\_inactive pool
* **Divergent share prices:** slashing could affect one pool but not the other
* **Withdrawal timing:** only pending\_inactive becomes withdrawable after lockup

**Why Two Structs?**

A StakePool supports only one owner. The DelegationPool wraps it to allow multiple delegators, tracking each person's ownership via shares inside `pool_u64::Pool` instances.

Think: StakePool = vault with cash. DelegationPool = ledger of who owns what percentage of that cash.

## Synchronization and the Gap

The delegation pool uses **lazy synchronization** — no automatic sync at epoch end.

**What Triggers Sync**

* ✅ `add_stake()` — User adding stake
* ✅ `unlock()` — User unlocking stake
* ✅ `withdraw()` — User withdrawing
* ✅ `synchronize_delegation_pool()` — Anyone can call (public)
* ❌ Epoch ends — no automatic sync

**At Epoch End**

1. Rewards go to `StakePool.active` and `StakePool.pending_inactive`
2. `DelegationPool` shares pools are not updated (stale)
3. Commission is not calculated yet

### The Gap

The "gap" is the difference between:

* **StakePool value:** actual tokens in `StakePool.active` (or `pending_inactive`)
* **Shares pool value:** `active_shares.total_coins` (or `inactive_shares[cycle].total_coins`)

This gap represents unsynchronized rewards waiting to be distributed to delegators (via share price increase) and operator (via commission).

### Sync Process

For each shares pool (`active_shares` and `pending_inactive_shares`):

1. Calculate gap: `gap = stake_pool_value - pool.total_coins`
2. Calculate commission: `commission = gap × commission_rate`
3. Update shares pool: `pool_u64::update_total_coins(pool, stake_pool_value - commission)`
   * This increases share price for delegators
4. Operator buys shares: operator uses commission to buy shares at new price

**Implications**

* If no one interacts, rewards simply accumulate indefinitely in the StakePool
* Commission is paid in one lump sum when sync finally happens
* Operator loses compounding on commission if sync is delayed

***

## References

For additional context, see the [Aptos Staking documentation](https://aptos.dev/network/blockchain/staking) and [Aptos Delegated Staking documentation](https://aptos.dev/network/blockchain/delegated-staking).

# What is M1
URL: /general/l1/what-is-movement-l1

M1 is a native Layer 1 blockchain built specifically for the Move programming language and virtual machine. Unlike sidechains or Layer 2 solutions, M1 operates as an independent blockchain with its own consensus mechanism and validator set.

## Core Components

#### Native Move Virtual Machine (MoveVM)

M1 runs the Move Virtual Machine natively, providing ***direct Move execution*** where smart contracts execute without translation or adaptation layers. The platform offers full support for Move's ***resource-oriented programming model*** with ***optimized performance*** through direct bytecode execution for maximum efficiency. Built-in ***type safety*** provides compile-time guarantees for asset safety and program correctness.

#### Consensus and Validation

M1 employs a ***proof-of-stake consensus*** mechanism for energy-efficient validation with native staking. A ***decentralized validator network*** secures the network, while ***fast finality*** ensures sub-second transaction finality for optimal user experience. The system features ***Byzantine fault tolerance***, providing robust consensus resistant to malicious actors.

#### Native Token Economics

The ***MOVE token*** serves as the native token for transaction fees, staking, and governance. ***Efficient gas metering*** provides resource pricing for computational operations, while ***staking rewards*** incentivize validators and delegators to earn rewards for network security. ***Token holders*** participate in protocol governance, ensuring decentralized decision-making.

## Key Advantages

#### Developer Experience

M1 provides a purpose-built ***Move language*** designed specifically for digital assets and DeFi applications. Developers benefit from ***comprehensive development tools and libraries***, along with ***built-in testing and simulation capabilities***. ***Extensive guides and API references*** ensure developers have the resources they need to build effectively.

#### Performance and Scalability

The platform delivers ***high throughput*** with thousands of transactions per second capability, combined with ***low latency*** through fast block times and transaction confirmation. ***Efficient storage*** is achieved through optimized state management and data structures, while ***parallel execution*** enables concurrent transaction processing where possible.

#### Security and Reliability

M1 leverages Move's built-in ***formal verification*** capabilities to ensure program correctness. ***Resource safety*** prevents common smart contract vulnerabilities, while the platform is built on ***battle-tested*** blockchain architectures. An ***audit trail*** maintains transaction history and state transitions for full transparency.

## Use Cases

#### DeFi Applications

M1 excels at supporting DeFi applications including efficient ***decentralized exchanges*** through automated market makers (AMMs), ***secure borrowing and lending platforms***, ***complex yield generation strategies***, and the creation and management of ***synthetic assets and derivatives***.

#### NFTs and Digital Assets

The platform enables direct creation and trading of ***non-fungible tokens*** through NFT marketplaces, supports ***gaming assets*** including in-game items and character progression systems, facilitates ***digital collectibles*** like unique digital art and memorabilia, and enables ***asset tokenization*** for real-world asset (RWA) representation on-chain.

#### Enterprise Applications

M1 supports enterprise use cases such as ***transparent supply chain tracking*** for goods and materials, ***secure digital identity verification and management*** systems, ***efficient cross-border and micropayment*** solutions, and ***regulatory-friendly blockchain compliance*** tools.

## Comparison with Sidechain

| Feature            | M1                | Sidechain                     |
| ------------------ | ----------------- | ----------------------------- |
| **Security Model** | Native validators | Operator and L1-secured       |
| **Consensus**      | BFT with PoS      | Operator + Anchoring          |
| **Execution**      | native\* MoveVM   | native or adapted MoveVM      |
| **Finality**       | Native finality   | anchoring- / bridge-dependent |
| **Governance**     | Native governance | dependent on L1               |

*\* the L1 defines the meaning of native*

## Getting Started

#### For Developers

1. **[Learn Move](/devs/firstMoveContract)**: Familiarize yourself with the Move programming language
2. **[Set up Tools](/devs/movementcli)**: Install Movement CLI and development environment
3. **[Deploy on Testnet](/devs/networkEndpoints)**: Test your applications on M1 testnet
4. **[Build Applications](/devs/tutorials/build)**: Create DeFi, NFT, or enterprise applications

#### For Users

1. **[Get a Wallet](/general/usingmovement/connect_to_movement)**: Use Move-compatible wallets for M1 interaction
2. **Acquire MOVE**: Obtain native tokens for transaction fees
3. **[Explore DApps](https://explorer.movementnetwork.xyz/)**: Discover applications built on M1
4. **Participate**: Engage with governance and network activities

# Overview
URL: /general/networks

import React from 'react';

Movement provides several networks with different architectures for development and production needs:

### M1 Networks

1. **[M1 (Mainnet)](/general/networks/mainnet)** — The flagship production network serving real economic value.
2. **[M1 (Testnet)](/general/networks/testnet)** — A native L1 testing environment that provides developers with a safe space to build and test applications using the full Move execution environment before deploying to production networks.

## Network Status

Movement is **live on Mainnet**. M1 — the native Move Layer 1 — powers both Mainnet and Testnet, giving developers a full Move execution environment for production applications and for pre-production testing.

{/* ### Network Properties

| Network | Chain ID | Genesis | Faucet | Governance | Update Schedule | Data Persistence |
  |---------|------------|---------|---------|------------|-----------------|------------------|
  | **M1 (Mainnet)** | 126 | Info Coming Soon | N/A | Info Coming Soon | Monthly, varies | Permanent |
  | **M1 (Testnet)** | 250 | Info Coming Soon | Coming Soon | Managed by Move Industries | Monthly, varies | Resets as Needed, but avoided | */}

All Network URLS are availble [here](/devs/networkEndpoints).

## Additional Resources

* For community resources, support channels, and ways to get involved, see [Community and Support](/general/usingmovement/community-support).
* **[Node Operations](/general/l1/nodes)** - Information about running Movement nodes
* **[Explorer](https://explorer.movementnetwork.xyz/)** - Browse network activity and transactions

# Mainnet
URL: /general/networks/mainnet

import React from 'react';

Movement Mainnet is the flagship blockchain in the Movement ecosystem, designed to be a high-performance, secure, and scalable blockchain platform.

Movement Mainnet is live. To start building on Mainnet, see our [developer documentation](/devs) and the [network endpoints](/devs/networkEndpoints).

## Documentation

* **[Learn more about M1 architecture](/general/l1)**

# M1 (Testnet)
URL: /general/networks/testnet

import React from 'react';

Movement Testnet is a native L1 blockchain network that provides a production-like testing environment for developers to build and test applications before deploying to the production networks. Testnet operates as a full [L1 blockchain](/general/l1).

## Key Features

Testnet represents the stable testing version of Movement's L1 architecture:

* **Stable Environment**: Persistent network with reliable uptime
* **Production-Ready Conditions**: Production-like network conditions, consensus and performance
* **Community Validators**: Decentralized validator set for realistic testing
* **Persistent Data**: Long-term data retention for continuous development
* **Stable APIs**: Production-ready interfaces for application development

## Network Properties

| Property           | Value                                                     |
| ------------------ | --------------------------------------------------------- |
| **Network Type**   | Native L1 Blockchain                                      |
| **Consensus**      | BFT Consensus                                             |
| **Block Time**     | \~1 second                                                |
| **Finality**       | \~1 second (Details TBA)                                  |
| **Validators**     | Community + Move Industries                               |
| **Data Retention** | Permanent                                                 |
| **Faucet**         | [Get testnet tokens](https://faucet.movementnetwork.xyz/) |

<Callout type="info">
  Testnet lets teams confirm applications are compatible with L1 architecture through ***tool validation*** to ensure development tools work with L1, ***workflow testing*** to validate deployment and operational workflows, and ***training*** to familiarize teams with L1 operations.
</Callout>

## Use Cases

#### Application Development

Testnet enables comprehensive application development through ***pre-production testing*** in production-like conditions, ***integration testing*** to validate integrations with realistic network behavior, ***performance testing*** to benchmark application performance on L1, and ***user acceptance testing*** for end-to-end testing with real user flows.

#### Infrastructure Testing

Infrastructure testing includes ***validator setup*** for testing validator node configurations, ***API services*** validation for RPC and indexing services, ***monitoring*** implementation for infrastructure monitoring and alerting, and ***scaling*** tests to validate infrastructure performance under load.

## Getting Started

#### Prerequisites

* [Movement CLI tools](/devs/movementcli) installed
* Understanding of [Move language](/general/l1/move-language)
* Testnet MOVE tokens from [faucet](https://faucet.movementnetwork.xyz/)

# Nodes
URL: /general/nodes

The Movement Network consists of various node types that serve different purposes. This section covers how to deploy and operate nodes for different use cases.

## Node Types

### Full Node (PFN)

A **public fullnode (PFN)** synchronizes with the Movement blockchain and maintains recent state. Full nodes are suitable for:

* Running applications that need blockchain data
* Submitting transactions
* Querying recent state and transactions

[Learn more about Full Nodes](/general/nodes/full-node)

### Archival Node

An **archival fullnode** maintains complete blockchain history from genesis by disabling ledger pruning. Archival nodes are required for:

* Historical state queries from any point in time
* Running indexers that need full transaction history
* Providing historical data services

[Learn more about Archival Nodes](/general/nodes/archival-node)

## Comparison

| Feature                  | Full Node                  | Archival Node                |
| ------------------------ | -------------------------- | ---------------------------- |
| Recent state queries     | Yes                        | Yes                          |
| Historical state queries | Limited                    | Full history                 |
| Storage requirements     | \~50-100GB                 | 700GB+ (mainnet)             |
| Initial sync time        | Fast (state sync)          | Requires backup restore      |
| Use case                 | Applications, transactions | Indexers, historical queries |

## Additional Resources

* [M1 Node Types](/general/l1/nodes) - Learn about validator and VFN nodes
* [Genesis Files](https://github.com/movement-network/movement-networks) - Download genesis and configuration files

# Bridge
URL: /general/usingmovement/bridge

## Canonical Bridging via Layer Zero

The Movement Network Bridge, powered by [LayerZero](https://www.layerzero.network/), is a bridge that allows users to bridge tokens between the Movement Network and other chains, initially supporting transfers from Ethereum to Movement Network.

Note: The Movement Network Bridge is currently in beta and only supports transfers from Ethereum to Movement Network for Move. Other assets can be bridged in both directions.

Learn more about Layer Zero OFT(Omnichain Fungible Tokens) and how this is implemented using Aptos Move [here](https://docs.layerzero.network/v2/developers/aptos-move/contract-modules/oft).

Note: OFTs do not currently support the Coin standard and as such all OFTs are minted as Fungible Asset Standard.

## Bridge Interface

The Bridge Interface is a web application that allows users to bridge tokens between the Movement Network and other chains.

To start bridging, navigate to the [Bridge Interface](https://bridge.movementnetwork.xyz/) and connect your wallet.

## Asset Transfer

We are launching with support for the following assets:

* Move Token
  * Daily Bridge Limit:
    * 75M tokens can be bridged to Movement on Day 1
    * 25m tokens can be bridged to Movement per day thereafter
  * No withdrawals from Movement back to Ethereum for Move Token at launch
* USDC/USDT/ETH
  * 3 Day waiting period for withdrawals when briding from Movement to Ethereum
* Other Assets
  * 3 Day waiting period for withdrawals when briding from Movement to Ethereum

## Mainnet Addresses

The mainnet Bridge currently allows for bridging between Ethereum Mainnet and Movement Mainnet.

<Callout>
  Note that the Move Token listed below is not an OFT but is an FA token that is used to pay for gas on the Movement Network. On the Movement Network both Coin and FA move can be used to initialize accounts and pay for gas.
</Callout>

### Adaptor Addresses on Ethereum Mainnet

| Adaptor          | Address                                      |
| ---------------- | -------------------------------------------- |
| MOVE OFT Adapter | `0xf1df43a3053cd18e477233b59a25fc483c2cbe0f` |
| USDC OFT Adapter | `0xc209a627a7B0a19F16A963D9f7281667A2d9eFf2` |
| USDT OFT Adapter | `0x5e87D7e75B272fb7150B4d1a05afb6Bd71474950` |
| WETH OFT Adapter | `0x06E01cB086fea9C644a2C105A9F20cfC21A526e8` |
| WBTC OFT Adapter | `0xa55688C280E725704CFe8Ea30eD33fE5B91cE6a4` |

### Ethereum Token Addresses

| Token | Address                                      |
| ----- | -------------------------------------------- |
| MOVE  | `0x3073f7aAA4DB83f95e9FFf17424F71D4751a3073` |
| USDC  | `0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48` |
| USDT  | `0xdac17f958d2ee523a2206206994597c13d831ec7` |
| WETH  | `0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2` |
| WBTC  | `0x2260fac5e5542a773aa44fbcfedf7c193bc2c599` |

### Movement OFT Contract Addresses

| Token  | Address                                                              |
| ------ | -------------------------------------------------------------------- |
| MOVE   | `0x7e4fd97ef92302eea9b10f74be1d96fb1f1511cf7ed28867b0144ca89c6ebc3c` |
| USDC.e | `0x4d2969d384e440db9f1a51391cfc261d1ec08ee1bdf7b9711a6c05d485a4110a` |
| USDT.e | `0x38cdb3f0afabee56a3393793940d28214cba1f5781e13d5db18fa7079f60ab55` |
| WETH.e | `0x3dfe1ac4574c7dbbe6f1c5ba862de88fc3e7d3cf8eba95ef1abf32b582889e6d` |
| WBTC.e | `0xbdf86868a32dbae96f2cd50ab05b4be43b92e84e793a4fc01b5b460cc38fdc14` |

### Movement MOVE Escrow Address:

`0x42afc6935b692cd286e3087a4464ec516a60dd21c9e355e1b8b0088376501372`

### Movement OFT / FA Addresses

| Token  | Address                                                              |
| ------ | -------------------------------------------------------------------- |
| MOVE   | `0xa`                                                                |
| USDC.e | `0x83121c9f9b0527d1f056e21a950d6bf3b9e9e2e8353d0e95ccea726713cbea39` |
| USDT.e | `0x447721a30109c662dde9c73a0c2c9c9c459fb5e5a9c92f03c50fa69737f5d08d` |
| WETH.e | `0x908828f4fb0213d4034c3ded1630bbd904e8a3a6bf3c63270887f0b06653a376` |
| WBTC.e | `0xb06f29f24dde9c6daeec1f930f14a441a8d6c0fbea590725e88b340af3e1939c` |

## Testnet Addresses

The testnet Bridge currently allows for bridging between Binance Smart Chain Testnet and Movement Bardock Testnet.

### Mock Token Addresses on BSC Testnet

| Token | Address                                      |
| ----- | -------------------------------------------- |
| tUsdc | `0x3D40fF7Ff9D5B01Cb5413e7E5C18Aa104A6506a5` |
| tUsdt | `0xC1c94Dde81053612aC602ba39b6AfBd3CfE6a8Bc` |
| tWeth | `0x50e288885258bC62da02d7Bd1e37d5c7B27F814F` |

### Bardock OFT Addresses

| Token  | Address                                                              |
| ------ | -------------------------------------------------------------------- |
| USDC.e | `0x33987308d6698c3def1f155c8ea394360e9756b0a22e64fb20834327f04a1e42` |
| USDT.e | `0x9cda672762a6f88e4b608428dd063e03aaf6712f0a427923dd0f1416afa1c075` |
| WETH.e | `0x2fa1f2914aa17d239410cb81ab46dd8fa9230272c58bc84e9e8b971eded79ca5` |

# Community and Support
URL: /general/usingmovement/community-support

import React from 'react';

## Get Involved

* **Build on Movement**: Deploy your dApps to Mainnet and Testnet
* **Developer Feedback**: Report issues and suggestions
* **Community Testing**: Join coordinated testing efforts
* **Documentation**: Contribute to documentation improvements

## Support Channels

* **[Discord Community](https://discord.com/invite/moveindustries)** - Real-time support and discussion
* **[GitHub Issues](https://github.com/movement-network/movement)** - Bug reports and feature requests
* **Office Hours** - Regular developer support sessions

## Stay Updated

* **[X (Twitter)](https://x.com/movement_xyz)** - Latest news and developments
* **[GitHub](https://github.com/movement-network/movement)** - Technical updates and releases

# Connect To Movement
URL: /general/usingmovement/connect_to_movement

This guide will show you how to use blockchains on the movement network. Everything from setting up the wallet to connecting to the chain, getting testnet tokens from the faucet, and using the explorer will be covered in this guide.

Let’s start by installing a wallet. We recommend [Motion](https://chromewebstore.google.com/detail/motion-wallet/lcicbbjcjidfcideckmacabjdfiiogfo), the official Movement wallet built by Move Industries. OKX Wallet and Nightly are also supported. All of these work on Chrome, Brave, Opera, Edge, and other Chromium-based browsers.

Install the Chrome extensions here:

* [Motion](https://chromewebstore.google.com/detail/motion-wallet/lcicbbjcjidfcideckmacabjdfiiogfo)
* [OKX Wallet](https://chromewebstore.google.com/detail/okx-wallet/mcohilncbfahbmgdjkbpemcciiolgcge)
* [Nightly](https://chromewebstore.google.com/detail/nightly/fiikommddbeccaoicoejoniammnalkfa)

## Wallet Setup

Follow the instructions to set up the wallet.

### Motion Wallet

Motion is the official self-custodial wallet for the Movement Network, built by Move Industries. Your keys are encrypted and stored locally on your device. It supports sending and receiving MOVE, swaps, bridging (Movement → Ethereum via LayerZero), Ledger hardware wallets, and dApp connections, with quick switching between Mainnet and Testnet.

Learn more or download it at [motion.movementnetwork.xyz](https://motion.movementnetwork.xyz/).

**Step 1: Install and Open Motion**

1. Install the [Motion Wallet extension](https://chromewebstore.google.com/detail/motion-wallet/lcicbbjcjidfcideckmacabjdfiiogfo) from the Chrome Web Store and pin it to your toolbar.
2. Open the extension to begin setup.

**Step 2: Create or Import a Wallet**

1. Choose **Create a new wallet** to generate a fresh seed phrase, or **Import** an existing wallet using a seed phrase or private key.
2. Write down your recovery phrase and store it somewhere safe. Never share it with anyone.

![](./imgs/motion1.png)

**Step 3: Set a Password**

1. Create a strong password to encrypt your wallet locally.
2. Confirm the password to finish setup.

![](./imgs/motion2.png)

### OKX Wallet

**Step 1: Welcome to OKX Wallet**

1. Open the OKX Wallet extension.
2. You will be greeted with the welcome screen.
3. Click on the “Start” button.

![](./imgs/okx1.png)

**Step 2: Create Wallet**

1. The next screen will present you with the "Create Wallet" page. In our example we will use the "Seed phrase" option secured by a password.

![](./imgs/okx2.png)
![](./imgs/okx3.png)

**Step 3: Create a Password**

1. You will now be prompted to create a password for the wallet.
2. Enter a strong password and confirm it by entering it again.
3. Click on the Confirm button.

![](./imgs/okx4.png)

**Step 4: Back Up Your Seed Phrase**

1. You will now be prompted to save your seed phrase. Be sure to write this down and keep it in a safe space

![](./imgs/okx6.png)

**Step 5: Welcome to the OKX Wallet Dashboard**

1. After setting up your password, you will see the OKX Wallet dashboard upon clicking the extension.

![](./imgs/okx5.png)
![](./imgs/okx7.png)

### Nightly

**Step 1: Welcome to Nightly Wallet**

1. Open the Nightly Wallet application or extension.
2. You will be greeted with the welcome screen.
3. Click on the “Start your journey with Nightly!” button.

![](./imgs/image8.png)

**Step 2: Set Password**

1. You will now be prompted to create a password for your Nightly wallet after you create a new wallet.
2. Enter a strong password and confirm it by entering it again.
3. Click on the “Next” button.

![](./imgs/image9.png)\
![](./imgs/image10.png)

**Step 3: Your Secret Phrase**

1. The next screen will present you with your Secret Recovery Phrase. This is a critical step in setting up your wallet.
2. Ensure you write down the 12-word phrase and store it securely. Do not share it with anyone.
3. Click on “Next” after you have safely noted it down.

![](./imgs/image11.png)

**Step 4: Wallet Created**

1. Once you have completed the setup, you will receive a message indicating that your Nightly wallet has been created.
2. Click on “Log in to your wallet” to finish the setup process.

![](./imgs/image12.png)

**Step 5: Nightly Wallet Dashboard**

1. After logging in, you will see the Nightly Wallet dashboard.
2. Be sure to select Movement from the network drop-down menu and you’re set!

![](./imgs/image13.png)

## Connecting to the Movement Network

Movement Network currently runs **Aptos Move** on both Mainnet and Testnet, powered by the [M1](/general/l1/what-is-movement-l1) blockchain.

<Callout type="info">
  **Note:** Sui Move and Move EVM (MEVM) have been deprecated and are no longer supported.
</Callout>

Our Mainnet and Testnet are running M1 - a native Layer 1 blockchain built specifically for the Move programming language. Learn more about [M1 architecture and capabilities](/general/l1/what-is-movement-l1).

dApps deployed on the Movement Network will work with Motion and Nightly wallets.

Let's try using them on Movement's Faucet with Aptos Move.

**Step 1: Access the Movement Faucet**

1. Open your browser and go to [Movement Faucet](https://faucet.movementnetwork.xyz/).
2. Select the chain you want to use. For this example, select "Aptos Move" in the mock tokens section.
   ![](./imgs/image23.png)

**Step 2: Connect Your Wallet**

1. Click on the “Connect Wallet” button.
2. Choose Motion Wallet or Nightly Wallet from the list of available wallets.

![](./imgs/image24.png)

**Step 3: Approve Access Request**

1. Your wallet will request access to connect to the Movement Faucet.
2. Approve the access request by clicking “Confirm”.

![](./imgs/image25.png)

**Step 4: Get Mock Tokens**

1. Now that the wallet is connected, you can mint dummy tokens as per your needs.

![](./imgs/image26.png)

Using this faucet, you can get testnet tokens across any movement chain.

That is it for this guide! If you’re looking to build on Movement, check out our [developer docs](/devs).

# NEAR Intents
URL: /general/usingmovement/near-intents

## Onboarding via NEAR Intents

NEAR Intents is an intent-based, cross-chain settlement protocol. Instead of manually choosing a bridge and a swap, you declare the outcome you want — "I have token X on chain A, give me token Y on the Movement Network" — and a competitive network of solvers fulfills it in a single step.

For onboarding to Movement, this means you can convert **USDT held on supported chains** into **USDC.x on the Movement Network** without bridging and swapping yourself.

<Callout>
  NEAR Intents complements the canonical [Bridge](./bridge). The Bridge moves a specific asset between Ethereum and Movement, while NEAR Intents lets you arrive on Movement from a range of source chains and assets in one transaction.
</Callout>

## Where to swap

You perform the swap in the [NEAR Intents app](https://near.com). It is powered by the 1Click API, which wraps NEAR Intents into a simple deposit-and-receive flow. You do not interact with solvers or the underlying protocol directly — 1Click coordinates quoting, deposit handling, intent submission, settlement tracking, and refunds.

## How it works

1. **Choose your assets.** Select your origin asset (USDT on a supported chain) and the destination asset (USDC.x on the Movement Network), and provide the Movement address that should receive the funds.
2. **Get a quote.** 1Click returns a one-time deposit address on the origin chain along with the expected amount you will receive.
3. **Deposit.** Send your USDT to the provided deposit address. The swap begins automatically once the deposit transaction is detected and confirmed on the origin chain.
4. **Receive.** USDC.x is delivered to your Movement address.

## For developers

Building an integration instead of moving funds by hand? The [NEAR Intents SDK](/devs/interactonchain/near-intents-sdk) is a TypeScript SDK that runs this same USDT/USDC → Movement flow programmatically — quote a route, build the deposit, and track it to settlement.

## Learn more

* [NEAR Intents overview](https://docs.near-intents.org/)

# Aptos Wallet Standard
URL: /devs/interactonchain/wallet-adapter/aptos_wallet_standard

The Movement Network uses the Aptos flavor of Move, which includes Aptos wallets.

**Why is this important?**

* **For Users:** It means you're free to use your favorite Aptos Move wallet with any dApp without worrying about compatibility headaches.
* **For Developers:** You can focus on building amazing dApps, knowing that your application will work smoothly with a wide range of wallets.
* **For the Move Ecosystem:** A unified standard fosters growth and innovation by removing barriers to entry.

**Let's break down the key ingredients of this standard.**

## 1. Mnemonics: Your Master Key to the Aptos Universe

### 1.1 What are Mnemonics?

Think of a mnemonic phrase as a super-secure, human-readable password that unlocks your digital assets. Instead of a random string of characters, it's a list of 12 or 24 words that you can write down and store safely. This phrase is the foundation of your account's security, so guard it carefully!

**Best Practice:** Each account should have its own unique mnemonic. This enhances security and makes key rotation (which we'll discuss later) much easier to manage. It's like having separate keys for your house, your car, and your safe deposit box – much safer than using the same key for everything. While some wallets, especially those migrating from other ecosystems, might use a single mnemonic for multiple accounts, the Aptos standard strongly recommends a one-to-one relationship between mnemonics and accounts.

### 1.2 Creating Your First Move Account

> Let's walk through the process of generating a new Aptos account:

1. **Generate Your Mnemonic Phrase:** We use a widely adopted standard called BIP39 to generate a cryptographically secure mnemonic. Many wallet applications and libraries will handle this for you automatically.
2. **From Phrase to Seed:** Your mnemonic isn't directly used as a key. Instead, it's converted into a "master seed" – a long string of random bits that serves as the starting point for generating your account keys.
3. **Deriving Your Account Address:** Here's where BIP44 comes in. It defines a standard way to create a "path" from your master seed to your Aptos account address. This path looks like this: `m/44'/637'/0'/0'/0'`. Each number represents a specific level of derivation, ensuring that your Aptos address is unique and securely generated. The `637` in the path specifically designates Aptos within the broader cryptocurrency landscape.

```typescript
/**
  * Creates new account with bip44 path and mnemonics,
  * @param path. (e.g. m/44'/637'/0'/0'/0')
  * Detailed description: {@link https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki}
  * @param mnemonics.
  * @returns AptosAccount
  */
static fromDerivePath(path: string, mnemonics: string): AptosAccount {
   if (!AptosAccount.isValidPath(path)) {
     throw new Error("Invalid derivation path");
   }

const normalizeMnemonics = mnemonics
     .trim()
     .split(/\s+/)
     .map((part) => part.toLowerCase())
     .join(" ");

const { key } = derivePath(bytesToHex(bip39.mnemonicToSeedSync(normalizeMnemonics)), path);

return new AptosAccount(new Uint8Array(key));
}
```

### 1.3 Supporting Multiple Accounts (The Advanced Route)

While not recommended for most users, some wallets allow you to manage multiple Aptos accounts from a single mnemonic. This is like having a master key that can open multiple doors in a building.

**How it Works:**

1. Steps 1 and 2 are the same: Generate the mnemonic and master seed.
2. **Account Index:** Instead of a fixed path, we introduce an "account index" (`i`) into the derivation path: `m/44'/637'/i'/0'/0'`.
3. **Finding Your Accounts:** The wallet will increment `i` (starting from 0, then 1, 2, and so on) to generate multiple account addresses from your single mnemonic.

**Searching with a Gap Limit:** To avoid searching endlessly for accounts, wallets use a "gap limit." This limit (usually set to 10) defines how many empty addresses the wallet will check before giving up. So, if the wallet finds 10 consecutive addresses with no associated accounts, it will stop searching.

```typescript
const gapLimit = 10; // Standard gap limit
let currentGap = 0;

for (let i = 0; currentGap < gapLimit; i += 1) {
  const derivationPath = `m/44'/637'/${i}'/0'/0'`;
  const account = AptosAccount.fromDerivePath(derivationPath, mnemonics);
  try {
    const resources = await account.getResources(); // Try fetching resources for the account
    wallet.addAccount(account); // Account exists, add it to the wallet
    currentGap = 0; // Reset the gap
  } catch (error) {
    if (error.status === 404) {
      currentGap += 1; // Increment the gap if account not found
    } else {
      throw new AptosWalletError(AptosWalletErrorCode.InternalError, error);
    }
  }
}
```

**Caution:** Managing multiple accounts from one mnemonic can be more complex and may have security implications if not handled carefully. It also makes key rotation more difficult, as rotating one account derived from the mnemonic might affect others.

## 2. Bridging the Gap: How Wallets and dApps Communicate

### 2.1 The Universal Language: The AptosWallet Interface

To ensure smooth communication, wallets must speak a common language. This is defined by the `AptosWallet` interface, as specified in AIP-62. Think of it as a contract that all wallets must adhere to.

```typescript
class MyWallet implements AptosWallet {
  url: string;
  version: "1.0.0";
  name: string;
  icon: `data:image/svg+xml;base64,${string}` | `data:image/webp;base64,${string}` | `data:image/png;base64,${string}` | `data:image/gif;base64,${string}`;
  chains: AptosChain[];
  features: AptosFeatures;
  accounts: readonly AptosWalletAccount[];
}
```

**What does this mean?**

Every Aptos-compatible wallet will have properties like:

* `url`: The URL of the wallet.
* `version`: The wallet's version number.
* `name`: The wallet's name (e.g., "Petra," "Martian").
* `icon`: An icon representing the wallet.
* `chains`: The Aptos chains it supports (e.g., mainnet, testnet).
* `features`: The capabilities of the wallet (e.g., connecting, signing transactions).
* `accounts`: A list of the user's accounts managed by the wallet.

### 2.2. Inside the Wallet: The AptosWalletAccount Interface

Each account within a wallet also has a standard interface: `AptosWalletAccount`.

```typescript
enum AptosAccountVariant {
  Ed25519,
  MultiEd25519,
  SingleKey,
  MultiKey,
}

class AptosWalletAccount implements WalletAccount {
  address: string;
  publicKey: Uint8Array;
  chains: AptosChain[];
  features: AptosFeatures;
  variant: AptosAccountVariant;
  label?: string;
  icon?: `data:image/svg+xml;base64,${string}` | `data:image/webp;base64,${string}` | `data:image/png;base64,${string}` | `data:image/gif;base64,${string}`;
}
```

**Key Properties:**

* `address`: The account's public address on the Aptos blockchain.
* `publicKey`: The public key associated with the account.
* `chains`: The Aptos chains this account is valid on.
* `features`: The capabilities of this specific account.
* `variant`: The type of cryptographic scheme used by the account (e.g., Ed25519, MultiEd25519).
* `label` and `icon`: Optional properties to help users identify and manage their accounts.

**Wallet Registration:** Web extension wallets (like those installed from the Chrome Web Store) need to actively register themselves using a `registerWallet` function. This lets dApps know that the wallet is installed and ready to be used.

```typescript
const myWallet = new MyWallet();
registerWallet(myWallet);
```

### 2.3 Handling Errors Gracefully: The AptosWalletError

When things go wrong (and they sometimes do), wallets need a consistent way to report errors. The `AptosWalletError` class provides a standardized approach. Wallets can throw predefined errors like `Unauthorized` or `InternalError`, or they can create custom errors with specific error codes and messages.

```typescript
// Using the default message
if (error) {
  throw new AptosWalletError(AptosWalletErrorCode.Unauthorized);
}

// Using a custom message
if (error) {
  throw new AptosWalletError(
    AptosWalletErrorCode.Unauthorized,
    "My custom unauthorized message"
  );
}

// Using a custom error code
if (error) {
  throw new AptosWalletError(-32000, "Invalid Input");
}
```

**Why is this important?**

* **dApp developers** can easily handle different error scenarios without writing wallet-specific code.
* **Users** get clear and consistent error messages, regardless of which wallet they're using.

## 3. Integrating with Wallets: A dApp Developer's Toolkit

### 3.1 The Easy Route: The Wallet Adapter Standard

For a seamless integration experience, dApp developers are encouraged to use the Aptos Wallet Adapter Standard. This standard provides a set of tools and libraries that simplify the process of connecting to multiple wallets. The Wallet Adapter Standard is designed to work across different blockchain ecosystems, making it a versatile solution.

**Think of the Wallet Adapter as a universal remote control for your TV. You don't need a separate remote for each device; the universal remote handles it all.**

### 3.2. The Custom Path: Rolling Your Own Integration

If you need more control or want to build a custom integration, you can use the `getAptosWallets()` function. This function retrieves a list of all currently registered Aptos wallets that comply with the standard.

```typescript
import { getAptosWallets } from "@aptos-labs/wallet-standard";

let { aptosWallets, on } = getAptosWallets();
```

**Dynamic Wallet Discovery:** dApps can listen for events when new wallets are registered or unregistered. This allows them to dynamically update their UI and provide users with the most up-to-date list of available wallets.

```typescript
const removeRegisterListener = on("register", () => {
  let { aptosWallets } = getAptosWallets();
  // Update the UI with the newly registered wallets
});

const removeUnregisterListener = on("unregister", () => {
  let { aptosWallets } = getAptosWallets();
  // Update the UI to remove unregistered wallets
});
```

When a user wants to connect, the dApp can simply call the appropriate function offered by the wallet (e.g., `connect()`).

```typescript
const onConnect = async () => {
  try {
    const response = await wallet.features["aptos:connect"].connect();
    console.log("Wallet connected:", response);
    // Handle successful connection
  } catch (error) {
    console.error("Connection error:", error);
    // Handle connection error, display error message, etc.
  }
};
```

**Example Scenario:** A dApp might have a "Connect Wallet" button. When clicked, the dApp calls `getAptosWallets()`, displays the available wallets to the user, and then, upon user selection, calls the selected wallet's `connect()` function to initiate the connection.

## 4. Key Rotation: Upgrading Your Security

### 4.1. What is Key Rotation?

Imagine you lose your house keys. You wouldn't just keep using the same locks, right? You'd change them. Key rotation is a similar concept in the blockchain world. It's the process of updating your account's authentication key to a new one, enhancing security in case your old key is compromised.

### 4.2 The Future of Aptos Key Rotation

* **Implementation Status:** While the on-chain mechanism for mapping rotated keys is already implemented, wallet support is still under development. SDK integration is also actively being worked on.
* **How It Will Work (for Wallets Importing Private Keys):**

1. **Derive the Authentication Key:** The wallet derives the authentication key from the imported private key.
2. **On-Chain Lookup:** The wallet checks the Aptos blockchain's account origination table to see if an account with this authentication key already exists.

* **New Account:** If no matching account is found, it means it's a brand-new account, and the authentication key will be used as the account address.
   * **Rotated Key:** If a matching account is found, it indicates that the key has been rotated. The wallet will then use the actual account address stored in the table.

**Why is Key Rotation Important?**

* **Enhanced Security:** Regularly rotating your keys reduces the risk of unauthorized access if a key is compromised.
* **Account Recovery:** In some scenarios, key rotation can be used as a mechanism for account recovery.

# Connect Wallet
URL: /devs/interactonchain/wallet-adapter/connect_wallet

# Overview

This guide will help you understand how to connect with Aptos MoveVM wallets.

# Aptos Move Wallets

With Aptos compatible networks, you can use `@aptos-labs/wallet-adapter-react` to provide your dApp with a `Provider` and `Context` for connecting MoveVM wallets to your dapp.

This Provider uses a standard interface for all Movement Wallets, making it easy for new wallets to be supported.

## Using the React `Provider` and `Context`

In this example, we'll be using Next.js and TypeScript.

### Set up Next.js

```bash tab="npm"
npm create next-app
```

```bash tab="pnpm"
pnpm create next-app
```

```bash tab="yarn"
yarn create next-app
```

```bash tab="bun"
bun create next-app
```

### Install `@aptos-labs/wallet-adapter-react`

```bash tab="npm"
npm install @aptos-labs/wallet-adapter-react @moveindustries/ts-sdk
```

```bash tab="pnpm"
pnpm add @aptos-labs/wallet-adapter-react @moveindustries/ts-sdk
```

```bash tab="yarn"
yarn add @aptos-labs/wallet-adapter-react @moveindustries/ts-sdk
```

```bash tab="bun"
bun add @aptos-labs/wallet-adapter-react @moveindustries/ts-sdk
```

### Implement Wallet Provider & Custom network

Create a new files with name `provider/WalletProvider.tsx`, import the Aptos Wallet Adapter and any legacy wallet plugins & custom network to connect to the Movement Testnet.

```typescript title="src/provider/WalletProvider.tsx"
import { AptosWalletAdapterProvider } from "@aptos-labs/wallet-adapter-react";
import { PropsWithChildren } from "react";
import { MovementConfig, Network } from "@moveindustries/ts-sdk";

export const WalletProvider = ({ children }: PropsWithChildren) => {
  const wallets = [
    // add plugins for non AIP 62 compliant wallets here
  ];
  const config = new MovementConfig({
    network: Network.TESTNET,
    fullnode: 'https://testnet.movementnetwork.xyz/v1',
    faucet: 'https://faucet.testnet.movementnetwork.xyz/'
  })

return (
    <AptosWalletAdapterProvider
      plugins={wallets}
      autoConnect={true}
      dappConfig={config}
      onError={(error) => {
        console.log("error", error);
      }}
    >
      {children}
    </AptosWalletAdapterProvider>
  );
};
```

<details>
  <summary>All fields of AptosWalletAdapterProvider</summary>
  It is recommended to:

Set autoConnect to true.
  Include plugins for any wallets that are using the legacy standard.

| Field          | Description                                                                                                                                                                                                                                                                                                                                                                    | Example                                                   |
  | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
  | `autoConnect`  | A prop indicates whether the dapp should auto connect with the most recently connected wallet on page reload.                                                                                                                                                                                                                                                                  | `true`                                                    |
  | `optInWallets` | Limit the list of supported AIP-62 wallets to just the ones with names in optedInWallets.                                                                                                                                                                                                                                                                                      | `['Petra']`                                               |
  | `dappConfig`   | Specify an alternate network to work on. This prop only works for wallets which are NOT chrome extensions. If set, this object must include the name of the network the app is connected to. The object may include a aptosConnectDappId.                                                                                                                                      | `{ network: 'mainnet',   aptosConnectDappId: undefined }` |
  | `onError`      | A callback function to fire when the adapter throws an error.                                                                                                                                                                                                                                                                                                                  | `(error) => { console.log("error", error); }`             |
  | `plugins`      | Any legacy standard wallet, i.e., a wallet that is not AIP-62 standard compatible, should be installed in this array. Check [https://github.com/aptos-labs/aptos-wallet-adapter/blob/main/README.md#supported-wallet-packages](https://github.com/aptos-labs/aptos-wallet-adapter/blob/main/README.md#supported-wallet-packages) for a list of legacy standard wallet plugins. | `[new LegacyWallet()]`                                    |
</details>

### Import Provider to layout.tsx

```typescript
import type { Metadata } from "next";
import localFont from "next/font/local";
import "./globals.css";
import { WalletProvider } from "@/provider";

// ... {rest code}

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
      >
        <WalletProvider>
          {children}
        </WalletProvider>
      </body>
    </html>
  );
}
```

### Edit `src/app/page.tsx` & import `useWallet` to access data from the `Provider`

```typescript title="src/app/page.tsx"
'use client'

import {useWallet} from '@aptos-labs/wallet-adapter-react'

export default function Home() {
  const { account, connected, wallet, changeNetwork } = useWallet();

return (
    <div className="grid grid-rows-[20px_1fr_20px] items-center justify-items-center min-h-screen p-8 pb-20 gap-16 sm:p-20 font-[family-name:var(--font-geist-sans)]">
    {account && account.address}
    </div>
  );
}
```

For more information about the `useWallet` hook, you can refer to the following interface:

```typescript
export interface WalletContextState {
  connected: boolean;
  isLoading: boolean;
  account: AccountInfo | null;
  network: NetworkInfo | null;
  connect(walletName: WalletName): void;
  disconnect(): void;
  wallet: WalletInfo | null;
  wallets?: ReadonlyArray<Wallet | AptosStandardSupportedWallet>;
  signAndSubmitTransaction(transaction: InputTransactionData): Promise<any>;
  signTransaction(
    transactionOrPayload: AnyRawTransaction | Types.TransactionPayload,
    asFeePayer?: boolean,
    options?: InputGenerateTransactionOptions
  ): Promise<AccountAuthenticator>;
  submitTransaction(
    transaction: InputSubmitTransactionData
  ): Promise<PendingTransactionResponse>;
  signMessage(message: SignMessagePayload): Promise<SignMessageResponse>;
  signMessageAndVerify(message: SignMessagePayload): Promise<boolean>;
  changeNetwork(network: Network): Promise<AptosChangeNetworkOutput>;
}
```

<details>
  <summary>Details all function of useWallet()</summary>

### Functions

*See [`WalletCore.ts`](https://github.com/aptos-labs/aptos-wallet-adapter/blob/main/packages/wallet-adapter-core/src/WalletCore.ts) in [`wallet-adapter-core`](https://github.com/aptos-labs/aptos-wallet-adapter/tree/main/packages/wallet-adapter-core) for where these functions are implemented.*

| Function                   | Signature                                                                                                                                                                              | Description                                                                       |
  | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
  | `connect`                  | `connect(walletName: WalletName): void`                                                                                                                                                | Connects to the specified wallet by its name.                                     |
  | `disconnect`               | `disconnect(): void`                                                                                                                                                                   | Disconnects the currently connected wallet.                                       |
  | `signTransaction`          | `signTransaction(transactionOrPayload: AnyRawTransaction \| Types.TransactionPayload, asFeePayer?: boolean, options?: InputGenerateTransactionOptions): Promise<AccountAuthenticator>` | Signs a transaction with optional parameters for fee payment.                     |
  | `submitTransaction`        | `submitTransaction(transaction: InputSubmitTransactionData): Promise<PendingTransactionResponse>`                                                                                      | Submits a transaction with the provided transaction data.                         |
  | `signAndSubmitTransaction` | `signAndSubmitTransaction(transaction: InputTransactionData): Promise<any>`                                                                                                            | Signs and submits a transaction with the given input data.                        |
  | `signMessage`              | `signMessage(message: SignMessagePayload): Promise<SignMessageResponse>`                                                                                                               | Signs a message and returns the signature and other response info.                |
  | `signMessageAndVerify`     | `signMessageAndVerify(message: SignMessagePayload): Promise<boolean>`                                                                                                                  | Signs a message and verifies the signer.                                          |
  | `changeNetwork`            | `changeNetwork(network: Network): Promise<AptosChangeNetworkOutput>`                                                                                                                   | Requests a change in the connected network. This is not supported by all wallets. |
</details>

# Digital Asset
URL: /devs/tokenStandard/currentStandard/digitalAsset

# Digital Asset (DA) Standard

The Movement Digital Asset Standard provides a modern, flexible framework for creating and managing Non-Fungible Tokens (NFTs) on Movement. Built on Move Objects, this standard offers enhanced composability, direct transfers, and extensibility that surpasses traditional NFT implementations.

<Callout type="info">
  The Digital Asset standard is available in the Movement framework at `aptos_token_objects` and represents the current standard for NFT development on Movement.
</Callout>

## Overview

Movement's Digital Asset standard enables developers to:

* **Create Sophisticated NFTs**: Build tokens with custom logic, metadata, and behaviors
* **Direct Transfers**: Transfer NFTs without recipient opt-in requirements
* **Enhanced Composability**: NFTs can own other NFTs and complex asset structures
* **Extensible Design**: Leverage Move Objects for unlimited customization possibilities
* **Ecosystem Integration**: Seamless compatibility with Movement's DeFi and gaming protocols

## Core Architecture

### Object-Based Design

The DA standard uses Move Objects to represent digital assets with two primary components:

```move
module aptos_token_objects::collection {
    /// Collection metadata and configuration
    struct Collection has key {
        creator: address,
        description: String,
        name: String,
        uri: String,
        mutation_setting: MutationSetting,
    }
}

module aptos_token_objects::token {
    /// Individual token within a collection
    struct Token has key {
        collection: Object<Collection>,
        description: String,
        name: String,
        uri: String,
        mutation_setting: MutationSetting,
    }
}
```

**Architecture Benefits:**

* **True Ownership**: NFTs are owned objects, not account resources
* **Composability**: Objects can contain other objects for complex structures
* **Extensibility**: Add custom resources and functionality via smart contracts
* **Gas Efficiency**: Optimized storage and transfer mechanisms

### Movement Framework Structures

#### Collections

Collections organize related NFTs under a unified framework:

| Field              | Type            | Description                                         |
| ------------------ | --------------- | --------------------------------------------------- |
| `creator`          | address         | Address of the collection creator                   |
| `description`      | String          | Collection description (max 2048 characters)        |
| `name`             | String          | Unique collection name under creator                |
| `uri`              | String          | URI pointing to collection metadata (max 512 chars) |
| `mutation_setting` | MutationSetting | Controls which fields can be modified               |

#### Tokens

Tokens represent individual NFTs within a collection. Each token is a Move Object that contains metadata and maintains a reference to its parent collection. Tokens can be extended with custom resources to add application-specific functionality such as game attributes, DeFi properties, or any other custom data.

| Field              | Type                 | Description                                                           |
| ------------------ | -------------------- | --------------------------------------------------------------------- |
| `collection`       | `Object<Collection>` | Reference to the parent collection object                             |
| `description`      | String               | Token description (max 2048 characters)                               |
| `name`             | String               | Unique token name within the collection                               |
| `uri`              | String               | URI pointing to off-chain token metadata (max 512 chars)              |
| `mutation_setting` | MutationSetting      | Configuration controlling which fields can be modified after creation |

## Creating Collections on Movement

### Fixed Supply Collections

Fixed supply collections have a predetermined maximum number of tokens that can be minted. This is ideal for limited edition NFT drops, exclusive membership tokens, or any collection where scarcity is important. Use `collection::create_fixed_collection` to create a collection with a hard cap on supply.

```move
module movement_addr::movement_nft_collection {
    use aptos_token_objects::collection;
    use aptos_token_objects::royalty;
    use std::string;
    use std::option;
    use std::signer;

/// Movement Gaming NFT Collection
    struct MovementGamingCollection has key {}

/// Create a Movement gaming collection with fixed supply
    public entry fun create_gaming_collection(creator: &signer) {
        let royalty_config = royalty::create(
            5, // 5% royalty
            100, // denominator
            signer::address_of(creator) // royalty recipient
        );

collection::create_fixed_collection(
            creator,
            string::utf8(b"Exclusive collection of Movement gaming assets featuring unique characters, weapons, and items for the Movement ecosystem"),
            1000, // Maximum 1000 NFTs
            string::utf8(b"Movement Gaming Assets"),
            option::some(royalty_config),
            string::utf8(b"https://gaming.movement.xyz/collection/metadata")
        );
    }
}
```

<Callout type="warning">
  A Collection's maximum supply cannot be changed after creation.
</Callout>

### Unlimited Supply Collections

Unlimited supply collections have no cap on the number of tokens that can be minted. This is suitable for ongoing NFT series, reward tokens, or collections that need to grow over time. Use `collection::create_unlimited_collection` to create an open-ended collection.

```move
module movement_addr::movement_art_collection {
    use aptos_token_objects::collection;
    use aptos_token_objects::royalty;
    use std::string;
    use std::option;

/// Create Movement art collection with unlimited supply
    public entry fun create_art_collection(creator: &signer) {
        let royalty_config = royalty::create(
            10, // 10% royalty for artists
            100,
            signer::address_of(creator)
        );

collection::create_unlimited_collection(
            creator,
            string::utf8(b"Curated digital art collection showcasing the creativity and innovation of the Movement community"),
            string::utf8(b"Movement Digital Art"),
            option::some(royalty_config),
            string::utf8(b"https://art.movement.xyz/collection")
        );
    }
}
```

### Advanced Collection with Custom Features

Since Collections are Move Objects, they can be customized through permission tokens called Refs. These Refs grant the ability to modify specific aspects of the Object after creation. In addition to standard Object Refs, Collections support a specialized MutatorRef that can be obtained by calling `collection::generate_mutator_ref`:

```move
module movement_addr::advanced_movement_collection {
    use aptos_token_objects::collection::{Self, MutatorRef};
    use aptos_token_objects::royalty;
    use aptos_framework::object;
    use std::string;
    use std::option;
    use std::signer;

/// Collection with custom mutability
    struct CustomCollection has key {
        mutator_ref: MutatorRef,
    }

/// Create collection with mutator ref for future updates
    public entry fun create_custom_collection(creator: &signer) {
        let royalty_config = royalty::create(5, 100, signer::address_of(creator));
        
        let constructor_ref = &collection::create_unlimited_collection(
            creator,
            string::utf8(b"Movement collection with mutable metadata"),
            string::utf8(b"Movement Custom Collection"),
            option::some(royalty_config),
            string::utf8(b"https://movement.xyz/metadata")
        );

// Generate mutator ref for later modifications
        let mutator_ref = collection::generate_mutator_ref(constructor_ref);
        let collection_signer = &object::generate_signer(constructor_ref);

// Store mutator ref for future use
        move_to(collection_signer, CustomCollection {
            mutator_ref,
        });
    }

/// Update collection description using stored mutator ref
    public entry fun update_description(
        creator: &signer,
        collection: object::Object<collection::Collection>,
        new_description: string::String
    ) acquires CustomCollection {
        let collection_addr = object::object_address(&collection);
        let custom_collection = borrow_global<CustomCollection>(collection_addr);
        
        collection::set_description(&custom_collection.mutator_ref, new_description);
    }
}
```

<Callout type="info">
  Refs must be generated at creation time of an Object. The ConstructorRef used to generate other Refs expires as soon as the transaction to create the Object is finished.
</Callout>

## Creating Tokens (NFTs)

### Named Tokens

Named tokens have deterministic addresses derived from the creator address, collection name, and token name. This makes them predictable and easy to reference without needing to store the token address. Named tokens are ideal when you need to look up tokens by their identifying information rather than storing addresses. Use `token::create_named_token` to create tokens with deterministic addressing.

```move
module movement_addr::movement_character_nft {
    use aptos_token_objects::token;
    use aptos_token_objects::royalty;
    use std::string;
    use std::option;

/// Create a Movement character NFT
    public entry fun mint_character(
        creator: &signer,
        character_class: String,
        rarity: String,
        power_level: u64
    ) {
        let character_name = string::utf8(b"Movement Warrior #1001");
        
        let description = string::utf8(b"A powerful legendary warrior from the Movement universe with high power level");

let royalty_config = royalty::create(5, 100, signer::address_of(creator));

token::create_named_token(
            creator,
            string::utf8(b"Movement Gaming Assets"),
            description,
            character_name,
            option::some(royalty_config),
            string::utf8(b"https://gaming.movement.xyz/characters/warrior")
        );
    }

// Helper function to convert u64 to string (implementation omitted for brevity)
    fun u64_to_string(value: u64): String {
        // Implementation would convert u64 to string
        string::utf8(b"placeholder")
    }
}
```

<Callout type="info">
  You can derive the address for named tokens by:

* Concatenating the creator address, collection name and token name
  * Doing a sha256 hash of that new string
</Callout>

### Unnamed Tokens with Custom Properties

Unnamed tokens receive unique, non-deterministic addresses at creation time. They offer more flexibility for dynamic minting scenarios where predictable addresses aren't required. Unnamed tokens are commonly used with custom properties stored as additional resources on the token object, enabling rich functionality like equipment stats, character progression, or any application-specific data.

```move
module movement_addr::movement_equipment_nft {
    use aptos_token_objects::token::{Self, MutatorRef, BurnRef};
    use aptos_token_objects::royalty;
    use aptos_framework::object::{Self, Object};
    use aptos_framework::event;
    use std::string::{Self, String};
    use std::option;
    use std::signer;

/// Equipment NFT with custom properties
    struct MovementEquipment has key {
        mutator_ref: MutatorRef,
        burn_ref: BurnRef,
        equipment_type: String,
        rarity: String,
        stats: EquipmentStats,
        upgrade_level: u64,
        durability: u64,
    }

/// Equipment statistics
    struct EquipmentStats has store, drop {
        attack: u64,
        defense: u64,
        speed: u64,
        special_ability: String,
    }

#[event]
    struct EquipmentUpgraded has drop, store {
        token: address,
        old_level: u64,
        new_level: u64,
        new_stats: EquipmentStats,
    }

/// Mint equipment NFT with custom properties
    public entry fun mint_equipment(
        creator: &signer,
        recipient: address,
        equipment_type: String,
        rarity: String,
        base_stats: EquipmentStats
    ) {
        let token_name = string::utf8(b"Movement Legendary Sword");
        
        let description = string::utf8(b"A legendary sword forged in the Movement realm");

let royalty_config = royalty::create(3, 100, signer::address_of(creator));

let constructor_ref = &token::create(
            creator,
            string::utf8(b"Movement Gaming Assets"),
            description,
            token_name,
            option::some(royalty_config),
            string::utf8(b"https://gaming.movement.xyz/equipment/sword")
        );

// Generate refs for customization
        let mutator_ref = token::generate_mutator_ref(constructor_ref);
        let burn_ref = token::generate_burn_ref(constructor_ref);
        let token_signer = &object::generate_signer(constructor_ref);

// Store custom equipment data
        move_to(token_signer, MovementEquipment {
            mutator_ref,
            burn_ref,
            equipment_type,
            rarity,
            stats: base_stats,
            upgrade_level: 1,
            durability: 100,
        });

// Transfer to recipient
        let token = object::object_from_constructor_ref<token::Token>(constructor_ref);
        object::transfer(creator, token, recipient);
    }

/// Upgrade equipment NFT
    public entry fun upgrade_equipment(
        owner: &signer,
        token: `Object<token::Token>`
    ) acquires MovementEquipment {
        let token_addr = object::object_address(&token);
        assert!(object::is_owner(token, signer::address_of(owner)), 1);
        
        let equipment = borrow_global_mut<MovementEquipment>(token_addr);
        let old_level = equipment.upgrade_level;
        
        // Upgrade stats based on level
        equipment.upgrade_level = equipment.upgrade_level + 1;
        equipment.stats.attack = equipment.stats.attack + (equipment.upgrade_level * 5);
        equipment.stats.defense = equipment.stats.defense + (equipment.upgrade_level * 3);
        equipment.stats.speed = equipment.stats.speed + (equipment.upgrade_level * 2);

// Update token description
        let new_description = string::utf8(b"A legendary sword (Level 2) forged in the Movement realm");
        
        token::set_description(&equipment.mutator_ref, new_description);

event::emit(EquipmentUpgraded {
            token: token_addr,
            old_level,
            new_level: equipment.upgrade_level,
            new_stats: equipment.stats,
        });
    }

// Helper function (implementation omitted for brevity)
    fun u64_to_string(value: u64): String { string::utf8(b"placeholder") }
}
```

## Token Operations

### Transfer Operations

The Digital Asset standard enables direct NFT transfers without requiring recipient opt-in, simplifying the user experience. Transfers are performed using the `object::transfer` function, which moves ownership of the NFT object to the specified recipient address.

```move
public entry fun transfer_nft(
    owner: &signer,
    nft: `Object<token::Token>`,
    recipient: address
) {
    object::transfer(owner, nft, recipient);
}
```

### Batch Operations

For applications that need to transfer multiple NFTs in a single transaction, batch operations provide gas efficiency and atomic execution. The following pattern iterates through a list of NFTs and recipients to perform multiple transfers.

```move
public entry fun batch_transfer_nfts(
    owner: &signer,
    nfts: `vector<Object<token::Token>>`,
    recipients: vector<address>
) {
    let len = vector::length(&nfts);
    assert!(len == vector::length(&recipients), 1);

let i = 0;
    while (i < len) {
        let nft = *vector::borrow(&nfts, i);
        let recipient = *vector::borrow(&recipients, i);
        object::transfer(owner, nft, recipient);
        i = i + 1;
    };
}
```

### Burning Tokens

Burning permanently destroys an NFT, removing it from circulation. To burn a token, you must have stored a `BurnRef` during token creation. The burn operation is irreversible and should be used carefully. Common use cases include redemption mechanics, upgrade systems that consume tokens, or cleanup of expired assets.

```move
module movement_addr::nft_burning {
    use aptos_token_objects::token::{Self, BurnRef, Token};
    use aptos_framework::object::{Self, Object};

struct BurnableNFT has key {
        burn_ref: BurnRef,
    }

public entry fun burn_nft(
        owner: &signer,
        nft: `Object<Token>`
    ) acquires BurnableNFT {
        let nft_addr = object::object_address(&nft);
        assert!(object::is_owner(nft, signer::address_of(owner)), 1);
        
        // Remove custom data first
        let BurnableNFT { burn_ref } = move_from<BurnableNFT>(nft_addr);
        
        // Burn the token
        token::burn(burn_ref);
    }
}
```

## Movement Token Module

For creators who want pre-built NFT functionality, Movement provides the `movement_token` module:

```move
module movement_addr::movement_token {
    use aptos_token_objects::aptos_token;
    use std::string::{Self, String};
    use std::vector;
    use aptos_framework::timestamp;
    use aptos_std::bcs;

/// Mint a Movement-branded NFT with properties
    public entry fun mint_movement_nft(
        creator: &signer,
        collection: String,
        description: String,
        name: String,
        uri: String,
        movement_properties: vector<String>
    ) {
        let property_keys = vector[
            string::utf8(b"Movement_Ecosystem"),
            string::utf8(b"Created_On"),
            string::utf8(b"Network"),
        ];
        
        let property_types = vector[
            string::utf8(b"0x1::string::String"),
            string::utf8(b"u64"),
            string::utf8(b"0x1::string::String"),
        ];
        
        let property_values = vector[
            bcs::to_bytes(&string::utf8(b"true")),
            bcs::to_bytes(×tamp::now_seconds()),
            bcs::to_bytes(&string::utf8(b"Movement")),
        ];

// Add custom Movement properties
        vector::append(&mut property_keys, movement_properties);
        // Add corresponding types and values...

aptos_token::mint(
            creator,
            collection,
            description,
            name,
            uri,
            property_keys,
            property_types,
            property_values,
        );
    }

/// Mint soulbound Movement NFT
    public entry fun mint_soulbound_movement_nft(
        creator: &signer,
        collection: String,
        description: String,
        name: String,
        uri: String,
        soul_bound_to: address
    ) {
        let property_keys = vector[
            string::utf8(b"Movement_Soulbound"),
            string::utf8(b"Bound_To"),
        ];
        
        let property_types = vector[
            string::utf8(b"bool"),
            string::utf8(b"address"),
        ];
        
        let property_values = vector[
            bcs::to_bytes(&true),
            bcs::to_bytes(&soul_bound_to),
        ];

aptos_token::mint_soul_bound(
            creator,
            collection,
            description,
            name,
            uri,
            property_keys,
            property_types,
            property_values,
            soul_bound_to,
        );
    }
}
```

## Query Functions

The Digital Asset standard provides a comprehensive query interface for retrieving information about collections, tokens, and ownership. These functions enable applications to read NFT metadata, verify ownership, and build rich user interfaces.

```move
// Collection queries
public fun collection_name<T: key>(collection: `Object<T>`): String
public fun collection_description<T: key>(collection: `Object<T>`): String
public fun collection_uri<T: key>(collection: `Object<T>`): String
public fun collection_creator<T: key>(collection: `Object<T>`): address

// Token queries  
public fun token_name<T: key>(token: `Object<T>`): String
public fun token_description<T: key>(token: `Object<T>`): String
public fun token_uri<T: key>(token: `Object<T>`): String
public fun token_collection<T: key>(token: `Object<T>`): `Object<collection::Collection>`

// Ownership queries
public fun owner<T: key>(object: `Object<T>`): address
public fun is_owner<T: key>(object: `Object<T>`, owner: address): bool
```

## Events and Monitoring

Movement's DA standard emits comprehensive events:

```move
// Collection events
#[event]
struct CollectionCreation has drop, store {
    creator: address,
    collection: address,
    name: String,
}

// Token events
#[event]
struct TokenMutation has drop, store {
    token: address,
    mutated_field_name: String,
}

#[event]
struct Transfer has drop, store {
    object: address,
    from: address,
    to: address,
}

#[event]
struct Burn has drop, store {
    object: address,
    previous_owner: address,
}
```

## Summary

* **Modern NFT framework** built on Move Objects for true ownership and enhanced composability
* **Direct transfers** without recipient opt-in requirements for seamless user experience
* **Flexible addressing** with named tokens (deterministic) and unnamed tokens (custom properties)
* **Collection management** with fixed or unlimited supply (unchangeable after creation)
* **Extensible design** allowing NFTs to own other NFTs and custom resource integration
* **Recommended standard** for new NFT projects, replacing legacy Token standard

# Fungible Asset
URL: /devs/tokenStandard/currentStandard/fungibleAsset

# Fungible Asset (FA) Standard

The Movement Fungible Asset Standard provides a modern, type-safe framework for creating and managing fungible tokens on Movement. Built on the foundation of Move Objects, this standard offers enhanced security, composability, and customization capabilities that surpass traditional token implementations.

<Callout type="info">
  The Fungible Asset standard is available in the Movement framework at `aptos_framework::fungible_asset` and represents the current standard for fungible token development.
</Callout>

## Overview

Movement's Fungible Asset standard enables developers to:

* **Create Sophisticated Tokens**: Build tokens with custom logic, automated behaviors, and advanced features
* **Enhanced Security**: Leverage Move's type safety and object-based architecture for secure token operations
* **Seamless Integration**: Automatic compatibility with Movement ecosystem applications and wallets
* **Advanced Customization**: Implement custom transfer logic, fee mechanisms, and compliance features

## Core Architecture

### Object-Based Design

The FA standard uses two primary Move Objects to represent fungible assets:

```move
module aptos_framework::fungible_asset {
    /// Metadata object containing token information
    struct Metadata has key, copy, drop {
        name: String,
        symbol: String,
        decimals: u8,
        icon_uri: String,
        project_uri: String
    }
    
    /// Store object holding token balances
    struct FungibleStore has key {
        metadata: Object<Metadata>,
        balance: u64,
        frozen: bool
    }
    
    /// Ephemeral token representation for transfers
    struct FungibleAsset {
        metadata: Object<Metadata>,
        amount: u64
    }
}
```

**Architecture Benefits:**

* **Unified Standard**: Single framework for all fungible token types
* **Composability**: Objects can be extended and customized via smart contracts
* **Automatic Management**: Recipients automatically receive storage capabilities
* **Gas Efficiency**: Optimized storage patterns reduce transaction costs

### Movement Framework Structures

The following tables describe the core structures in Movement's FA implementation.

#### \[`Metadata`]

| Field         | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| `name`        | String | Full name of the fungible asset      |
| `symbol`      | String | Short symbol (e.g., "MOVE", "USDT")  |
| `decimals`    | u8     | Number of decimal places for display |
| `icon_uri`    | String | URI pointing to token icon image     |
| `project_uri` | String | URI pointing to project website      |

#### \[`FungibleStore`]

| Field      | Type               | Description                                 |
| ---------- | ------------------ | ------------------------------------------- |
| `metadata` | `Object<Metadata>` | Reference to the token's metadata object    |
| `balance`  | `u64`              | Current token balance in this store         |
| `frozen`   | `bool`             | Whether transfers are frozen for this store |

#### \[`FungibleAsset`]

| Field      | Type               | Description                              |
| ---------- | ------------------ | ---------------------------------------- |
| `metadata` | `Object<Metadata>` | Reference to the token's metadata object |
| `amount`   | `u64`              | Amount of tokens in this asset instance  |

## Creating Fungible Assets on Movement

### Basic Token Creation

The simplest way to create a fungible asset is using `primary_fungible_store::create_primary_store_enabled_fungible_asset`. This function creates a token with automatic store management, meaning recipients don't need to manually create storage for the token. The function returns capability references (`MintRef`, `TransferRef`, `BurnRef`) that must be stored securely for later token management operations.

```move
module movement_addr::movement_token {
    use aptos_framework::fungible_asset::{Self, MintRef, TransferRef, BurnRef};
    use aptos_framework::object::{Self, Object};
    use aptos_framework::primary_fungible_store;
    use std::string;
    use std::option;
    use std::signer;

/// Movement ecosystem token
    struct MovementToken has key {}

/// Initialize a new Movement token
    public entry fun create_movement_token(creator: &signer) {
        // Create non-deletable object for token metadata
        let constructor_ref = &object::create_named_object(
            creator, 
            b"MOVEMENT_TOKEN"
        );

// Create the fungible asset with Movement branding
        primary_fungible_store::create_primary_store_enabled_fungible_asset(
            constructor_ref,
            option::some(1000000000), // 1B max supply
            string::utf8(b"Movement Token"),
            string::utf8(b"MOVE"),
            8, // 8 decimals
            string::utf8(b"https://movement.xyz/assets/move-token.png"),
            string::utf8(b"https://movement.xyz")
        );

// Generate capability references
        let mint_ref = fungible_asset::generate_mint_ref(constructor_ref);
        let transfer_ref = fungible_asset::generate_transfer_ref(constructor_ref);
        let burn_ref = fungible_asset::generate_burn_ref(constructor_ref);

// Store capabilities in a resource
        move_to(creator, MovementTokenRefs {
            mint_ref,
            transfer_ref,
            burn_ref,
        });
    }

/// Resource to store token capabilities
    struct MovementTokenRefs has key {
        mint_ref: MintRef,
        transfer_ref: TransferRef,
        burn_ref: BurnRef,
    }
}
```

### Advanced Token with Custom Features

For more sophisticated use cases, you can create tokens with custom logic such as fee collection, time-based restrictions, or integration with other protocols. This example demonstrates a DeFi token with automatic fee collection on minting operations. The token configuration stores additional state like fee rates and launch timestamps.

```move
module movement_addr::advanced_movement_token {
    use aptos_framework::fungible_asset::{Self, MintRef, TransferRef, BurnRef, FungibleAsset};
    use aptos_framework::primary_fungible_store;
    use aptos_framework::object::{Self, Object};
    use aptos_framework::event;
    use aptos_framework::timestamp;
    use std::string;
    use std::option;
    use std::signer;

/// Advanced Movement DeFi token
    struct MovementDeFiToken has key {}

/// Token configuration and state
    struct TokenConfig has key {
        mint_ref: MintRef,
        transfer_ref: TransferRef,
        burn_ref: BurnRef,
        fee_rate: u64,           // Fee rate in basis points (100 = 1%)
        fee_collector: address,   // Address that receives fees
        total_fees_collected: u64,
        launch_time: u64,
    }

/// Fee collection event
    #[event]
    struct FeeCollected has drop, store {
        amount: u64,
        from_transfer: u64,
        collector: address,
    }

/// Create advanced Movement DeFi token
    public entry fun create_advanced_token(
        creator: &signer,
        fee_rate: u64,
        fee_collector: address
    ) {
        assert!(fee_rate <= 1000, 1); // Max 10% fee
        
        let constructor_ref = &object::create_named_object(
            creator,
            b"MOVEMENT_DEFI_TOKEN"
        );

// Create fungible asset with Movement DeFi branding
        primary_fungible_store::create_primary_store_enabled_fungible_asset(
            constructor_ref,
            option::none(), // Unlimited supply for DeFi use cases
            string::utf8(b"Movement DeFi Token"),
            string::utf8(b"MOVEFI"),
            18, // High precision for DeFi
            string::utf8(b"https://movement.xyz/assets/movefi-token.png"),
            string::utf8(b"https://defi.movement.xyz")
        );

// Generate capabilities
        let mint_ref = fungible_asset::generate_mint_ref(constructor_ref);
        let transfer_ref = fungible_asset::generate_transfer_ref(constructor_ref);
        let burn_ref = fungible_asset::generate_burn_ref(constructor_ref);

// Store configuration
        move_to(creator, TokenConfig {
            mint_ref,
            transfer_ref,
            burn_ref,
            fee_rate,
            fee_collector,
            total_fees_collected: 0,
            launch_time: timestamp::now_seconds(),
        });
    }

/// Mint tokens with automatic fee collection
    public entry fun mint_with_fee(
        creator: &signer,
        recipient: address,
        amount: u64
    ) acquires TokenConfig {
        let config = borrow_global_mut<TokenConfig>(signer::address_of(creator));
        
        // Calculate fee
        let fee_amount = (amount * config.fee_rate) / 10000;
        let net_amount = amount - fee_amount;

// Mint tokens
        let tokens = fungible_asset::mint(&config.mint_ref, amount);
        
        // Split for fee collection
        if (fee_amount > 0) {
            let fee_tokens = fungible_asset::extract(&mut tokens, fee_amount);
            primary_fungible_store::deposit(config.fee_collector, fee_tokens);
            
            config.total_fees_collected = config.total_fees_collected + fee_amount;
            
            event::emit(FeeCollected {
                amount: fee_amount,
                from_transfer: amount,
                collector: config.fee_collector,
            });
        }

// Deposit remaining tokens to recipient
        primary_fungible_store::deposit(recipient, tokens);
    }
}
```

## Token Operations

### For Token Creators

#### Minting Tokens

Minting creates new token instances and adds them to circulation. The `MintRef` capability is required to mint tokens, ensuring only authorized accounts can increase the token supply. After minting, tokens must be deposited to a recipient's store using `primary_fungible_store::deposit`.

```move
public entry fun mint_tokens(
    creator: &signer,
    recipient: address,
    amount: u64
) acquires MovementTokenRefs {
    let refs = borrow_global<MovementTokenRefs>(signer::address_of(creator));
    let tokens = fungible_asset::mint(&refs.mint_ref, amount);
    primary_fungible_store::deposit(recipient, tokens);
}
```

#### Batch Minting for Airdrops

For token distributions like airdrops, batch minting allows you to efficiently send tokens to multiple recipients in a single transaction. This reduces gas costs compared to individual transfers and ensures atomic execution where all transfers succeed or none do.

```move
public entry fun airdrop_tokens(
    creator: &signer,
    recipients: vector<address>,
    amounts: vector<u64>
) acquires MovementTokenRefs {
    let refs = borrow_global<MovementTokenRefs>(signer::address_of(creator));
    let len = vector::length(&recipients);
    assert!(len == vector::length(&amounts), 1);

let i = 0;
    while (i < len) {
        let recipient = *vector::borrow(&recipients, i);
        let amount = *vector::borrow(&amounts, i);
        
        let tokens = fungible_asset::mint(&refs.mint_ref, amount);
        primary_fungible_store::deposit(recipient, tokens);
        
        i = i + 1;
    };
}
```

#### Freezing and Unfreezing Accounts

The freeze functionality allows token creators to restrict transfers for specific accounts. This is useful for compliance requirements, security incidents, or implementing vesting schedules. The `TransferRef` capability is required to freeze or unfreeze accounts.

```move
public entry fun freeze_account(
    creator: &signer,
    account: address,
    metadata: Object<Metadata>
) acquires MovementTokenRefs {
    let refs = borrow_global<MovementTokenRefs>(signer::address_of(creator));
    let store = primary_fungible_store::primary_store(account, metadata);
    fungible_asset::set_frozen_flag(&refs.transfer_ref, store, true);
}

public entry fun unfreeze_account(
    creator: &signer,
    account: address,
    metadata: Object<Metadata>
) acquires MovementTokenRefs {
    let refs = borrow_global<MovementTokenRefs>(signer::address_of(creator));
    let store = primary_fungible_store::primary_store(account, metadata);
    fungible_asset::set_frozen_flag(&refs.transfer_ref, store, false);
}
```

### For Token Users

#### Basic Transfer Operations

Users can transfer tokens using `primary_fungible_store::transfer`, which handles withdrawing from the sender's store and depositing to the recipient's store in a single atomic operation. The recipient's store is automatically created if it doesn't exist.

```move
public entry fun transfer_tokens(
    sender: &signer,
    metadata: Object<Metadata>,
    recipient: address,
    amount: u64
) {
    primary_fungible_store::transfer(sender, metadata, recipient, amount);
}
```

#### Batch Transfers

Batch transfers allow sending tokens to multiple recipients in a single transaction, reducing gas costs and ensuring atomic execution. This is useful for payroll systems, reward distributions, or any scenario requiring multiple simultaneous transfers.

```move
public entry fun batch_transfer(
    sender: &signer,
    metadata: Object<Metadata>,
    recipients: vector<address>,
    amounts: vector<u64>
) {
    let len = vector::length(&recipients);
    assert!(len == vector::length(&amounts), 1);

let i = 0;
    while (i < len) {
        let recipient = *vector::borrow(&recipients, i);
        let amount = *vector::borrow(&amounts, i);
        
        primary_fungible_store::transfer(sender, metadata, recipient, amount);
        i = i + 1;
    };
}
```

#### Conditional Transfers

Conditional transfers add validation logic before executing a transfer. This example ensures the sender maintains a minimum balance after the transfer, which is useful for preventing users from accidentally depleting their entire balance or for implementing reserve requirements.

```move
public entry fun conditional_transfer(
    sender: &signer,
    metadata: Object<Metadata>,
    recipient: address,
    amount: u64,
    min_balance_required: u64
) {
    // Check sender has sufficient balance beyond minimum
    let sender_balance = primary_fungible_store::balance(
        signer::address_of(sender), 
        metadata
    );
    assert!(
        sender_balance >= amount + min_balance_required, 
        1
    );

primary_fungible_store::transfer(sender, metadata, recipient, amount);
}
```

## Dispatchable Fungible Assets (Advanced)

Movement supports Dispatchable Fungible Assets (DFA) that execute custom logic during transfers.

### Custom Transfer Logic

Dispatchable Fungible Assets allow you to intercept and customize withdraw and deposit operations. This enables advanced features like automatic fee collection, transfer taxes, bonus rewards, or compliance checks. The custom logic is registered during token creation and executes automatically on every transfer.

```move
module movement_addr::fee_collecting_token {
    use aptos_framework::fungible_asset::{Self, FungibleAsset, TransferRef};
    use aptos_framework::object::{Self, Object};
    use aptos_framework::primary_fungible_store;
    use aptos_framework::dispatchable_fungible_asset;
    use aptos_framework::function_info;
    use std::string;
    use std::option;

/// Custom withdraw with fee collection
    public fun withdraw<T: key>(
        store: Object<T>,
        amount: u64,
        transfer_ref: &TransferRef,
    ): FungibleAsset {
        // Calculate fee (1% of transfer)
        let fee_amount = amount / 100;
        let net_amount = amount - fee_amount;

// Withdraw full amount
        let fa = fungible_asset::withdraw_with_ref(transfer_ref, store, amount);
        
        // Extract fee portion
        let fee_fa = fungible_asset::extract(&mut fa, fee_amount);
        
        // Deposit fee to protocol treasury
        let treasury = get_treasury_address();
        primary_fungible_store::deposit(treasury, fee_fa);

fa // Return net amount
    }

/// Custom deposit with bonus rewards
    public fun deposit<T: key>(
        store: Object<T>,
        fa: FungibleAsset,
        transfer_ref: &TransferRef,
    ) {
        let amount = fungible_asset::amount(&fa);
        
        // Calculate bonus (0.1% of deposit)
        let bonus_amount = amount / 1000;
        
        // Deposit original amount
        fungible_asset::deposit_with_ref(transfer_ref, store, fa);
        
        // Mint and deposit bonus
        if (bonus_amount > 0) {
            let mint_ref = get_mint_ref();
            let bonus_fa = fungible_asset::mint(mint_ref, bonus_amount);
            fungible_asset::deposit_with_ref(transfer_ref, store, bonus_fa);
        }
    }

/// Register dispatch functions
    public entry fun setup_dispatchable_token(creator: &signer) {
        let constructor_ref = &object::create_named_object(
            creator,
            b"MOVEMENT_FEE_TOKEN"
        );

// Create the fungible asset
        primary_fungible_store::create_primary_store_enabled_fungible_asset(
            constructor_ref,
            option::some(10000000000), // 10B max supply
            string::utf8(b"Movement Fee Token"),
            string::utf8(b"MOVEFEE"),
            8,
            string::utf8(b"https://movement.xyz/assets/fee-token.png"),
            string::utf8(b"https://movement.xyz")
        );

// Create function info for dispatch
        let withdraw_function = function_info::new_function_info(
            creator,
            string::utf8(b"fee_collecting_token"),
            string::utf8(b"withdraw")
        );

let deposit_function = function_info::new_function_info(
            creator,
            string::utf8(b"fee_collecting_token"),
            string::utf8(b"deposit")
        );

// Register dispatch functions
        dispatchable_fungible_asset::register_dispatch_functions(
            constructor_ref,
            option::some(withdraw_function),
            option::some(deposit_function),
            option::none()
        );
    }

// Helper functions
    fun get_treasury_address(): address { @movement_treasury }
    fun get_mint_ref(): &fungible_asset::MintRef { 
        // Implementation to retrieve stored mint ref
        abort 0
    }
}
```

## Query Functions

The Fungible Asset standard provides a comprehensive query interface for retrieving token metadata, supply information, balances, and store status. These functions enable applications to display token information, verify balances before transfers, and check account states.

```move
// Token metadata queries
public fun name<T: key>(metadata: Object<T>): String
public fun symbol<T: key>(metadata: Object<T>): String  
public fun decimals<T: key>(metadata: Object<T>): u8
public fun icon_uri<T: key>(metadata: Object<T>): String
public fun project_uri<T: key>(metadata: Object<T>): String

// Supply information
public fun supply<T: key>(metadata: Object<T>): Option<u128>
public fun maximum<T: key>(metadata: Object<T>): Option<u128>

// Balance queries
public fun balance<T: key>(store: Object<T>): u64
public fun primary_store_balance<T: key>(account: address, metadata: Object<T>): u64

// Store status
public fun is_frozen<T: key>(store: Object<T>): bool
public fun store_exists(store: address): bool
```

## Events and Monitoring

Movement's FA standard emits comprehensive events for tracking:

```move
// Core transfer events
#[event]
struct Deposit has drop, store {
    store: address,
    amount: u64,
}

#[event]
struct Withdraw has drop, store {
    store: address,
    amount: u64,
}

#[event]
struct Frozen has drop, store {
    store: address,
    frozen: bool,
}

// Creation and management events
#[event]
struct Creation has drop, store {
    metadata: address,
    name: String,
    symbol: String,
    decimals: u8,
    maximum_supply: Option<u128>,
}
```

## Summary

* **Modern framework** built on Move Objects with automatic store management for recipients
* **Capability-based access** through `MintRef`, `TransferRef`, and `BurnRef` for secure operations
* **Advanced features** including dispatchable tokens with custom transfer logic
* **Batch operations** for efficient airdrops and multi-recipient transfers
* **Enhanced security** with protected capability refs and automatic storage creation
* **Recommended standard** for new fungible token projects, replacing legacy Coin

# Coin (Legacy)
URL: /devs/tokenStandard/legacyStandard/coin

# Coin (Legacy Standard)

The [Coin standard](https://github.com/movement-network/aptos-core/blob/m1/aptos-move/framework/aptos-framework/sources/coin.move) provides a robust, type-safe framework for creating fungible tokens on Movement. Built on Move's phantom type system, it enables developers to create distinct coin types while leveraging shared infrastructure.

<Callout type="info">
  The Coin standard is available in the Movement framework at `0x1::coin`.
</Callout>

<Callout type="warning">
  This is the legacy coin standard. For new projects on Movement, consider using the updated [Fungible Asset Standard](/devs/tokenStandard/currentStandard/fungibleAsset/) which offers enhanced features and better composability.
</Callout>

## Core Architecture

### Reusable Token Framework

The fundamental `Coin` struct uses phantom types to support multiple distinct tokens:

```move
module 0x1::coin {
  struct Coin<phantom CoinType> has store {
    /// Amount of coin this address has.
    value: u64,
  }
}
```

**Key Benefits:**

* **Type Safety**: `Coin<MOVE>` and `Coin<USDC>` are completely different types
* **Code Reuse**: Single implementation supports unlimited token types
* **Storage Efficiency**: Minimal on-chain footprint per token instance
* **Composability**: Easy integration with other Move modules and protocols

### Account Storage

Movement stores coins in user accounts using the `CoinStore` resource:

```move
module 0x1::coin {
  struct CoinStore<phantom CoinType> has key {
    coin: Coin<CoinType>,
    frozen: bool,
    deposit_events: EventHandle<DepositEvent>,
    withdraw_events: EventHandle<WithdrawEvent>,
  }
}
```

### Token Metadata

Token information and metadata are stored under the creator's account:

```move
module 0x1::coin {
  struct CoinInfo<phantom CoinType> has key {
    name: string::String,
    /// Symbol of the coin, usually a shorter version of the name.
    /// For example, Movement Token is MOVE.
    symbol: string::String,
    /// Number of decimals used to get its user representation.
    /// For example, if `decimals` equals `8`, a balance of `100000000` coins should
    /// be displayed to a user as `1.00000000` (`100000000 / 10 ** 8`).
    decimals: u8,
    /// Amount of this coin type in existence.
    supply: Option<OptionalAggregator>,
  }
}
```

## Movement Framework Structures

The following tables describe the core structures in Movement's coin implementation. For the complete reference, see the [Movement Framework Documentation](https://github.com/movement-network/aptos-core/blob/movement/aptos-move/framework/aptos-framework/doc/coin.md).

### \[`Coin<CoinType>`]

| Field   | Type | Description                                    |
| ------- | ---- | ---------------------------------------------- |
| `value` | u64  | Token amount (e.g., 1000000000 for 10.00 MOVE) |

### \[`CoinStore<CoinType>`]

| Field             | Type                         | Description                                 |
| ----------------- | ---------------------------- | ------------------------------------------- |
| `coin`            | `Coin<CoinType>`             | The actual coin balance held in the store   |
| `frozen`          | bool                         | Whether deposits and withdrawals are frozen |
| `deposit_events`  | `EventHandle<DepositEvent>`  | Event handle for tracking deposits          |
| `withdraw_events` | `EventHandle<WithdrawEvent>` | Event handle for tracking withdrawals       |

### \[`CoinInfo<CoinType>`]

| Field      | Type                         | Description                                                                      |
| ---------- | ---------------------------- | -------------------------------------------------------------------------------- |
| `name`     | String                       | Full token name (e.g., "Movement Token")                                         |
| `symbol`   | String                       | Token symbol (e.g., "MOVE")                                                      |
| `decimals` | u8                           | Decimal precision; MOVE uses 8 decimals, so 100000000 represents 1.00000000 MOVE |
| `supply`   | `Option<OptionalAggregator>` | Optional supply tracking for monitoring total tokens in circulation              |

## Token Operations

Movement's coin standard provides comprehensive functionality for both token creators and users.

### For Token Creators

Token creators have privileged access to manage their tokens through capabilities.

#### Initialize a New Token

The `initialize` function creates and registers a new token type on Movement. This function must be called from the account that deployed the token module and can only be executed once per token type. It returns three capability tokens (`BurnCapability`, `FreezeCapability`, `MintCapability`) that grant privileged access to token management operations and must be stored securely.

```move
module 0x1::coin {
  public fun initialize<CoinType>(
    account: &signer,
    name: string::String,
    symbol: string::String,
    decimals: u8,
    monitor_supply: bool,
  ): (BurnCapability<CoinType>, FreezeCapability<CoinType>, MintCapability<CoinType>) {
    // Implementation details...
  }
}
```

**Example: Creating a Movement-based Token**

```move
// Define your token type
struct MovementUSD {}

// Initialize the token
public fun initialize_movement_usd(creator: &signer) {
    let (burn_cap, freeze_cap, mint_cap) = coin::initialize<MovementUSD>(
        creator,
        string::utf8(b"Movement USD"),
        string::utf8(b"mUSD"),
        6, // 6 decimal places for USD precision
        true // Monitor supply for transparency
    );
    
    // Store capabilities securely
    move_to(creator, TokenCapabilities {
        burn_cap,
        freeze_cap,
        mint_cap
    });
}
```

**Requirements:**

* Must be called from the account that deployed the token module
* Token name ≤ 32 characters
* Token symbol ≤ 10 characters
* Decimals is typically between 6 and 18 for most tokens
* Can only be initialized once per token type

#### Mint New Tokens

Minting creates new token instances and adds them to the total supply. The `MintCapability` is required to mint tokens, ensuring only authorized accounts can increase circulation. The minted tokens are returned as a `Coin` struct that must then be deposited to a recipient's account.

```move
module 0x1::coin {
  public fun mint<CoinType>(
    amount: u64,
    _cap: &MintCapability<CoinType>,
  ): Coin<CoinType> {
    // Implementation...
  }
}
```

**Example Usage:**

```move
// Mint tokens for initial distribution
public fun mint_musd_for_liquidity(
    amount: u64, 
    mint_cap: &MintCapability<MovementUSD>
): Coin<MovementUSD> {
    coin::mint<MovementUSD>(amount, mint_cap)
}

// Mint and directly deposit to recipient
public fun airdrop_musd(
    recipient: address, 
    amount: u64, 
    mint_cap: &MintCapability<MovementUSD>
) {
    let tokens = coin::mint<MovementUSD>(amount, mint_cap);
    coin::deposit<MovementUSD>(recipient, tokens);
}
```

#### Burn Tokens

Burning permanently removes tokens from circulation, reducing the total supply. The `BurnCapability` is required for this operation. Two variants exist: `burn` destroys tokens from a `Coin` struct, while `burn_from` removes tokens directly from a user's `CoinStore` (commonly used for transaction fees).

```move
module 0x1::coin {
  public fun burn<CoinType>(
    coin: Coin<CoinType>,
    _cap: &BurnCapability<CoinType>,
  ) {
    // Implementation...
  }
  
  public fun burn_from<CoinType>(
    account_addr: address,
    amount: u64,
    burn_cap: &BurnCapability<CoinType>,
  ) {
    // Implementation...
  }
}
```

<Callout type="info">
  **burn vs burn\_from**

The `burn` function destroys tokens from a `Coin` struct, while `burn_from` removes tokens directly from a user's `CoinStore`. The `burn_from` function bypasses frozen status and is commonly used for transaction fees on Movement.
</Callout>

#### Freeze/Unfreeze Accounts

The freeze functionality allows token creators to restrict deposits and withdrawals for specific accounts. This is useful for compliance requirements, security incidents, or implementing controlled token releases. The `FreezeCapability` is required to freeze or unfreeze accounts.

```move
module 0x1::coin {
  public entry fun freeze_coin_store<CoinType>(
    account_addr: address,
    _freeze_cap: &FreezeCapability<CoinType>,
  ) {
    // Implementation...
  }
  
  public entry fun unfreeze_coin_store<CoinType>(
    account_addr: address,
    _freeze_cap: &FreezeCapability<CoinType>,
  ) {
    // Implementation...
  }
}
```

### For Token Users

Regular users can interact with tokens through standard operations.

#### Register for Token

Before an account can receive a specific token type, it must register for that token by creating a `CoinStore` resource. This is a one-time operation per token type and is required because the legacy coin standard requires explicit opt-in for token receipt.

```move
module 0x1::coin {
  public fun register<CoinType>(account: &signer) {
    // Implementation...
  }
}
```

**Example:**

```move
// Register to receive Movement USD
public entry fun register_for_musd(user: &signer) {
    coin::register<MovementUSD>(user);
}
```

#### Transfer Tokens

The `transfer` function moves tokens from one account to another in a single atomic operation. It handles both the withdrawal from the sender and deposit to the recipient, emitting events for both operations. The recipient must have already registered for the token type.

```move
module 0x1::coin {
  public entry fun transfer<CoinType>(
    from: &signer,
    to: address,
    amount: u64,
  ) {
    // Implementation...
  }
}
```

<Callout type="info">
  This operation emits both `WithdrawEvent` and `DepositEvent` for complete transaction tracking on Movement.
</Callout>

#### Merge Token Amounts

The `merge` function combines two `Coin` instances into one by adding the source coin's value to the destination coin. The source coin is consumed in the process. This is useful when aggregating tokens from multiple sources before a single deposit or transfer.

```move
// Merge two token amounts
public fun merge<CoinType>(
    dst_coin: &mut Coin<CoinType>,
    source_coin: Coin<CoinType>,
)
```

#### Extract Token Amounts

The `extract` function splits a `Coin` by removing a specified amount and returning it as a new `Coin` instance. The original coin's value is reduced accordingly. This is useful for partial transfers or when you need to separate tokens for different purposes.

```move
// Extract specific amount from tokens
public fun extract<CoinType>(
    coin: &mut Coin<CoinType>,
    amount: u64,
): Coin<CoinType>
```

#### Withdraw Tokens

The `withdraw` function removes tokens from the caller's `CoinStore` and returns them as a `Coin` struct. This is the first step in a manual transfer process and emits a `WithdrawEvent`. The caller must have sufficient balance and the account must not be frozen.

```move
// Withdraw tokens from account
public fun withdraw<CoinType>(
    account: &signer,
    amount: u64,
): Coin<CoinType>
```

#### Deposit Tokens

The `deposit` function adds tokens from a `Coin` struct to an account's `CoinStore`. This is typically used after minting or withdrawing tokens. The recipient account must have registered for the token type and must not be frozen. A `DepositEvent` is emitted upon successful deposit.

```move
// Deposit tokens to account
public fun deposit<CoinType>(
    account_addr: address,
    coin: Coin<CoinType>,
)
```

## Additional Functions

Movement provides enhanced tooling for coin development, organized into query and utility functions.

### Query Functions

Query functions allow you to retrieve token information without modifying state. These are essential for building user interfaces, validating balances before transfers, and monitoring token supply.

```move
// Get account balance for a specific token type
public fun balance<CoinType>(owner: address): u64

// Get total supply of tokens in circulation
public fun supply<CoinType>(): Option<u128>

// Get token name
public fun name<CoinType>(): string::String

// Get token symbol
public fun symbol<CoinType>(): string::String

// Get token decimal precision
public fun decimals<CoinType>(): u8
```

### Utility Functions

Utility functions help verify account states and token properties. These are useful for validation checks before performing operations and for building conditional logic in smart contracts.

```move
// Check if account is registered for a token type
public fun is_account_registered<CoinType>(account: address): bool

// Check if account's coin store is frozen
public fun is_coin_store_frozen<CoinType>(account: address): bool

// Get value from a Coin struct
public fun value<CoinType>(coin: &Coin<CoinType>): u64
```

## Events and Monitoring

Movement's coin standard emits comprehensive events for tracking:

```move
/// Emitted when tokens are deposited to an account
struct DepositEvent has drop, store {
    amount: u64,
}

/// Emitted when tokens are withdrawn from an account  
struct WithdrawEvent has drop, store {
    amount: u64,
}
```

## Summary

* **Legacy framework** using Move's phantom types for type-safe, distinct coin types
* **Capability-based access** through `MintCapability`, `BurnCapability`, and `FreezeCapability`
* **Manual registration** required for users before receiving tokens via `CoinStore` resources
* **Event tracking** with comprehensive deposit and withdraw event emission
* **Proven stability** for existing projects with full ecosystem compatibility
* **Migration recommended** to [Fungible Asset Standard](/devs/tokenStandard/currentStandard/fungibleAsset/) for new projects

# Token (Legacy)
URL: /devs/tokenStandard/legacyStandard/token

# Token (Legacy Standard)

The [Token standard](https://github.com/movement-network/aptos-core/blob/m1/aptos-move/framework/aptos-token/sources/token.move) provides a comprehensive framework for creating and managing collections of tokens on Movement. This standard supports fungible tokens (FTs), non-fungible tokens (NFTs), and semi-fungible tokens (SFTs) within a unified system, enabling creators to build complex token ecosystems with rich metadata and customizable properties.

<Callout type="info">
  The Token standard is available in the Movement framework at `aptos_token::token`.
</Callout>

<Callout type="warning">
  This is the legacy token standard. For new projects on Movement, consider using the updated [Digital Asset Standard](/devs/tokenStandard/currentStandard/digitalAsset) for NFTs or [Fungible Asset Standard](/devs/tokenStandard/currentStandard/fungibleAsset) for fungible tokens, which offer enhanced features and better composability.
</Callout>

## Core Architecture

### Multi-Token Framework

The Token standard uses a hierarchical structure to organize tokens:

```move
module aptos_token::token {
    /// Core token structure supporting all token types
    struct Token has store {
        id: TokenId,
        amount: u64,
        token_properties: PropertyMap,
    }
    
    /// Global unique identifier for tokens
    struct TokenId has store, copy, drop {
        token_data_id: TokenDataId,
        property_version: u64,
    }
    
    /// Identifier for shared token data
    struct TokenDataId has copy, drop, store {
        creator: address,
        collection: String,
        name: String,
    }
}
```

**Key Benefits:**

* **Unified Standard**: Single framework handles all token types (FT, NFT, SFT)
* **Efficient Storage**: Shared token data reduces on-chain storage requirements
* **Version Control**: Property versioning enables token evolution and customization
* **Creator Control**: Comprehensive mutability and capability management

### Collection Structure

Collections organize related tokens under a common framework:

```move
module aptos_token::token {
    /// Collection metadata and configuration
    struct CollectionData has store {
        description: String,
        name: String,
        uri: String,
        supply: u64,
        maximum: u64,
        mutability_config: CollectionMutabilityConfig,
    }
    
    /// Controls which collection fields can be modified
    struct CollectionMutabilityConfig has copy, store, drop {
        description: bool,
        uri: bool,
        maximum: bool,
    }
}
```

### Token Data and Metadata

Shared token information is stored in `TokenData`:

```move
module aptos_token::token {
    /// Shared data for tokens with the same TokenDataId
    struct TokenData has store {
        maximum: u64,
        largest_property_version: u64,
        supply: u64,
        uri: String,
        royalty: Royalty,
        name: String,
        description: String,
        default_properties: PropertyMap,
        mutability_config: TokenMutabilityConfig,
    }
    
    /// Royalty configuration for creator economics
    struct Royalty has copy, drop, store {
        royalty_points_numerator: u64,
        royalty_points_denominator: u64,
        payee_address: address,
    }
}
```

## Movement Framework Structures

The following tables describe the core structures in Movement's token implementation.

### \[`Token`]

| Field              | Type        | Description                                        |
| ------------------ | ----------- | -------------------------------------------------- |
| `id`               | TokenId     | Unique identifier for this specific token instance |
| `amount`           | u64         | Quantity of tokens (1 for NFTs, >1 for FTs/SFTs)   |
| `token_properties` | PropertyMap | Instance-specific properties for this token        |

### \[`TokenId`]

| Field              | Type        | Description                                 |
| ------------------ | ----------- | ------------------------------------------- |
| `token_data_id`    | TokenDataId | Reference to shared token data              |
| `property_version` | u64         | Version number for token property mutations |

### \[`TokenDataId`]

| Field        | Type    | Description                                    |
| ------------ | ------- | ---------------------------------------------- |
| `creator`    | address | Address of the token creator                   |
| `collection` | String  | Name of the collection this token belongs to   |
| `name`       | String  | Unique name of the token within the collection |

### \[`CollectionData`]

| Field               | Type                       | Description                                 |
| ------------------- | -------------------------- | ------------------------------------------- |
| `description`       | String                     | Collection description                      |
| `name`              | String                     | Unique collection name under creator        |
| `uri`               | String                     | URI pointing to collection metadata         |
| `supply`            | u64                        | Current number of token types in collection |
| `maximum`           | u64                        | Maximum token types allowed (0 = unlimited) |
| `mutability_config` | CollectionMutabilityConfig | Controls which fields can be modified       |

### \[`TokenData`]

| Field                      | Type                  | Description                                        |
| -------------------------- | --------------------- | -------------------------------------------------- |
| `maximum`                  | u64                   | Maximum supply for this token type (0 = unlimited) |
| `largest_property_version` | u64                   | Highest property version used                      |
| `supply`                   | u64                   | Current circulating supply                         |
| `uri`                      | String                | URI pointing to token metadata                     |
| `royalty`                  | Royalty               | Royalty configuration for secondary sales          |
| `name`                     | String                | Token name (unique within collection)              |
| `description`              | String                | Token description                                  |
| `default_properties`       | PropertyMap           | Default properties for new token instances         |
| `mutability_config`        | TokenMutabilityConfig | Controls which fields can be modified              |

## Token Operations

Movement's token standard provides comprehensive functionality for creators and users.

### For Collection Creators

#### Create a Collection

Collections serve as containers for organizing related tokens under a common framework. Before creating any tokens, you must first create a collection. The `mutate_setting` parameter controls which collection properties (description, URI, maximum) can be modified after creation.

```move
public fun create_collection(
    creator: &signer,
    name: String,
    description: String,
    uri: String,
    maximum: u64,
    mutate_setting: vector<bool>
) acquires Collections
```

**Example: Creating a Movement NFT Collection**

```move
public entry fun create_movement_nft_collection(creator: &signer) {
    let mutate_setting = vector<bool>[
        true,  // description mutable
        true,  // uri mutable  
        false  // maximum immutable
    ];
    
    token::create_collection(
        creator,
        string::utf8(b"Movement Pioneers"),
        string::utf8(b"Exclusive NFT collection for Movement ecosystem pioneers"),
        string::utf8(b"https://movement.xyz/metadata/pioneers"),
        1000, // Maximum 1000 NFTs
        mutate_setting
    );
}
```

#### Create Token Data

Token data defines the template for tokens within a collection, including metadata, royalty configuration, and default properties. Each token data entry represents a unique token type that can have multiple instances (for FTs/SFTs) or a single instance (for NFTs). Properties are stored as key-value pairs with explicit type information.

```move
public fun create_tokendata(
    account: &signer,
    collection: String,
    name: String,
    description: String,
    maximum: u64,
    uri: String,
    royalty_payee_address: address,
    royalty_points_denominator: u64,
    royalty_points_numerator: u64,
    token_mutate_config: TokenMutabilityConfig,
    property_keys: vector<String>,
    property_values: vector<vector<u8>>,
    property_types: vector<String>
): TokenDataId acquires Collections
```

**Example: Creating an NFT with Properties**

```move
public fun create_pioneer_nft(
    creator: &signer,
    pioneer_id: u64,
    rarity: String,
    special_ability: String
): TokenDataId {
    let property_keys = vector<String>[
        string::utf8(b"pioneer_id"),
        string::utf8(b"rarity"),
        string::utf8(b"special_ability"),
        string::utf8(b"TOKEN_BURNABLE_BY_CREATOR")
    ];
    
    let property_values = vector<vector<u8>>[
        bcs::to_bytes<u64>(&pioneer_id),
        bcs::to_bytes<String>(&rarity),
        bcs::to_bytes<String>(&special_ability),
        bcs::to_bytes<bool>(&true)
    ];
    
    let property_types = vector<String>[
        string::utf8(b"u64"),
        string::utf8(b"0x1::string::String"),
        string::utf8(b"0x1::string::String"),
        string::utf8(b"bool")
    ];
    
    let mutate_config = token::create_token_mutability_config(
        &vector<bool>[false, true, true, true, true] // Only maximum immutable
    );
    
    token::create_tokendata(
        creator,
        string::utf8(b"Movement Pioneers"),
        string::utf8(b"Pioneer #") + to_string(pioneer_id),
        string::utf8(b"A unique Movement ecosystem pioneer NFT"),
        1, // NFT - maximum supply of 1
        string::utf8(b"https://movement.xyz/metadata/pioneer/") + to_string(pioneer_id),
        signer::address_of(creator),
        100, // 10% royalty (10/100)
        10,
        mutate_config,
        property_keys,
        property_values,
        property_types
    )
}
```

#### Mint Tokens

Minting creates actual token instances from previously defined token data. The amount parameter determines how many tokens to create (1 for NFTs, more for FTs/SFTs). Minted tokens are initially held by the creator and can then be transferred to recipients.

```move
public fun mint_token(
    account: &signer,
    token_data_id: TokenDataId,
    amount: u64,
): TokenId acquires Collections, TokenStore
```

**Example: Minting and Distributing NFTs**

```move
public fun mint_and_distribute_pioneer(
    creator: &signer,
    recipient: address,
    token_data_id: TokenDataId
) {
    // Mint the NFT
    let token_id = token::mint_token(creator, token_data_id, 1);
    
    // Transfer to recipient if they've opted in
    if (token::is_opt_in_direct_transfer(recipient)) {
        let token = token::withdraw_token(creator, token_id, 1);
        token::direct_deposit(recipient, token);
    }
}
```

#### Token Property Management

The legacy token standard supports mutable properties, allowing tokens to evolve over time. Property mutations create new property versions, enabling features like character leveling, equipment upgrades, or dynamic NFT attributes. Only properties marked as mutable during token data creation can be modified.

```move
public fun mutate_token_properties(
    account: &signer,
    token_owner: address,
    creator: address,
    collection_name: String,
    token_name: String,
    token_property_version: u64,
    amount: u64,
    keys: vector<String>,
    values: vector<vector<u8>>,
    types: vector<String>,
) acquires Collections, TokenStore
```

**Example: Upgrading Token Properties**

```move
public fun upgrade_pioneer_abilities(
    creator: &signer,
    token_owner: address,
    token_id: TokenId,
    new_special_ability: String,
    power_level: u64
) {
    let keys = vector<String>[
        string::utf8(b"special_ability"),
        string::utf8(b"power_level"),
        string::utf8(b"last_upgraded")
    ];
    
    let values = vector<vector<u8>>[
        bcs::to_bytes<String>(&new_special_ability),
        bcs::to_bytes<u64>(&power_level),
        bcs::to_bytes<u64>(×tamp::now_seconds())
    ];
    
    let types = vector<String>[
        string::utf8(b"0x1::string::String"),
        string::utf8(b"u64"),
        string::utf8(b"u64")
    ];
    
    token::mutate_token_properties(
        creator,
        token_owner,
        token_id.token_data_id.creator,
        token_id.token_data_id.collection,
        token_id.token_data_id.name,
        token_id.property_version,
        1,
        keys,
        values,
        types
    );
}
```

### For Token Users

#### Opt-in for Direct Transfer

Unlike the newer Digital Asset standard, the legacy token standard requires recipients to explicitly opt-in before they can receive direct token transfers. This provides security against unwanted token spam but adds friction to the transfer process.

```move
public entry fun opt_in_direct_transfer(account: &signer, opt_in: bool) acquires TokenStore
```

**Example:**

```move
public entry fun enable_token_transfers(user: &signer) {
    token::opt_in_direct_transfer(user, true);
}
```

#### Transfer Tokens

The `transfer_with_opt_in` function transfers tokens between accounts when the recipient has enabled direct transfers. The function requires specifying the full token identification (creator, collection, name, property version) to uniquely identify the token being transferred.

```move
public entry fun transfer_with_opt_in(
    from: &signer,
    creator: address,
    collection_name: String,
    token_name: String,
    token_property_version: u64,
    to: address,
    amount: u64,
) acquires TokenStore
```

**Example: Trading NFTs**

```move
public entry fun trade_pioneer_nft(
    seller: &signer,
    buyer_address: address,
    creator: address,
    pioneer_id: u64
) {
    let collection_name = string::utf8(b"Movement Pioneers");
    let token_name = string::utf8(b"Pioneer #") + to_string(pioneer_id);
    
    token::transfer_with_opt_in(
        seller,
        creator,
        collection_name,
        token_name,
        0, // Original property version
        buyer_address,
        1  // Transfer 1 NFT
    );
}
```

#### Burn Tokens

Burning permanently destroys tokens, removing them from circulation. Tokens can only be burned if the `TOKEN_BURNABLE_BY_CREATOR` or `TOKEN_BURNABLE_BY_OWNER` properties were set during token data creation. This is useful for redemption mechanics, upgrade systems, or cleaning up unwanted tokens.

```move
public entry fun burn(
    owner: &signer,
    creators_address: address,
    collection: String,
    name: String,
    property_version: u64,
    amount: u64
) acquires Collections, TokenStore
```

## Movement-Specific Features

### Enhanced Property System

The legacy token standard includes a flexible property system that stores arbitrary key-value pairs with type information. Properties can be set during token creation and optionally mutated later, enabling dynamic NFTs and evolving game assets.

```move
// Custom property types supported
struct PropertyMap has store, drop, copy {
    map: SimpleMap<String, PropertyValue>
}

// Flexible property values
struct PropertyValue has store, drop, copy {
    value: vector<u8>,
    type: String,
}
```

**Benefits:**

* **Type Safety**: Strongly typed property values with runtime validation
* **Extensibility**: Support for custom property types and complex data structures
* **Versioning**: Property mutations create new versions for NFT evolution
* **Gas Efficiency**: Optimized storage and access patterns

### Creator Economics

The legacy token standard includes a built-in royalty system that defines creator fees for secondary sales. Royalties are configured during token data creation and are expressed as a fraction (numerator/denominator) to support precise percentage calculations.

```move
struct Royalty has copy, drop, store {
    royalty_points_numerator: u64,
    royalty_points_denominator: u64,
    payee_address: address,
}
```

**Features:**

* **Flexible Rates**: Configurable royalty percentages
* **Multi-Recipient**: Support for shared royalty distribution
* **Marketplace Integration**: Standard interface for marketplace compliance
* **Immutable Options**: Lock royalty settings for creator guarantees

### Advanced Token Types

#### Semi-Fungible Tokens (SFTs)

Semi-fungible tokens combine properties of both fungible and non-fungible tokens. They can have multiple identical copies (like FTs) but also support unique per-instance properties (like NFTs). This is ideal for game items, event tickets, or any asset that needs both quantity and uniqueness.

```move
// Create SFT with limited supply
public fun create_game_item_sft(
    creator: &signer,
    item_name: String,
    max_supply: u64,
    base_stats: vector<u64>
): TokenDataId {
    // Implementation for game items that can have multiple copies
    // but maintain unique properties per instance
}
```

#### Dynamic NFTs

Dynamic NFTs leverage the property mutation system to create tokens that evolve based on external events, user actions, or time. Property mutations create new versions, preserving the history of changes while updating the token's current state.

```move
// NFT that can level up and gain new abilities
public fun level_up_character(
    owner: &signer,
    character_token_id: TokenId,
    new_level: u64,
    new_abilities: vector<String>
) {
    // Update character properties based on game progression
}
```

### Collection Management

#### Batch Operations

Batch operations enable efficient processing of multiple tokens in a single transaction, reducing gas costs and ensuring atomic execution. This is essential for large-scale minting events, airdrops, or collection-wide updates.

```move
public fun batch_mint_tokens(
    creator: &signer,
    token_data_ids: vector<TokenDataId>,
    amounts: vector<u64>,
    recipients: vector<address>
) {
    // Batch mint multiple tokens efficiently
}
```

#### Collection Analytics

Query functions provide insights into collection performance, including current supply, maximum capacity, and minting history. These are useful for building dashboards, enforcing supply limits, and monitoring collection growth.

```move
public fun get_collection_stats(
    creator: address,
    collection_name: String
): (u64, u64, u64) {
    // Returns (current_supply, maximum, total_minted)
}
```

## Query Functions

The legacy token standard provides a comprehensive query interface for retrieving token ownership, balances, metadata, and collection information. These functions are essential for building user interfaces, validating ownership, and integrating with marketplaces.

```move
// Token ownership and balance
public fun balance_of(owner: address, token_id: TokenId): u64
public fun get_token_amount(token: &Token): u64

// Token metadata
public fun get_token_id(token: &Token): &TokenId
public fun get_property_map(owner: address, token_id: TokenId): PropertyMap

// Collection information
public fun get_collection_supply(creator: address, collection_name: String): u64
public fun get_collection_maximum(creator: address, collection_name: String): u64

// Token data queries
public fun get_tokendata_maximum(token_data_id: TokenDataId): u64
public fun get_tokendata_supply(token_data_id: TokenDataId): u64
public fun get_tokendata_uri(creator: address, token_data_id: TokenDataId): String
```

## Events and Monitoring

The legacy token standard emits comprehensive events for tracking the complete token lifecycle. These events enable indexers, analytics platforms, and user interfaces to track token creation, transfers, burns, and property mutations in real-time.

```move
// Token lifecycle events
struct CreateTokenDataEvent has drop, store { /* ... */ }
struct MintTokenEvent has drop, store { /* ... */ }
struct BurnTokenEvent has drop, store { /* ... */ }

// Transfer events
struct DepositEvent has drop, store { /* ... */ }
struct WithdrawEvent has drop, store { /* ... */ }

// Property mutation events
struct MutateTokenPropertyMapEvent has drop, store { /* ... */ }
```

<Callout type="info">
  Move Industries provides migration tools and documentation for projects transitioning from legacy standards. The Token standard will continue to be supported for existing projects while new development is encouraged to use modern standards.
</Callout>

## Summary

* **Unified framework** supporting FTs, NFTs, and SFTs through hierarchical structures
* **Collection-based organization** with built-in royalty systems for creator economics
* **Mutable properties** with versioning support for dynamic NFTs and evolving assets
* **Opt-in transfers** requiring recipient approval for enhanced security
* **Flexible burning** when configured during token creation for redemption mechanics
* **Migration recommended** to [Digital Asset Standard](/devs/tokenStandard/currentStandard/digitalAsset) (NFTs) or [Fungible Asset Standard](/devs/tokenStandard/currentStandard/fungibleAsset) (FTs)

# Overview
URL: /general/l1/nodes

import React from 'react';

The Movement Mainnet consists of three main node types:

* **Validator Nodes**
* **Validator Fullnodes (VFNs)**
* **Public Fullnodes (PFNs)**

To participate in consensus, you are required to run a validator node and stake the minimum amount of MOVE tokens. VFNs and PFNs are not required to participate in consensus, but they are essential for distributing blockchain data and enabling ecosystem services such as indexing, querying, and RESTful API services.
VFNs can only be run by validator operators, while PFNs can be run by anyone. All node types are currently in development and will be available soon.

Thus, the Movement network uses a multi-tier architecture:

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Validator     │◄──►│   Validator     │◄──►│   Validator     │
│     Node        │    │     Node        │    │     Node        │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          ▼                      ▼                      ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Validator     │    │   Validator     │    │   Validator     │
│   Fullnode      │    │   Fullnode      │    │   Fullnode      │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────┬───────────┴───────────┬──────────┘
                     │                       │
            ┌─────────────────┐      ┌─────────────────┐  
            │    Public       │      │    Public       │   
            │   Fullnode      │      │   Fullnode      │   
            └─────────────────┘      └─────────────────┘ 
```

## Node Types Overview

### Validator Nodes

[View Validator Node Documentation →](/general/l1/nodes/validator-node)

* **Purpose**: Participate in consensus protocol and validate transactions
* **Requirements**: Must stake minimum MOVE tokens
* **Rewards**: Earn staking rewards for successful validation
* **Status**: 🚧 Coming Soon
* **Requirements**: See System Requirements (Coming Soon)

### Validator Fullnodes (VFNs)

[View VFN Documentation →](/general/l1/nodes/validator-fullnode)

* **Purpose**: Serve as secure entry/exit points for validator operations
* **Requirements**: Can only be operated by validator operators
* **Benefits**: Improved reliability and secure data access for validators
* **Status**: 🚧 Coming Soon
* **Requirements**: See System Requirements (Coming Soon)

### Public Fullnodes (PFNs)

[View PFN Documentation →](/general/l1/nodes/public-fullnode)

* **Purpose**: Replicate blockchain state and provide public access
* **Requirements**: No staking required, open to anyone
* **Benefits**: Increase network decentralization and data availability
* **Use Cases**: RPC services, indexing, dApps, and ecosystem tools
* **Status**: 🚧 Coming Soon
* **Requirements**: See System Requirements (Currently Supported)

## Validator Node Types Comparison

To participate in the Movement consensus protocol, you will need to deploy and run a **validator node**. Additionally, it will be **highly recommended** to run a **validator fullnode (VFN)** to provide secure and reliable access to blockchain data.

Comprehensive deployment guides will be available when validators launch on Movement.

### Node Types Comparison

| Feature           | Validator Node             | Validator Fullnode (VFN)     |
| ----------------- | -------------------------- | ---------------------------- |
| **Purpose**       | Consensus participation    | Data distribution & security |
| **Required**      | ✅ Yes (for consensus)      | 📋 Highly recommended        |
| **Staking**       | ✅ Required                 | ❌ No staking needed          |
| **Public Access** | ❌ Private network only     | ✅ Public API access          |
| **API Services**  | ❌ Disabled for security    | ✅ Full REST/WebSocket APIs   |
| **Hardware**      | High (consensus critical)  | Moderate (data serving)      |
| **Uptime**        | Critical (affects rewards) | Important (affects users)    |

### Architecture Overview

The recommended validator setup uses a two-tier architecture:

```
Internet ←→ VFN ←→ Validator Node
             ↑           ↑
      (Public APIs)  (Private Network)
      (Data Access)  (Consensus Only)
```

## Quick Links

### System Requirements

Essential information for planning and deploying Movement nodes.

* **Complete System Requirements** (Coming Soon) - Comprehensive hardware and software requirements for all node types
* **Cloud Provider Recommendations** (Coming Soon) - AWS, GCP, and Azure instance recommendations
* **Storage Requirements** (Coming Soon) - Storage types, capacity planning, and performance considerations
* **Network Requirements** (Coming Soon) - Bandwidth, latency, and port configuration

### Validation & Staking (Coming Soon)

Comprehensive guides for validation, staking, and governance will be available when Movement validators launch.

### Node Operations (Coming Soon)

Step-by-step deployment and operational guides will be available when nodes launch.

### Development Tools (Coming Soon)

Developer tools and local development environments will be available soon.

## Getting Started

All Movement node types are currently in development and will be available soon. Detailed deployment guides and operational procedures will be published when the nodes are ready for mainnet launch.

Stay tuned for updates on node availability and deployment instructions.

## Additional Resources

* For community resources, support channels, and ways to get involved, see [Community and Support](/general/usingmovement/community-support).

# Public Fullnode (PFN)
URL: /general/l1/nodes/public-fullnode

Public fullnodes (PFNs) will allow you to synchronize the state of the Movement blockchain and stay up-to-date. PFNs will replicate the entire state of the blockchain by syncing from VFNs and other PFNs. PFNs will be available for anyone to run and will serve as crucial infrastructure for the Movement ecosystem.

PFNs will enable various use cases including:

* **RPC Services**: Provide JSON-RPC endpoints for dApps and wallets
* **Indexing**: Index blockchain data for analytics and APIs
* **Development**: Local testing and development environments
* **Backup**: Maintain redundant copies of blockchain state
* **Analytics**: Historical data analysis and research

## Network Connection

**Default connection to mainnet**: If you follow the default setup in this document, then your PFN will be connected to the Movement mainnet. To connect to a different Movement network, such as testnet, make sure you have the correct configuration files and genesis data.

You can find the genesis and waypoint files for all Movement networks in the **[Movement Networks repository](https://github.com/movement-network/movement-networks)**.

## Overview

When PFNs become available, running a PFN will involve:

1. **Requirements Check** - Ensure your system meets hardware and software specifications
2. **Deployment Method Selection** - Choose Docker, source build, or cloud deployment
3. **Node Configuration** - Set up configuration files and network parameters
4. **Deploy and Sync** - Start the node and sync with the network
5. **Service Configuration** - Set up optional services like APIs and indexing

Detailed deployment guides will be published when PFNs are ready for launch.

## PFN Types and Use Cases

#### Standard PFN

* **Purpose**: Basic blockchain synchronization and data access
* **Resources**: Moderate hardware requirements
* **Services**: Basic RPC endpoints

#### API PFN

* **Purpose**: High-performance API services for dApps
* **Resources**: Higher compute and memory for request handling
* **Services**: Full REST API, WebSocket, custom endpoints

#### Indexer PFN

* **Purpose**: Specialized indexing and analytics
* **Resources**: High storage and compute for data processing
* **Services**: Custom indexing, analytics APIs, database integration

#### Archive PFN

* **Purpose**: Long-term historical data preservation
* **Resources**: Very high storage requirements
* **Services**: Complete historical access, research APIs

## System Requirements

Detailed requirements will be provided when PFNs launch.

## Deployment Guides

When PFNs become available, comprehensive guides will be provided for various deployment methods.

# Validator Fullnode (VFN)
URL: /general/l1/nodes/validator-fullnode

Running a validator fullnode is not supported on the Movement Network at this time.

## System Requirements

When validator fullnodes become available, they will serve as secure data access layers for validators. For detailed specifications and planning information, see System Requirements (Coming Soon).

## What VFNs Will Provide

When available, validator fullnodes will offer:

* **Security Layer**: Acts as a buffer between validators and public networks
* **API Services**: Provides REST API and WebSocket endpoints
* **Load Balancing**: Reduces load on validator nodes
* **Data Distribution**: Serves blockchain data to ecosystem applications

# Validator Node (VN)
URL: /general/l1/nodes/validator-node

Running a validator node is not supported on the Movement Network at this time.

## System Requirements

When validator nodes become available, they will have specific hardware and software requirements. For detailed specifications and planning information, see System Requirements (Coming Soon).

## Get Notified

To be notified when validator functionality becomes available:

* **[Follow on Discord](https://discord.com/invite/moveindustries)** - Join the community
* **[Monitor GitHub](https://github.com/movement-network/movement)** - Track development progress

# Overview
URL: /general/nodes/archival-node

An **archival fullnode** maintains complete blockchain history from genesis by disabling ledger pruning. Unlike standard public fullnodes (PFNs) that sync from a recent state and prune old data, archival nodes preserve the full transaction history.

## When to Use an Archival Node

An archival node is required if you need to:

* Query historical blockchain state from any point in time
* Access complete transaction history from genesis
* Run indexers that require full historical data
* Provide historical data services to other applications

<Callout type="info">
  **Standard vs Archival Nodes**

| Feature                  | Standard PFN | Archival Node         |
  | ------------------------ | ------------ | --------------------- |
  | Recent state queries     | Yes          | Yes                   |
  | Historical state queries | Limited      | Full history          |
  | Storage requirements     | \~50-100GB   | 700GB+ (mainnet)      |
  | Initial sync time        | Faster       | Requires data restore |
  | Ledger pruning           | Enabled      | Disabled              |
</Callout>

## Key Configuration Difference

The only configuration difference between a standard PFN and an archival node is the `storage_pruner_config` setting:

```yaml
storage:
  storage_pruner_config:
    ledger_pruner_config:
      enable: false  # Disable pruning for archival nodes
```

This setting prevents the node from pruning old ledger data, ensuring complete history is maintained.

## Bootstrapping with Existing Data

Because archival nodes maintain complete history, syncing from genesis would take an extremely long time. Move Industries provides public backups that you can use to bootstrap your archival node with existing data.

The backups are:

* Updated hourly
* Maintained for 14 days of snapshots
* Available for both mainnet and testnet

See the [deployment guides](/general/nodes/archival-node/run/deploy) for instructions on restoring from backups.

## Hardware Requirements

| Resource | Minimum  | Recommended   |
| -------- | -------- | ------------- |
| Storage  | 1TB SSD  | 2TB+ NVMe SSD |
| Memory   | 16GB RAM | 32GB RAM      |
| CPU      | 8 cores  | 16 cores      |
| Network  | 100 Mbps | 1 Gbps        |

<Callout type="warning">
  **Storage Growth**

Archival nodes continuously grow as they store all blockchain data. Plan for storage expansion over time. As of January 2026:

* Mainnet: \~700GB
  * Testnet: \~260GB
</Callout>

## Next Steps

* [Run an Archival Node](/general/nodes/archival-node/run) - Overview of running archival nodes
* [Deploy with Docker](/general/nodes/archival-node/run/deploy/docker) - Deploy using Docker containers
* [Deploy from Source](/general/nodes/archival-node/run/deploy/source) - Build and deploy from source code

# Overview
URL: /general/nodes/full-node

You can run your own public fullnode (PFN) to synchronize the state of the Movement blockchain and stay
up-to-date. PFNs replicate the entire state of the blockchain by syncing from other Movement VFNs and PFNs. PFNs
can be run by anyone. This section explains how to deploy a PFN and connect to a Movement network. You can learn
more about the different types of nodes in the [M1](/general/l1/nodes) section.

**Default connection to testnet**
If you follow the default setup in this document, then your PFN will be connected to the Movement testnet. To connect
to a different Movement network, such as testnet or mainnet, make sure you have the correct docker image tag, or source
code branch if you build the binary directly.

You can find the genesis and waypoint files for all the networks, here ➜ [https://github.com/movement-network/movement-networks](https://github.com/movement-network/movement-networks).

# Wallet Connection
URL: /devs/interactonchain/wallet-adapter/useWallet/ConnectWallet

<Callout>
  Want to skip this and go straight to the code? [Click here](https://github.com/Rahat-ch/Movement-Network-ConnectWallet-Template)
</Callout>

## Building a Movement Network Wallet Connection Template

This tutorial will guide you through building a wallet connection interface for Movement Network using Next.js, TypeScript, and the Aptos Wallet Adapter.

## Prerequisites

* Node.js 18+ and npm/yarn installed
* Basic knowledge of React and TypeScript
* A Movement-compatible wallet (we recommend [Nightly](https://nightly.app/))

## Project Setup

### 1. Create a Next.js Application with shadcn/ui

This template was built using the shadcn init command, which automatically creates a Next.js application with TypeScript, Tailwind CSS, and the shadcn/ui component system pre-configured:

```bash
npx shadcn@latest init
```

Follow the Prompts for a Next JS application.

### 2. Install Required UI Components

After initializing the project, install the specific shadcn/ui components used in this template:

```bash
npx shadcn@latest add button card dialog input sonner
```

### 3. Install Core Dependencies

Install the Movement SDK and wallet adapter packages:

```bash
npm install @moveindustries/ts-sdk @aptos-labs/wallet-adapter-react
```

### 4. Install Wallet Standard and Peer Dependencies

**Important**: You'll need to install peer dependencies with the legacy peer deps flag to avoid version conflicts:

```bash
npm install @aptos-labs/wallet-standard --legacy-peer-deps
npm install @telegram-apps/bridge uuid aptos got --legacy-peer-deps
```

## Core Implementation

### 1. Wallet Provider Setup

Create a wallet provider component at `components/wallet-provider.tsx`:

```typescript
"use client";

import { ReactNode } from "react";
import { AptosWalletAdapterProvider } from "@aptos-labs/wallet-adapter-react";
import { MovementConfig, Network } from "@moveindustries/ts-sdk";

interface WalletProviderProps {
  children: ReactNode;
}

export function WalletProvider({ children }: WalletProviderProps) {
  // Movement Mainnet configuration
  const movementConfig = new MovementConfig({
    network: Network.MAINNET,
    fullnode: "https://mainnet.movementnetwork.xyz/v1",
  });
  
  return (
    <AptosWalletAdapterProvider
      autoConnect={true}
      dappConfig={movementConfig}
      onError={(error) => {
        console.error("Wallet error:", JSON.stringify(error, null, 2));
      }}
    >
      {children}
    </AptosWalletAdapterProvider>
  );
}
```

### 2. Root Layout Configuration

Update your `app/layout.tsx` to include the wallet provider:

```typescript
import { WalletProvider } from "@/components/wallet-provider";
import { Toaster } from "@/components/ui/sonner";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <WalletProvider>
          {children}
          <Toaster />
        </WalletProvider>
      </body>
    </html>
  );
}
```

### 3. Wallet Selection Modal with Movement Network Connection

There is some filtered logic for the wallets here in order to remove wallets that are not fully compatible with Movement Network.

Create `components/wallet-selection-modal.tsx`:

```typescript
"use client";

import { useState } from "react";
import { useWallet } from "@aptos-labs/wallet-adapter-react";
import { getAptosWallets } from "@aptos-labs/wallet-standard";
// ... UI imports

export function WalletSelectionModal({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
  const { wallets, connect } = useWallet();

// Filter and prioritize wallets
  const filteredWallets = wallets
    .filter((wallet) => {
      const name = wallet.name.toLowerCase();
      // Filter out incompatible wallets
      return !name.includes("petra") && 
             !name.includes("google") && 
             !name.includes("apple");
    })
    .filter((wallet, index, self) => {
      // Remove duplicates
      return index === self.findIndex((w) => w.name === wallet.name);
    })
    .sort((a, b) => {
      // Nightly wallet first (best Movement support)
      if (a.name.toLowerCase().includes("nightly")) return -1;
      if (b.name.toLowerCase().includes("nightly")) return 1;
      return 0;
    });

// Render modal with wallet options...
}
```

### 4. Network Switching Component

Since Aptos wallet adapter doesn't support using the built in switch component for custom networks like Movement, we need a special approach. This code is compatible with Nightly Wallet, you will need to determine if other wallets are able to use the switch network functionality. Otherwise the fallback will be to ask the user to manually switch the network in their wallet.

Create `components/switch-network.tsx`:

```typescript
export function SwitchNetwork() {
  const { network, wallet } = useWallet();
  
  // Detect current network by chain ID
  const isMovementMainnet = network?.chainId === 126;
  const isMovementTestnet = network?.chainId === 250;
  const isNightly = wallet?.name?.toLowerCase().includes("nightly");

// Render network status and switch buttons...
}
```

## Key Features Implementation

### 1. Send Transaction

The send transaction component (`components/send-transaction.tsx`) handles Movement network configurations:

```typescript
const MOVEMENT_CONFIGS = {
  mainnet: {
    chainId: 126,
    fullnode: "https://mainnet.movementnetwork.xyz/v1",
  },
  testnet: {
    chainId: 250,
    fullnode: "https://testnet.movementnetwork.xyz/v1",
  }
};

// Dynamically use the correct network based on chain ID
const getCurrentNetworkConfig = () => {
  if (network?.chainId === 126) return MOVEMENT_CONFIGS.mainnet;
  if (network?.chainId === 250) return MOVEMENT_CONFIGS.testnet;
  return MOVEMENT_CONFIGS.testnet; // Default
};
```

### 2. Sign Message

The sign message component (`components/sign-message.tsx`) handles signature formatting:

```typescript
// Handle different signature formats from wallets
if (response.signature?.data?.data) {
  // Convert byte array to hex string
  const byteArray = Object.values(response.signature.data.data) as number[];
  signature = '0x' + byteArray.map(byte => byte.toString(16).padStart(2, '0')).join('');
}
```

## Movement Network Configuration

### Chain IDs

* **Mainnet**: 126
* **Testnet**: 250 (Bardock)

### RPC Endpoints

* **Mainnet**: `https://mainnet.movementnetwork.xyz/v1`
* **Testnet**: `https://testnet.movementnetwork.xyz/v1`

### Explorer

* **Format**: `https://explorer.movementnetwork.xyz/txn/{txHash}?network={mainnet|testnet}`

## Important Considerations

### 1. Wallet Compatibility

Not all Aptos wallets support Movement Network properly. We recommend:

* **Nightly Wallet** (Full support including network switching)
* Other wallets may work but without network switching

### 2. Network Connection on Wallet Selection

**Critical**: When users click "Connect Wallet", the implementation attempts to connect directly to Movement Network (not Aptos mainnet). This is achieved through the wallet-standard `aptos:connect` feature with network info.

### 3. Network Switching Limitations

* Standard Aptos wallet adapter doesn't support Movement network switching
* Only Nightly wallet currently supports programmatic network switching
* Other wallets require manual network configuration

### 4. Error Handling

The template includes proper error handling for:

* Network mismatches
* Failed transactions
* Wallet connection issues
* Signature formatting differences

## Project Structure

```
movement-wallet-app/
├── app/
│   ├── layout.tsx         # Root layout with providers
│   └── page.tsx           # Main page with wallet UI
├── components/
│   ├── wallet-provider.tsx        # Wallet adapter setup
│   ├── wallet-selection-modal.tsx # Connection with Movement network
│   ├── wallet-demo-content.tsx    # Connected wallet UI
│   ├── switch-network.tsx         # Network switching (Nightly only)
│   ├── send-transaction.tsx       # Send MOVE tokens
│   ├── sign-message.tsx           # Message signing
│   └── ui/                        # shadcn/ui components
└── lib/
    └── utils.ts           # Utility functions
```

## Testing Your Implementation

1. **Install Nightly Wallet** from [nightly.app](https://nightly.app/)
2. **Run your development server**: `npm run dev`
3. **Connect Wallet**: Click connect and select Nightly
4. **Verify Network**: Check that you're connected to Movement Network (Chain ID 126 or 250)
5. **Test Features**:
   * Switch between Movement mainnet and testnet
   * Send a test transaction (ensure you have MOVE tokens)
   * Sign a message

## Troubleshooting Errors

### Peer Dependency Issues

Always use `--legacy-peer-deps` when installing wallet-related packages:

```bash
npm install [package] --legacy-peer-deps
```

### Wallet Not Connecting to Movement

Ensure the wallet selection modal is using the correct network info:

* Chain ID: 126 (mainnet) or 250 (testnet)
* Network name: "custom"

### Network Switching Not Working

Only Nightly wallet supports Movement network switching. Other wallets need manual configuration.

### Transaction Failures

Verify:

* Correct network configuration in send-transaction component
* Wallet is on Movement Network
* Sufficient MOVE balance

# Sign & Submit
URL: /devs/interactonchain/wallet-adapter/useWallet/signAndSubmitTx

## Overview

This React component implements a transaction signing and submission functionality for the Aptos blockchain. It provides a simple button interface that allows users to sign and submit transactions using their connected Aptos wallet.

## Dependencies

```typescript
import React from 'react';
import { useWallet } from '@aptos-labs/wallet-adapter-react';
import { Movement, MovementConfig, Network } from '@moveindustries/ts-sdk';
```

* `@aptos-labs/wallet-adapter-react`: Provides wallet connection functionality
* `@moveindustries/ts-sdk`: Movement blockchain SDK for interaction with the network

## Configuration

```typescript
const config = new MovementConfig({
  network: Network.TESTNET,
  fullnode: 'https://testnet.movementnetwork.xyz/v1',
  faucet: 'https://faucet.testnet.movementnetwork.xyz/'
})
const movement = new Movement(config);
```

* Creates a new Movement configuration instance
* Connects to the Movement testnet network
* Initializes the Movement client with the configuration

## Component Breakdown

### 1️⃣ Hook Usage

```typescript
const { account, signAndSubmitTransaction } = useWallet();
```

* Uses the `useWallet` hook to get:
  * `account`: Current connected wallet account
  * `signAndSubmitTransaction`: Function to sign and submit transactions

### 2️⃣ Transaction Handler

```typescript
const onSignAndSubmitTransaction = async () => {
```

This function handles:

1. Account verification
2. Transaction creation and submission
3. Transaction confirmation

#### Transaction Structure

```typescript
{
  sender: account.address,
  data: {
    function: "<address_account>::<module_name>::<function>",
    functionArguments: [account.address, 1],
  }
}
```

* `sender`: The address of the transaction sender
* `function`: Calls the Aptos account transfer function
* `functionArguments`: Array containing:
  * Recipient address (in this case, sending to self)
  * Amount to transfer (1 unit)

### 3️⃣ Transaction Confirmation

```typescript
await movement.waitForTransaction({ transactionHash: response.hash });
```

* Waits for transaction confirmation on the blockchain
* Includes error handling for failed transactions

### 4️⃣ UI Component

```typescript
return (
  <button onClick={onSignAndSubmitTransaction}>
    Sign and submit transaction
  </button>
);
```

* Renders a simple button
* Triggers the transaction process when clicked

## Usage Example

```typescript
import SignAndSubmit from './components/signAndSubmitTx';

function App() {
  return (
    <div>
      <SignAndSubmit />
    </div>
  );
}
```

## Important Notes

1. This component requires a connected wallet to function
2. It's configured to work with Mainnet (production network)
3. The current implementation sends 1 unit to the same address (self-transfer)
4. Error handling is implemented for transaction confirmation
5. The component should be used within a wallet provider context

## Fullcode

```typescript title="src/components/signAndSubmitTx.tsx"
import React from 'react';
import { useWallet } from '@aptos-labs/wallet-adapter-react';
import { Movement, MovementConfig, Network } from '@moveindustries/ts-sdk';

const config = new MovementConfig({ network: Network.MAINNET });
const movement = new Movement(config);

const SignAndSubmit = () => {
  const { account, signAndSubmitTransaction } = useWallet();

return (
    <button onClick={onSignAndSubmitTransaction}>
      Sign and submit transaction
    </button>
  );
};

export default SignAndSubmit;
```

# Sign and Verify Message
URL: /devs/interactonchain/wallet-adapter/useWallet/signMessage

## Overview

This React component creates a user interface for signing and verifying messages using an Movement wallet. It's commonly used in blockchain applications to prove ownership of a wallet address by signing messages.

## Key Features

1. Message signing
2. Message verification
3. Wallet connection status
4. Error handling

## How It Works

### 1️⃣ Component Setup

```typescript
const { signMessage, signMessageAndVerify, connected, account } = useWallet();
```

* Uses the Aptos wallet adapter to get necessary functions and wallet status
* `connected`: Tells if wallet is connected
* `account`: Contains wallet information

### 2️⃣ State Management

```typescript
const [message, setMessage] = useState<string>('');
const [nonce, setNonce] = useState<string>('');
const [signedMessage, setSignedMessage] = useState<any>(null);
const [verificationResult, setVerificationResult] = useState<boolean | null>(null);
const [error, setError] = useState<string | null>(null);
```

Manages five different states:

* `message`: The text message to be signed
* `nonce`: A random string to prevent replay attacks
* `signedMessage`: Stores the signed message response
* `verificationResult`: Stores whether the message verification was successful
* `error`: Stores any error messages

### 3️⃣ Message Signing Function

```typescript
const handleSignMessage = async () => {
    setError(null);
    try {
      const response = await signMessage({ message, nonce });
      setSignedMessage(response);
    } catch (err: any) {
      setError(`Failed to sign message: ${err.message}`);
    }
};
```

* Clears any previous errors
* Attempts to sign the message using the wallet
* Stores the signed message or captures any errors

### 4️⃣ Message Verification Function

```typescript
const handleVerifyMessage = async () => {
    setError(null);
    try {
      const result = await signMessageAndVerify({ message, nonce });
      setVerificationResult(result);
    } catch (err: any) {
      setError(`Failed to verify message: ${err.message}`);
    }
};
```

* Clears any previous errors
* Verifies the signed message
* Stores the verification result or captures any errors

### 5️⃣ User Interface

The component renders different UI elements based on wallet connection status:

If wallet is not connected:

* Shows a message asking user to connect wallet

If wallet is connected:

1. Shows the connected wallet address
2. Provides a text area for entering the message
3. Provides an input field for the nonce
4. Shows a "Sign Message" button
5. If message is signed:
   * Displays the signed message
   * Shows a "Verify Message" button
6. Shows verification result if available
7. Displays any errors that occur

## Use Cases

1. **Identity Verification**: Prove ownership of a wallet address
2. **Authentication**: Can be used as part of a login system
3. **Message Authentication**: Ensure messages are authentic and haven't been tampered with

## Error Handling

* Handles signing errors
* Handles verification errors
* Displays user-friendly error messages

This component provides a complete solution for signing and verifying messages using an Aptos wallet, with a user-friendly interface and proper error handling.

## Code Example

```typescript title="signAndVerify"
import React, { useState } from 'react';
import { useWallet } from '@aptos-labs/wallet-adapter-react';

const SignMessageDemo = () => {
  const { signMessage, signMessageAndVerify, connected, account } = useWallet();
  const [message, setMessage] = useState<string>('');
  const [nonce, setNonce] = useState<string>('');
  const [signedMessage, setSignedMessage] = useState<any>(null);
  const [verificationResult, setVerificationResult] = useState<boolean | null>(null);
  const [error, setError] = useState<string | null>(null);

return (
    <div>
      <h1>Aptos Sign and Verify Message</h1>
      <div>
        {connected ? (
          <div>
            <p>Connected to: {account?.address}</p>
            <div className="flex flex-col gap-4">
              <textarea
                value={message}
                onChange={(e) => setMessage(e.target.value)}
                placeholder="Enter your message here"
                className="border rounded p-2"
              />
              <input
                type="text"
                value={nonce}
                onChange={(e) => setNonce(e.target.value)}
                placeholder="Enter nonce (random string) here"
                className="border rounded p-2 mt-2"
              />
              <button onClick={handleSignMessage} className="bg-blue-500 text-white rounded p-2 mt-2">
                Sign Message
              </button>
              {signedMessage && (
                <div>
                  <h4>Signed Message</h4>
                  <pre>{JSON.stringify(signedMessage, null, 2)}</pre>
                  <button onClick={handleVerifyMessage} className="bg-green-500 text-white rounded p-2 mt-2">
                    Verify Message
                  </button>
                </div>
              )}
              {verificationResult !== null && (
                <div>
                  <h4>Verification Result</h4>
                  <p>{verificationResult ? 'Message is verified!' : 'Failed to verify message.'}</p>
                </div>
              )}
              {error && (
                <div className="text-red-600">
                  <p>{error}</p>
                </div>
              )}
            </div>
          </div>
        ) : (
          <p>Please connect your wallet to sign and verify messages.</p>
        )}
      </div>
    </div>
  );
};

export default SignMessageDemo;
```

## Sign & Submit BCS Transaction

How to sign and submit a BCS (Binary Canonical Serialization) transaction on the MoveVM blockchain. It specifically shows how to transfer tokens using the Move account module.

## Function Breakdown

### Transaction Submission Function

```typescript
const onSignAndSubmitBCSTransaction = async () => {
    const response = await signAndSubmitTransaction({
        sender: account.address,
        data: {
            function: "0x1::aptos_account::transfer",
            functionArguments: [AccountAddress.from(account.address), new U64(1)],
        },
    });
    // ... transaction confirmation ...
};
```

#### Key Components:

1. **Sender**: The address of the account initiating the transaction
2. **Function Path**: `0x1::aptos_account::transfer`
   * `0x1`: Core framework address
   * `aptos_account`: Module name
   * `transfer`: Function name
3. **Function Arguments**:
   * `AccountAddress.from(account.address)`: Recipient address
   * `new U64(1)`: Amount to transfer (1 unit)

### Transaction Confirmation

```typescript
try {
    await aptos.waitForTransaction({ transactionHash: response.hash });
} catch (error) {
    console.error(error);
}
```

* Waits for transaction confirmation
* Handles any errors during confirmation process

### UI Element

```typescript
<button onClick={onSignAndSubmitTransaction}>
    Sign and submit BCS transaction
</button>
```

* Simple button to trigger the transaction

## Important Notes

1. **BCS Format**: Uses Binary Canonical Serialization for efficient transaction encoding
2. **Error Handling**: Includes basic error handling for transaction confirmation
3. **Amount**: Example shows transfer of 1 unit (adjust as needed)
4. **Gas Fees**: Transaction will require gas fees (not shown in example)

## Common Use Cases

1. Token transfers
2. Smart contract interactions
3. Blockchain state modifications

# Requirements
URL: /general/nodes/archival-node/run

To ensure that your archival fullnode operates smoothly, it should meet the requirements specified in this document.

## Hardware requirements

<Callout type="warning">
  **Minimum hardware requirements**

Failing to meet the minimum hardware requirements means that your archival node will experience degradation under load and general instability in production environments. Archival nodes have higher requirements than standard PFNs due to the complete blockchain history they maintain.
</Callout>

For running a production-grade archival node, we recommend:

| Resource | Minimum      | Recommended   |
| -------- | ------------ | ------------- |
| Storage  | 1TB NVMe SSD | 2TB+ NVMe SSD |
| Memory   | 16GB RAM     | 32GB RAM      |
| CPU      | 8 cores      | 16 cores      |
| Network  | 100 Mbps     | 1 Gbps        |

<Callout type="info">
  **Storage growth**

Archival nodes store the complete blockchain history and will continue to grow over time. As of January 2026:

* Mainnet: \~700GB
  * Testnet: \~260GB

Plan for storage expansion as the blockchain grows.
</Callout>

## Network requirements and ports

When running an archival node, you need to open network ports to allow other nodes (peers) to connect. The public network is used for PFNs to connect to other PFNs and VFNs.

### Port settings

The recommendations below assume default port settings. If you have changed the default port settings in your configuration file, adjust accordingly.

<Callout type="warning">
  **Exposing ports**

Unless explicitly required, we recommend that you do not expose any other ports while operating an archival node. Exposing additional ports can increase the attack surface of your node.
</Callout>

#### Running an archival node:

Assuming default ports are used, configure the following:

* Open the following TCP ports:
  * `6182` – **Public network**: Open this port publicly to enable other PFNs to connect to your node.
* Close the following TCP ports:
  * `9101` – **Inspection service**: Close this port to prevent unauthorized metric inspection.
  * `9102` – **Admin service**: Close this port to prevent unauthorized admin service interaction.
  * `80/8080` - **REST API**: Close this port to prevent unauthorized REST API access.

<Callout type="warning">
  **Exposing services**

The inspection service port (`9101`), admin service port (`9102`) and the REST API port (`80` or `8080`) are useful for your internal network (e.g., application development and debugging). However, the inspection service port and the admin service port should never be exposed publicly. If you expose the REST API endpoint publicly, deploy additional authentication or rate-limiting to prevent abuse.
</Callout>

## Storage requirements

Archival nodes store the entire history of the blockchain, so the database size will continue to grow unbounded. Unlike standard PFNs that prune old data, archival nodes maintain complete ledger history from genesis.

Current storage estimates:

* **Mainnet**: \~700GB (and growing)
* **Testnet**: \~260GB (and growing)

We recommend using NVMe SSDs for optimal performance due to the high I/O requirements of archival nodes.

## Software requirements

You will need one of the following:

* **Docker** (recommended for most users)
* **Rust toolchain** (for building from source)

Additionally, to bootstrap your archival node from Move Industries' public backups, you will need:

* **restic** backup tool ([installation instructions](https://restic.net/))

## Bootstrapping from backups

Move Industries provides public backups of archival node data that are updated hourly. This is the fastest way to bootstrap an archival node rather than syncing from genesis.

Download and use the restore script from the Movement Networks repository:

```shellscript filename="Terminal"
# Download the restore script
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/l1_restore.sh
chmod +x l1_restore.sh

# Restore mainnet data
./l1_restore.sh mainnet ./data

# Or restore testnet data
./l1_restore.sh testnet ./data
```

The script handles all the restic configuration for anonymous access to the public S3 backup buckets.

<Callout type="info">
  **Backup schedule**

* **Frequency**: Hourly snapshots
  * **Retention**: 14 days of snapshots
  * **Format**: restic backup repositories
</Callout>

# Verify an Archival Node
URL: /general/nodes/archival-node/run/verify

After deploying your archival node, verify that it's running correctly and can access historical data.

## Basic Health Check

Check that the node is responding and syncing:

```shellscript filename="Terminal"
# Check node health
curl http://localhost:8080/v1

# Expected output includes:
# - chain_id
# - epoch
# - ledger_version
# - oldest_ledger_version
# - ledger_timestamp_usec
# - node_role
# - oldest_block_height
# - block_height
# - git_hash
```

## Verify Sync Status

Check the current ledger version and compare it to the network:

```shellscript filename="Terminal"
# Get your node's ledger version
curl -s http://localhost:8080/v1 | jq '.ledger_version'

# Compare with public endpoint
# For mainnet:
curl -s https://mainnet.movementnetwork.xyz/v1 | jq '.ledger_version'

# For testnet:
curl -s https://testnet.movementnetwork.xyz/v1 | jq '.ledger_version'
```

Your node's ledger version should be close to (or equal to) the public endpoint's version.

## Verify Historical Data Access

The key difference between an archival node and a standard PFN is the ability to query historical data. Verify this by querying early transactions:

```shellscript filename="Terminal"
# Query transaction at version 1 (genesis)
curl http://localhost:8080/v1/transactions/by_version/1

# Query an early block
curl http://localhost:8080/v1/blocks/by_height/1

# Query transactions from an early block
curl http://localhost:8080/v1/transactions?start=1&limit=10
```

<Callout type="info">
  **Archival Verification**

If these historical queries return data successfully, your archival node is correctly maintaining full history. A standard PFN would return errors for very old data that has been pruned.
</Callout>

## Check Oldest Ledger Version

Verify that your node has data from the beginning:

```shellscript filename="Terminal"
curl -s http://localhost:8080/v1 | jq '.oldest_ledger_version'
```

For an archival node, `oldest_ledger_version` should be `"0"` or a very low number, indicating data from genesis is available.

## Verify Pruning is Disabled

Check the node logs to confirm pruning is disabled:

```shellscript filename="Terminal"
# For Docker
docker logs aptos-archival-node 2>&1 | grep -i "pruner"

# Look for messages indicating pruning is disabled
```

## Monitor Node Metrics

The node exposes Prometheus metrics on port 9101:

```shellscript filename="Terminal"
# Check metrics endpoint
curl http://localhost:9101/metrics

# Key metrics to monitor:
# - aptos_state_sync_version (current synced version)
# - aptos_storage_ledger_version (ledger version in storage)
# - aptos_storage_oldest_ledger_version (oldest available version)
```

## Common Issues

### Node is behind the network

If your node's ledger version is significantly behind:

1. Check network connectivity to upstream peers
2. Verify port 6182 is open for outbound connections
3. Check available disk space
4. Review logs for errors

### Historical queries fail

If queries for old data fail:

1. Verify `storage_pruner_config.ledger_pruner_config.enable` is `false` in your config
2. Ensure you restored from a complete archival backup
3. Check that the restore completed successfully

### High disk usage

Archival nodes require significant storage:

1. Monitor disk usage trends
2. Plan for storage expansion
3. Consider using NVMe SSDs for better performance

## Troubleshooting

### Check logs

```shellscript filename="Terminal"
# Docker
docker logs aptos-archival-node --tail 100

# Source build
# Logs are typically written to stdout/stderr
```

### Restart the node

```shellscript filename="Terminal"
# Docker
docker restart aptos-archival-node

# Source build
# Stop and restart the process
```

### Verify configuration

Ensure your `archival-fullnode.yaml` has the correct settings:

```yaml
storage:
  storage_pruner_config:
    ledger_pruner_config:
      enable: false  # Must be false for archival
```

# Requirements
URL: /general/nodes/full-node/run

To ensure that your public fullnode (PFN) operates smoothly, it should meet the requirements specified in this document.

## Hardware requirements

<Callout type="warning">
  **Minimum hardware requirements**<br />
  Failing to meet the minimum hardware requirements mean that your PFN will experience degradation under
  load and general instability in production environments. It is not recommended to run a PFN without
  meeting the minimum hardware requirements.
</Callout>

For running a production-grade PFN, we recommend that your hardware meet the same requirements as a
validator or VFN. You can see the hardware requirements for these, here: [validator and VFN hardware requirements](/network/nodes/validator-node/node-requirements#hardware-requirements).

<Callout type="info">
  **Testing PFNs**<br />
  If you wish to run a PFN for development or testing only, lower hardware specs can be used.
  But, it should not be used in production.
</Callout>

## Network requirements and ports

When you are running a PFN, you are required to open network ports on your nodes to allow other nodes (i.e., peers)
to connect to you. There are different Movement network types, and each network type uses a different port. However,
the only network type that a PFN uses is the public network, where PFNs to connect to other PFNs and VFNs.

Your PFN can be configured so that the public network operates using a specific port on your node. You can configure
the port settings using the node configuration YAML file. Here is an [example
configuration file](https://github.com/movement-network/aptos-core/blob/movement/config/src/config/test_data/public_full_node.yaml#L16) for a PFN
that configures the public network to use port `6180`.

### Port settings

The recommendations described below assume the default port settings used by PFNs. If you have
changed the default port settings in your configuration file, then you should adjust the recommendations accordingly.

<Callout type="warning">
  **Exposing ports**<br />
  Unless explicitly required, we recommend that you do not expose any other ports while operating a PFN. This is because
  exposing additional ports can increase the attack surface of your node and make it more vulnerable to adversaries.
</Callout>

#### Running a PFN:

Assuming default ports are used, the following should be configured for PFNs:

* Open the following TCP ports:
  * `6182` – **Public network**: Open this port publicly to enable other PFNs to connect to your PFN.
* Close the following TCP ports:
  * `9101` – **Inspection service**: Close this port to prevent unauthorized metric inspection.
  * `9102` – **Admin service**: Close this port to prevent unauthorized admin service interaction.
  * `80/8080` - **REST API**: Close this port to prevent unauthorized REST API access.

<Callout type="warning">
  **Exposing services**<br />
  The inspection service port (`9101`), admin service port (`9102`) and the REST API port (`80` or `8080`)
  are likely useful for your internal network, e.g., application development and debugging. However, the inspection service
  port and the admin service port should never be exposed publicly as they can be easily abused. Similarly, if you choose
  to expose the REST API endpoint publicly, you should deploy an additional authentication or rate-limiting mechanism to
  prevent abuse.
</Callout>

## Storage requirements

The amount of data stored by Movement PFNs depends on the ledger history (length) of the blockchain and the number of
on-chain states (e.g., accounts and resources). Both the ledger history and the number of
on-chain states depend on several additional factors, including the age of the blockchain, the average transaction
rate over time, and the configuration of the ledger database pruner. At the time of writing, we estimate
that testnet and mainnet PFNs require several 100's of GB of storage.

Note that because archival nodes store the entire history of the blockchain, the database size on archival nodes
will continue to grow unbounded. As a result, we cannot provide a recommendation for archival node storage sizes.

# Verify a PFN
URL: /general/nodes/full-node/run/verify

After deploying your PFN, you can verify that it is operating correctly by checking several of the PFN's metrics.
This document describes the common types of checks that you might wish to perform.

<Callout type="info">
  You can learn more about Aptos metrics in the [Node Inspection Service](/network/nodes/measure/node-inspection-service) documents.
</Callout>

### Verify synchronization

During the initial synchronization of your PFN, there may be a lot of data to transfer. You can monitor state sync progress
by querying the metrics port to see what version your node is currently synced to. Run the following example
command to see the currently synced version of your node:

```shellscript filename="Terminal"
curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_state_sync_version{.*\"synced\"}" | awk '{print $2}'
```

The command will output the current synced version of your node. For example:

```shellscript filename="Terminal"
71000
```

Compare the synced version returned by this command (e.g., `71000`) with the highest version shown on the
[Movement explorer page](https://explorer.movementnetwork.xyz/?network=bardock+testnet). If your node is catching up to the highest
version, it is synchronizing correctly. It is fine if the explorer page differs by a few versions, as the explorer
nodes may sync with some variance.

<Callout type="warning">
  **Using fast sync?**<br />
  If your node is fast syncing, the command may show `0` until it has finally caught up. To verify that the node is
  fast syncing, run the following command:

```shellscript filename="Terminal"
  curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_state_sync_version{.*\"synced_states\"}" | awk '{print $2}'
  ```

This should show an increasing number of synced states. It may take several hours for your node to fast sync to the
  latest version. Eventually, once fast syncing is complete, the `aptos_state_sync_version{.*"synced"}` command will
  return the current synced version of your node.
</Callout>

### (Optional) Verify outbound network connections

If you wish, you can also check the outbound network connections for your PFN. The number of outbound network
connections should be more than `0` for healthy PFNs. Run the following command:

```shellscript filename="Terminal"
curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_connections{direction=\"outbound\""
```

The above command will output the number of outbound network connections for your node. For example:

```shellscript filename="Terminal"
curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_connections{direction=\"outbound\""
aptos_connections{direction="outbound",network_id="Public",peer_id="aabd651f",role_type="full_node"} 3
```

If the number of outbound connections returned is `0`, then it means your node cannot connect to the Movement blockchain. If this happens to you, follow these steps to resolve the issue:

1. Update your node to the latest release.
2. Remove any `seed` peers you may have added to your configuration file. The seeds may be preventing you from
   connecting to the network.

### (Optional) Examine Docker ledger size

If you are running your PFN using Docker, you can monitor the size of the blockchain ledger by entering the Docker
container and checking the size. This will allow you to see how much storage the blockchain ledger is currently consuming.

* First, run `docker container ls` on your terminal and copy the NAME field output. This will be a string similar to `public_full_node_fullnode_1`.
* Next, run these commands to check the storage size consumed by the ledger, using the NAME field you copied over in place of `public_full_node_fullnode_1`:

```shellscript filename="Terminal"
# Obtain the container ID:
id=$(docker container ls | grep public_full_node_fullnode_1 | grep -oE "^[0-9a-zA-Z]+")

# Enter the container:
docker exec -it $id /bin/bash

# Observe the volume (ledger) size:
du -cs -BM /opt/aptos/data
```

[rest_spec]: https://github.com/movement-network/aptos-core/tree/m1/api

[movement-network/aptos-core]: https://github.com/movement-network/aptos-core.git

# Using Docker
URL: /general/nodes/archival-node/run/deploy/docker

This guide describes how to deploy an archival fullnode using Docker.

<Callout type="warning">
  **Supported only on x86-64 CPUs**

Running aptos-core via Docker is currently only supported on x86-64 CPUs. If you have an Apple M1/M2 (ARM64) Mac, use the [source code approach](/general/nodes/archival-node/run/deploy/source) instead.
</Callout>

## Prerequisites

* [Docker](https://docs.docker.com/get-docker/) installed
* [restic](https://restic.net/) installed for data restoration
* Sufficient storage (mainnet \~700GB, testnet \~260GB)

## Step 1: Create Working Directory

```shellscript filename="Terminal"
# For mainnet
mkdir -p mainnet-archival && cd mainnet-archival

# For testnet
mkdir -p testnet-archival && cd testnet-archival
```

## Step 2: Download Configuration Files

Download the archival fullnode configuration and genesis files:

### For Mainnet

```shellscript filename="Terminal"
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/configs/archival-fullnode.yaml
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/genesis.blob
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/waypoint.txt
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/genesis_waypoint.txt
```

### For Testnet

```shellscript filename="Terminal"
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/configs/archival-fullnode.yaml
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/genesis.blob
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/waypoint.txt
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/genesis_waypoint.txt
```

## Step 3: Restore Data from Backup

Restore blockchain data from Move Industries' public backups using the restore script:

```shellscript filename="Terminal"
# Download the restore script
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/l1_restore.sh
chmod +x l1_restore.sh

# Restore data (use 'mainnet' or 'testnet')
./l1_restore.sh mainnet ./data

# Move data to the correct location for Docker
mv data/opt/data/aptos/* data/
rm -rf data/opt
```

<Callout type="warning">
  **Restore Time**

Restoring from backup can take several hours depending on your network speed. Mainnet data is approximately 700GB and testnet is approximately 260GB.
</Callout>

## Step 4: Run the Archival Node

Start the archival node using Docker:

```shellscript filename="Terminal"
docker run --pull=always \
  --rm -p 8080:8080 \
  -p 9101:9101 -p 6180:6180 \
  -v $(pwd):/opt/aptos \
  -v $(pwd)/data:/opt/aptos/data \
  --workdir /opt/aptos \
  --name=aptos-archival-node \
  ghcr.io/movement-network/aptos-node:f24a5bc \
  -f /opt/aptos/archival-fullnode.yaml
```

<Callout type="info">
  **Running in Background**

To run the node in the background, add the `-d` flag:

```shellscript filename="Terminal"
  docker run --pull=always -d \
    --rm -p 8080:8080 \
    -p 9101:9101 -p 6180:6180 \
    -v $(pwd):/opt/aptos \
    -v $(pwd)/data:/opt/aptos/data \
    --workdir /opt/aptos \
    --name=aptos-archival-node \
    ghcr.io/movement-network/aptos-node:f24a5bc \
    -f /opt/aptos/archival-fullnode.yaml
  ```

View logs with: `docker logs -f aptos-archival-node`
</Callout>

## Step 5: Verify the Node

Verify that your archival node is running correctly:

```shellscript filename="Terminal"
# Check the node is responding
curl http://localhost:8080/v1

# Check the ledger version
curl -s http://localhost:8080/v1 | jq '.ledger_version'

# Verify historical data access (query genesis transaction)
curl http://localhost:8080/v1/transactions/by_version/1

# Check oldest available ledger version (should be 0 for archival)
curl -s http://localhost:8080/v1 | jq '.oldest_ledger_version'
```

<Callout type="info">
  **Sync Time**

After restoring from backup, your archival node will need to sync the remaining transactions from the backup point to the current chain head. This typically takes a few hours depending on how recent the backup is.
</Callout>

## Managing the Node

### View Logs

```shellscript filename="Terminal"
docker logs -f aptos-archival-node
```

### Stop the Node

```shellscript filename="Terminal"
docker stop aptos-archival-node
```

### Restart the Node

```shellscript filename="Terminal"
docker start aptos-archival-node
```

## Ports

| Port | Purpose                                 |
| ---- | --------------------------------------- |
| 8080 | REST API                                |
| 9101 | Metrics (Prometheus)                    |
| 6180 | Internal use                            |
| 6182 | P2P networking (not exposed by default) |

<Callout type="warning">
  **Don't want to allow inbound P2P connections?**

The default configuration doesn't expose port 6182. If you want to allow other PFNs to connect to yours, add `-p 6182:6182` to the docker command.
</Callout>

## Next Steps

* [Verify your archival node](/general/nodes/archival-node/run/verify)

# Deploy an Archival Node
URL: /general/nodes/archival-node/run/deploy

This section covers the different methods to deploy an archival fullnode on the Movement Network.

## Deployment Options

Choose the deployment method that best fits your needs:

| Method                                                        | Best For                    | Complexity |
| ------------------------------------------------------------- | --------------------------- | ---------- |
| [Docker](/general/nodes/archival-node/run/deploy/docker)      | Quick setup, production use | Low        |
| [Source Code](/general/nodes/archival-node/run/deploy/source) | Customization, development  | Medium     |

## Prerequisites

Regardless of deployment method, you'll need:

* **Storage**: 1TB+ SSD (2TB+ recommended for mainnet)
* **Memory**: 16GB+ RAM
* **CPU**: 8+ cores
* **Network**: Reliable internet connection
* **restic**: For restoring from backups ([installation](https://restic.net/))

### Install restic

restic is used to restore blockchain data from Move Industries' public backups.

```shellscript filename="Terminal"
# Ubuntu/Debian
sudo apt update && sudo apt install -y restic

# macOS
brew install restic

# Or download directly
curl -LO https://github.com/restic/restic/releases/download/v0.18.1/restic_0.18.1_linux_amd64.bz2
bunzip2 restic_0.18.1_linux_amd64.bz2
chmod +x restic_0.18.1_linux_amd64
sudo mv restic_0.18.1_linux_amd64 /usr/local/bin/restic
```

## Restore Data from Backup

Before starting your archival node, restore existing blockchain data from Move Industries' public backups. This is the recommended approach as syncing from genesis would take an extremely long time.

Download and run the restore script from the Movement Networks repository:

```shellscript filename="Terminal"
# Download the restore script
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/l1_restore.sh
chmod +x l1_restore.sh

# Restore mainnet data (~700GB)
./l1_restore.sh mainnet ./data

# Or restore testnet data (~260GB)
./l1_restore.sh testnet ./data
```

<Callout type="warning">
  **Restore Time**

Restoring from backup can take several hours depending on your network speed:

* Mainnet: \~700GB
  * Testnet: \~260GB
</Callout>

## Configuration Files

Download the archival fullnode configuration and genesis files:

### For Mainnet

```shellscript filename="Terminal"
mkdir -p mainnet-archival && cd mainnet-archival
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/configs/archival-fullnode.yaml
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/genesis.blob
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/waypoint.txt
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/genesis_waypoint.txt
```

### For Testnet

```shellscript filename="Terminal"
mkdir -p testnet-archival && cd testnet-archival
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/configs/archival-fullnode.yaml
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/genesis.blob
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/waypoint.txt
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/genesis_waypoint.txt
```

## Next Steps

After restoring data and downloading configuration files, proceed to deploy:

* [Deploy with Docker](/general/nodes/archival-node/run/deploy/docker)
* [Deploy from Source](/general/nodes/archival-node/run/deploy/source)

# Using Source Code
URL: /general/nodes/archival-node/run/deploy/source

This guide describes how to deploy an archival fullnode by building from the Move Industries `aptos-core` source code.

## Prerequisites

* [Rust toolchain](https://rustup.rs/) installed
* [restic](https://restic.net/) installed for data restoration
* Sufficient storage (mainnet \~700GB, testnet \~260GB)
* Build dependencies installed

### Install Build Dependencies (Linux)

```shellscript filename="Terminal"
sudo apt update
sudo apt install -y binutils build-essential lld pkg-config libdw-dev
```

## Step 1: Clone and Build

```shellscript filename="Terminal"
# Clone the Movement aptos-core repository
git clone https://github.com/movement-network/aptos-core.git
cd aptos-core

# Check out the l1-migration branch
git checkout --track origin/l1-migration

# Build the release binary (this will take some time)
cargo build -p aptos-node --release
```

<Callout type="info">
  **Build Time**

The initial build can take 15-30 minutes depending on your hardware. Subsequent builds are faster due to caching.
</Callout>

## Step 2: Download Configuration Files

Download the archival fullnode configuration and genesis files:

### For Mainnet

### For Testnet

## Step 3: Update Configuration Paths

Edit the `archival-fullnode.yaml` to use local paths:

```yaml filename="archival-fullnode.yaml"
base:
  role: "full_node"
  data_dir: "./data"  # Local data directory
  waypoint:
    from_file: "./waypoint.txt"

execution:
  genesis_file_location: "./genesis.blob"
  genesis_waypoint:
    from_file: "./genesis_waypoint.txt"

storage:
  rocksdb_configs:
    enable_storage_sharding: false
  # ARCHIVAL NODE: Disable ledger pruning
  storage_pruner_config:
    ledger_pruner_config:
      enable: false

full_node_networks:
  # ... (keep network configuration as-is)

api:
  enabled: true
  address: 0.0.0.0:8080

state_sync:
  state_sync_driver:
    bootstrapping_mode: DownloadLatestStates
    continuous_syncing_mode: ApplyTransactionOutputs
```

## Step 4: Restore Data from Backup

Restore blockchain data from Move Industries' public backups using the restore script:

```shellscript filename="Terminal"
# Download the restore script
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/l1_restore.sh
chmod +x l1_restore.sh

# Restore data (use 'mainnet' or 'testnet')
./l1_restore.sh mainnet ./data

# Or for testnet:
# ./l1_restore.sh testnet ./data

# Move data to the correct location
mv data/opt/data/aptos/* data/
rm -rf data/opt
```

<Callout type="warning">
  **Restore Time**

Restoring from backup can take several hours depending on your network speed. Mainnet data is approximately 700GB and testnet is approximately 260GB.
</Callout>

## Step 5: Run the Archival Node

Start the archival node:

```shellscript filename="Terminal"
# Using the release binary
./target/release/aptos-node -f ./archival-fullnode.yaml

# Or using cargo run
cargo run -p aptos-node --release -- -f ./archival-fullnode.yaml
```

<Callout type="info">
  **Running in Background**

To run as a background service, consider using systemd or a process manager like `pm2` or `supervisord`.

Example using nohup:

```shellscript filename="Terminal"
  nohup ./target/release/aptos-node -f ./archival-fullnode.yaml > node.log 2>&1 &
  ```
</Callout>

## Step 6: Verify the Node

Verify that your archival node is running correctly:

```shellscript filename="Terminal"
# Check the node is responding
curl http://localhost:8080/v1

# Check the ledger version
curl -s http://localhost:8080/v1 | jq '.ledger_version'

# Verify historical data access (query genesis transaction)
curl http://localhost:8080/v1/transactions/by_version/1

# Check oldest available ledger version (should be 0 for archival)
curl -s http://localhost:8080/v1 | jq '.oldest_ledger_version'
```

<Callout type="info">
  **Sync Time**

## Running as a Systemd Service

Create a systemd service file for automatic startup:

```ini filename="/etc/systemd/system/movement-archival.service"
[Unit]
Description=Movement Archival Node
After=network.target

[Service]
Type=simple
User=movement
WorkingDirectory=/home/movement/aptos-core
ExecStart=/home/movement/aptos-core/target/release/aptos-node -f /home/movement/aptos-core/archival-fullnode.yaml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Enable and start the service:

```shellscript filename="Terminal"
sudo systemctl daemon-reload
sudo systemctl enable movement-archival
sudo systemctl start movement-archival

# Check status
sudo systemctl status movement-archival

# View logs
sudo journalctl -u movement-archival -f
```

## Updating the Node

To update to a newer version:

```shellscript filename="Terminal"
# Stop the node
sudo systemctl stop movement-archival  # or kill the process

# Pull latest changes
cd aptos-core
git pull origin l1-migration

# Rebuild
cargo build -p aptos-node --release

# Restart
sudo systemctl start movement-archival
```

## Troubleshooting

### Build fails

1. Ensure all build dependencies are installed
2. Check Rust version: `rustc --version`
3. Try cleaning and rebuilding: `cargo clean && cargo build -p aptos-node --release`

### Node won't start

1. Check configuration file syntax
2. Verify all paths in the config are correct
3. Ensure data directory exists and has correct permissions

### Node is not syncing

1. Check logs for connection errors
2. Verify network connectivity to upstream peers
3. Ensure port 6182 is open for outbound connections

## Next Steps

* [Verify your archival node](/general/nodes/archival-node/run/verify)

# Using Docker
URL: /general/nodes/full-node/run/deploy/docker

This section describes how to configure and run your PFN using Docker.

<Callout type="warning">
  **Supported only on x86-64 CPUs**

Running aptos-core via Docker is currently only supported on x86-64 CPUs. If you have an Apple M1/M2 (ARM64) Mac, use the [source code approach](/general/nodes/full-node/run/deploy/source) instead.
</Callout>

## Prerequisites

* [Docker](https://docs.docker.com/get-docker/) installed
* Sufficient storage space (\~50-100GB)

## Step 1: Download Configuration Files

Download the fullnode configuration and genesis files for your network:

### For Mainnet

```shellscript filename="Terminal"
mkdir -p mainnet && cd mainnet
mkdir -p data
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/configs/fullnode.yaml
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/genesis.blob
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/waypoint.txt
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/genesis_waypoint.txt
```

### For Testnet

```shellscript filename="Terminal"
mkdir -p testnet && cd testnet
mkdir -p data
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/configs/fullnode.yaml
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/genesis.blob
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/waypoint.txt
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/genesis_waypoint.txt
```

<Callout type="info">
  **Genesis files repository**

All configuration and genesis files are maintained at [https://github.com/movement-network/movement-networks](https://github.com/movement-network/movement-networks)
</Callout>

## Step 2: Run the Fullnode

Start the fullnode using Docker:

```shellscript filename="Terminal"
docker run --pull=always \
  --rm -p 8080:8080 \
  -p 9101:9101 -p 6180:6180 \
  -v $(pwd):/opt/aptos \
  -v $(pwd)/data:/opt/aptos/data \
  --workdir /opt/aptos \
  --name=aptos-fullnode \
  ghcr.io/movement-network/aptos-node:f24a5bc \
  -f /opt/aptos/fullnode.yaml
```

<Callout type="info">
  **Running in Background**

To run the node in the background, add the `-d` flag:

```shellscript filename="Terminal"
  docker run --pull=always -d \
    --rm -p 8080:8080 \
    -p 9101:9101 -p 6180:6180 \
    -v $(pwd):/opt/aptos \
    -v $(pwd)/data:/opt/aptos/data \
    --workdir /opt/aptos \
    --name=aptos-fullnode \
    ghcr.io/movement-network/aptos-node:f24a5bc \
    -f /opt/aptos/fullnode.yaml
  ```

View logs with: `docker logs -f aptos-fullnode`
</Callout>

<Callout type="warning">
  **Sudo access**

You may need to prefix the docker command with `sudo` depending on your configuration.
</Callout>

## Step 3: Verify the Node

Check that your node is running:

```shellscript filename="Terminal"
curl http://localhost:8080/v1
```

You should see a JSON response with the node's status including `chain_id`, `epoch`, and `ledger_version`.

## Configuration Details

The downloaded `fullnode.yaml` contains the following configuration:

```yaml
base:
  role: "full_node"
  data_dir: "/opt/aptos/data"
  waypoint:
    from_file: "/opt/aptos/waypoint.txt"

execution:
  genesis_file_location: "/opt/aptos/genesis.blob"
  genesis_waypoint:
    from_file: "/opt/aptos/genesis_waypoint.txt"

storage:
  rocksdb_configs:
    enable_storage_sharding: false

full_node_networks:
  - network_id: "public"
    discovery_method: "none"
    listen_address: "/ip4/0.0.0.0/tcp/6182"
    seeds:
      # Network-specific seed node configuration
      ...

api:
  enabled: true
  address: 0.0.0.0:8080

state_sync:
  state_sync_driver:
    bootstrapping_mode: DownloadLatestStates
    continuous_syncing_mode: ApplyTransactionOutputs
```

<Callout type="warning">
  **Don't want to allow inbound connections?**

Override the listen address in your config if you don't want other PFNs connecting to yours:

```yaml
  listen_address: "/ip4/127.0.0.1/tcp/6182"
  ```
</Callout>

## Ports

## Docker Tags

The `latest` tag always refers to the latest official Docker image. You can find the current version at:

* Mainnet: [https://github.com/movement-network/movement-networks/tree/main/mainnet](https://github.com/movement-network/movement-networks/tree/main/mainnet)
* Testnet: [https://github.com/movement-network/movement-networks/tree/main/testnet](https://github.com/movement-network/movement-networks/tree/main/testnet)

## Next Steps

* [Verify your PFN](/general/nodes/full-node/run/verify) - Check that your node is running correctly
* [Archival Node](/general/nodes/archival-node) - If you need complete historical data

# Deploy a PFN
URL: /general/nodes/full-node/run/deploy

The following guides provide step-by-step instructions for deploying a PFN on the Movement networks.

<Callout type="info">
  **Do I have to run a PFN?**<br />
  If you do not wish to run a PFN, but still want to interact with the Movement blockchain, you can use the REST API
  provided by the Move Industries' PFNs (see [Movement APIs](/api)). Note, however, that Move Industries-provided PFNs have rate
  limits, which can impede your development. You can deploy your own PFN
  and synchronize with the Movement blockchain directly, or use a different node infrastructure provider.
</Callout>

Select the guide for the deployment method you prefer:

<Callout type="warning">
  **Choose a network**<br />
  These guides default to deploying a PFN in the Movement for mainnet or testnet network.
  To find all configuration files for all Movement networks, check out the
  [movement-networks](https://github.com/movement-network/movement-networks) repo
  and use the `genesis.blob` and `waypoint.txt` node files for the respective networks:
  [mainnet](https://github.com/movement-network/movement-networks/blob/main/mainnet/README.md)
  and [testnet](https://github.com/movement-network/movement-networks/blob/main/testnet/README.md).
</Callout>

* ### [Using Source Code](/general/nodes/full-node/run/deploy/source)
* ### [Using Docker](/general/nodes/full-node/run/deploy/docker)

# Using Source Code
URL: /general/nodes/full-node/run/deploy/source

This guide describes how to deploy a PFN using the `aptos-core` source code maintained by Move Industries.

## Prerequisites

* [Rust toolchain](https://rustup.rs/) installed
* Sufficient storage space (\~50-100GB)
* Build dependencies installed

### Install Build Dependencies (Linux)

```shellscript filename="Terminal"
sudo apt update
sudo apt install -y binutils build-essential lld pkg-config libdw-dev
```

## Step 1: Clone and Build

```shellscript filename="Terminal"
# Clone the Movement aptos-core repository
git clone https://github.com/movement-network/aptos-core.git
cd aptos-core

# Check out the l1-migration branch
git checkout --track origin/l1-migration

# Build the release binary
cargo build -p aptos-node --release
```

<Callout type="info">
  **Build Time**

The initial build can take 15-30 minutes depending on your hardware. The release binary will be at `target/release/aptos-node`.
</Callout>

## Step 2: Download Configuration Files

Download the fullnode configuration and genesis files for your network:

### For Mainnet

```shellscript filename="Terminal"
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/configs/fullnode.yaml
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/genesis.blob
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/waypoint.txt
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/mainnet/genesis_waypoint.txt
```

### For Testnet

```shellscript filename="Terminal"
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/configs/fullnode.yaml
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/genesis.blob
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/waypoint.txt
curl -O https://raw.githubusercontent.com/movement-network/movement-networks/main/testnet/genesis_waypoint.txt
```

<Callout type="info">
  **Genesis files repository**

All configuration and genesis files are maintained at [https://github.com/movement-network/movement-networks](https://github.com/movement-network/movement-networks)
</Callout>

## Step 3: Update Configuration Paths

Edit the `fullnode.yaml` to use local paths:

```yaml filename="fullnode.yaml"
base:
  role: "full_node"
  data_dir: "./data"  # Local data directory
  waypoint:
    from_file: "./waypoint.txt"

execution:
  genesis_file_location: "./genesis.blob"
  genesis_waypoint:
    from_file: "./genesis_waypoint.txt"
```

Create the data directory:

```shellscript filename="Terminal"
mkdir -p data
```

## Step 4: Run the Fullnode

Start the fullnode:

```shellscript filename="Terminal"
# Using the release binary
./target/release/aptos-node -f ./fullnode.yaml

# Or using cargo run
cargo run -p aptos-node --release -- -f ./fullnode.yaml
```

<Callout type="info">
  **Debug vs Release**

The release binary is substantially faster than debug builds but lacks debugging information. To build a debug binary for development, omit the `--release` flag.
</Callout>

## Step 5: Verify the Node

Check that your node is running:

```shellscript filename="Terminal"
curl http://localhost:8080/v1
```

You should see a JSON response with the node's status including `chain_id`, `epoch`, and `ledger_version`.

## Running as a Background Service

To run the node as a systemd service:

```ini filename="/etc/systemd/system/movement-fullnode.service"
[Unit]
Description=Movement Full Node
After=network.target

[Install]
WantedBy=multi-user.target
```

Enable and start the service:

```shellscript filename="Terminal"
sudo systemctl daemon-reload
sudo systemctl enable movement-fullnode
sudo systemctl start movement-fullnode

# Check status
sudo systemctl status movement-fullnode

# View logs
sudo journalctl -u movement-fullnode -f
```

## Configuration Details

The downloaded `fullnode.yaml` contains the following key settings:

```yaml
base:
  role: "full_node"
  data_dir: "/opt/aptos/data"
  waypoint:
    from_file: "/opt/aptos/waypoint.txt"

execution:
  genesis_file_location: "/opt/aptos/genesis.blob"
  genesis_waypoint:
    from_file: "/opt/aptos/genesis_waypoint.txt"

storage:
  rocksdb_configs:
    enable_storage_sharding: false

full_node_networks:
  - network_id: "public"
    discovery_method: "none"
    listen_address: "/ip4/0.0.0.0/tcp/6182"
    seeds:
      # Network-specific seed node
      ...

api:
  enabled: true
  address: 0.0.0.0:8080

state_sync:
  state_sync_driver:
    bootstrapping_mode: DownloadLatestStates
    continuous_syncing_mode: ApplyTransactionOutputs
```

## Updating the Node

To update to a newer version:

```shellscript filename="Terminal"
# Stop the node
sudo systemctl stop movement-fullnode  # or kill the process

# Pull latest changes
cd aptos-core
git pull origin l1-migration

# Rebuild
cargo build -p aptos-node --release

# Restart
sudo systemctl start movement-fullnode
```

## Troubleshooting

### Build fails

1. Ensure all build dependencies are installed
2. Check Rust version: `rustc --version`
3. Try cleaning and rebuilding: `cargo clean && cargo build -p aptos-node --release`

### Node won't start

1. Check configuration file syntax
2. Verify all paths in the config are correct
3. Ensure data directory exists and has correct permissions

### Node is not syncing

1. Check logs for connection errors
2. Verify network connectivity to upstream peers
3. Ensure port 6182 is open for outbound connections

## Next Steps

* [Verify your PFN](/general/nodes/full-node/run/verify) - Check that your node is running correctly
* [Archival Node](/general/nodes/archival-node) - If you need complete historical data