Aptos Move Examples

A curated collection of Move language examples for the Aptos blockchain. Each snippet demonstrates a specific concept, design pattern, or feature of Move on Aptos, written using Move 2 syntax.

Originally created by @gregnazario as a series of educational tweets on learning Move piece by piece.

Coding agents: start at AGENTS.md (commands, named addresses, non-interactive CLI). Doc index: llms.txt.

---

Table of Contents

• Overview
• Prerequisites
• Quick Start
• For coding agents
• Example Documentation
• Examples by Category
  • Beginner
  • Intermediate
  • Advanced
• Example Index
• Concepts Covered
• Project Structure
• Named Addresses

---

Overview

This repository contains standalone Move snippets that each focus on a specific topic. The examples progress from basic language features (error codes, structs, objects) through intermediate patterns (NFT minting, storage data structures) to advanced use cases (composable NFTs, liquid tokens, formal verification).

All examples use Move 2 syntax, including:

• Receiver-style function calls (vector.length() instead of vector::length(&vector))
• Index notation for resource access (Resource[address] instead of borrow_global<Resource>(address))
• Enum types
• Pattern matching with match
• for loops

---

Prerequisites

• Aptos CLI installed
• Basic familiarity with Move language concepts (modules, structs, resources, signers)
• An Aptos account only if you publish (not required to compile or test)

---

Quick Start

Run these from the repository root. Replace <example-dir> with a path from the example index. Most packages use the named address deploy_addr; exceptions are listed under Named Addresses.

Compile (no account)

aptos move compile --dev --package-dir snippets/<example-dir>

snippets/fractional-token cannot use --dev. Compile it with:

aptos move compile --named-addresses fraction_addr=0x1337,minter=0x2337 --package-dir snippets/fractional-token

Test

aptos move test --dev --package-dir snippets/<example-dir>

Not every package has tests. See the Tests column in the example index or the catalog in AGENTS.md.

Deploy

Publishing needs a CLI profile and prompts for confirmation unless you pass --assume-yes.

aptos init --network devnet --assume-yes
aptos move publish --assume-yes --named-addresses deploy_addr=default --package-dir snippets/<example-dir>

Using an explicit address instead of a profile name:

MY_ADDR=0x12345
aptos move publish --assume-yes --named-addresses deploy_addr=$MY_ADDR --package-dir snippets/<example-dir>

snippets/snipe-prevention must be deployed as a code object:

aptos move deploy-object --assume-yes --named-addresses antisnipe=default --package-dir snippets/snipe-prevention

After deploying, interact with your contract via the Aptos Explorer.

---

For coding agents

Practical rules:

• Compile and test locally; do not publish to mainnet.
• Never run aptos init without --network and --assume-yes (it will prompt or hang).
• Named addresses are not all deploy_addr. Check Move.toml or the catalog before compiling.
• Prefer --package-dir snippets/... from the repo root so commands match the READMEs.

---

Example Documentation

Every example has a README.md in its package directory. Each follows the same structure so you (or an agent) can scan any example quickly:

See Named Addresses below for the address placeholder each package expects at compile/deploy time.

For a summary of Move 2 features used across examples, see snippets/move-2/README.md.

---

Examples by Category

Beginner

Intermediate

Advanced

---

Example Index

---

Concepts Covered

Language Features

• Error Codes: Named constants with doc comments for readable abort messages
• Function Visibility: public, public entry, entry, private, public(friend), inline
• Structs & Resources: has key, has store, has copy, has drop abilities
• Generics & Phantom Types: phantom type parameters for type-safe wrappers
• Enum Types: Move 2 enum declarations with variant matching
• Pattern Matching: match expressions for enums and destructuring

Aptos Framework

• Object Model: ConstructorRef, ExtendRef, DeleteRef, TransferRef, object creation, named/sticky objects
• Token V2 (Token Objects): Collections, tokens, MutatorRef, BurnRef, numbered tokens
• Fungible Assets: Metadata, FungibleStore, primary stores, mint/burn/transfer
• Coin (Legacy): coin::initialize, mint/burn capabilities, CoinStore
• Randomness: randomness::u64_range for on-chain random number generation
• Timestamps: timestamp::now_seconds(), timestamp::now_microseconds()

Design Patterns

• Autonomous Objects: Objects that can act as signers via ExtendRef for programmatic actions
• Object Ownership Permission: Checking object::is_owner or object::owns before granting access
• Capability Pattern: Using structs as capabilities to gate access to privileged operations
• Named Objects: Deterministic object addresses via object::create_named_object
• Collection-Owned Minting: Object-owned collections that allow parallelized or public minting
• Dynamic NFTs: Changing token metadata (URI, description) based on state changes
• Composable NFTs: Nesting objects (equipping items) and reflecting changes in metadata
• Fractionalization: Converting a single NFT into fungible shares and back
• Escrow Patterns: Time-locked and simple escrow using objects and fungible stores

Storage & Data Structures

• Vector: O(1) append, O(n) lookup by value; best for small datasets
• SimpleMap: O(n) operations; stored as unsorted vector of key-value pairs
• Table: O(1) operations; no iteration; each entry stored separately on-chain
• SmartTable: O(bucket_size) operations; hybrid of vector and table with bucketing
• SmartVector: O(1) append; scales past vector limits using table-backed buckets
• Min Heap: Priority queue with O(n log n) sort, O(log n) insert/pop

Formal Verification

• Move Prover: spec blocks, ensures, requires, aborts_if, aborts_with
• Invariants: Struct invariants that must always hold
• Schemas: Reusable specification patterns

---

Project Structure

snippets/
├── composable-nfts/          # Dynamic composable Face + Hat NFTs
│   ├── Move.toml
│   └── sources/
│       └── composable_nfts.move
├── controlled-mint/          # Creator-controlled batch NFT minting
│   ├── Move.toml
│   └── sources/
│       └── controlled_mint.move
├── data-structures/
│   └── heap/                 # Min heap with formal verification
│       ├── Move.toml
│       ├── sources/
│       │   └── min_heap_u64.move
│       └── tests/
│           └── min_heap_u64_tests.move
├── design-patterns/
│   └── autonomous-objects/   # Autonomous object design pattern
│       ├── Move.toml
│       └── sources/
│           └── base.move
├── error-codes/              # Error code best practices
│   ├── Move.toml
│   └── sources/
│       └── error_codes.move
├── fa-lockup-example/        # Fungible asset time-locked escrow
│   ├── Move.toml
│   └── sources/
│       └── lockup.move
├── fractional-token/         # NFT fractionalization into fungible tokens
│   ├── Move.toml
│   ├── sources/
│   │   └── fractional_token.move
│   └── tests/
│       ├── common_tests.move
│       └── fractional_token_tests.move
├── liquid-nfts/              # NFT liquidity pools (3 implementations)
│   ├── Move.toml
│   └── sources/
│       ├── common.move
│       ├── liquid_coin.move
│       ├── liquid_coin_legacy.move
│       └── liquid_fungible_asset.move
├── lootbox/                  # On-chain mystery boxes with randomness
│   ├── Move.toml
│   └── sources/
│       └── mystery_box.move
├── modifying-nfts/           # Mutable NFT properties and extension
│   ├── Move.toml
│   └── sources/
│       └── modify_nfts.move
├── move-2/                   # Move 2 feature reference (redirects to examples)
│   └── README.md
├── parallel-nfts/            # Parallelized public NFT minting
│   ├── Move.toml
│   └── sources/
│       └── parallel_mint.move
├── private-vs-public/        # Function visibility & security
│   ├── cheater/
│   │   ├── Move.toml
│   │   └── sources/
│   │       └── cheater.move
│   └── dice_roll/
│       ├── Move.toml
│       └── sources/
│           └── dice_roll.move
├── prover/                   # Formal verification with Move Prover
│   ├── Move.toml
│   └── sources/
│       └── payment_escrow.move
├── snipe-prevention/         # Anti-snipe protection for token launches
│   ├── Move.toml
│   └── sources/
│       └── antisnipe_token.move
├── storage/                  # Data structure comparison with gas benchmarks
│   ├── Move.toml
│   └── sources/
│       ├── allowlist_simple_map.move
│       ├── allowlist_smart_table.move
│       ├── allowlist_smart_vector.move
│       ├── allowlist_table.move
│       ├── allowlist_vector.move
│       └── object_management.move
└── struct-capabilities/      # Capability-based mailbox system
    ├── Move.toml
    └── sources/
        └── mailbox.move

---

Named Addresses

Different examples use different named addresses in their Move.toml. When compiling without --dev, or when deploying, substitute the appropriate address. Agents: copy the compile line from the package README or from AGENTS.md rather than assuming deploy_addr.

---

License

See LICENSE for details.