write-contracts

name	write-contracts
description	Generates secure Aptos Move V2 smart contracts with Object model, Digital Asset integration, security patterns, and storage type guidance. Includes comprehensive storage decision framework for optimal data structure selection. Triggers on: 'write contract', 'create NFT collection', 'build marketplace', 'implement minting', 'generate Move module', 'create token contract', 'build DAO', 'implement staking'. Ask storage questions when: 'store', 'track', 'registry', 'mapping', 'list', 'collection'.
license	MIT
metadata	{"author":"aptos-labs","version":"1.0","category":"move","tags":["smart-contracts","move","nft","defi","objects"],"priority":"critical"}

Write Contracts Skill

Core Rules

Digital Assets (NFTs) ⭐ CRITICAL

1. ALWAYS use Digital Asset (DA) standard for ALL NFT-related contracts (collections, marketplaces, minting)
2. ALWAYS import aptos_token_objects::collection and aptos_token_objects::token modules
3. ALWAYS use Object<AptosToken> for NFT references (NOT generic Object<T>)
4. NEVER use legacy TokenV1 standard or aptos_token::token module (deprecated)
5. See ../../../patterns/move/DIGITAL_ASSETS.md for complete NFT patterns

Object Model

6. ALWAYS use Object<T> for all object references (NEVER raw addresses)
7. Generate all refs (TransferRef, DeleteRef) in constructor before ConstructorRef destroyed
8. Return Object<T> from constructors (NEVER return ConstructorRef)
9. Verify ownership with object::owner(obj) == signer::address_of(user)
10. Use object::generate_signer(&constructor_ref) for object signers
11. Use named objects for singletons: object::create_named_object(creator, seed)

Security

12. ALWAYS verify signer authority in entry functions: assert!(signer::address_of(user) == expected, E_UNAUTHORIZED)
13. ALWAYS validate inputs: non-zero amounts, address validation, string length checks
14. NEVER expose &mut references in public functions
15. NEVER skip signer verification in entry functions

Modern Syntax

16. Use inline functions and lambdas for iteration
17. Use receiver-style method calls: obj.is_owner(user) (define first param as self)
18. Use vector indexing: vector[index] instead of vector::borrow()
19. Use direct named addresses: @marketplace_addr (NOT helper functions)

Required Patterns

20. Use init_module for contract initialization on deployment
21. Emit events for ALL significant activities (create, transfer, update, delete)
22. Define clear error constants with descriptive names (E_NOT_OWNER, E_INSUFFICIENT_BALANCE)

Testability

23. Add accessor functions for struct fields - tests in separate modules cannot access struct fields directly
24. Use #[view] annotation for read-only accessor functions
25. Return tuples from accessors for multi-field access: (seller, price, timestamp)
26. Place #[view] BEFORE doc comments - /// comment before #[view] causes compiler warnings. Write #[view] first, then ///

Quick Workflow

1. Create module structure → Define structs, events, constants, init_module
2. Implement object creation → Use proper constructor pattern with all refs generated upfront
3. Add access control → Verify ownership and validate all inputs
4. Security check → Use security-audit skill before deployment

Key Example: Object Creation Pattern

struct MyObject has key {
    name: String,
    transfer_ref: object::TransferRef,
    delete_ref: object::DeleteRef,
}

// Error constants
const E_NOT_OWNER: u64 = 1;
const E_EMPTY_STRING: u64 = 2;
const E_NAME_TOO_LONG: u64 = 3;

// Configuration constants
const MAX_NAME_LENGTH: u64 = 100;

/// Create object with proper pattern
public fun create_my_object(creator: &signer, name: String): Object<MyObject> {
    // 1. Create object
    let constructor_ref = object::create_object(signer::address_of(creator));

    // 2. Generate ALL refs you'll need BEFORE constructor_ref is destroyed
    let transfer_ref = object::generate_transfer_ref(&constructor_ref);
    let delete_ref = object::generate_delete_ref(&constructor_ref);

    // 3. Get object signer
    let object_signer = object::generate_signer(&constructor_ref);

    // 4. Store data in object
    move_to(&object_signer, MyObject {
        name,
        transfer_ref,
        delete_ref,
    });

    // 5. Return typed object reference (ConstructorRef automatically destroyed)
    object::object_from_constructor_ref<MyObject>(&constructor_ref)
}

/// Update with ownership verification
public entry fun update_object(
    owner: &signer,
    obj: Object<MyObject>,
    new_name: String
) acquires MyObject {
    // ✅ ALWAYS: Verify ownership
    assert!(object::owner(obj) == signer::address_of(owner), E_NOT_OWNER);

    // ✅ ALWAYS: Validate inputs
    assert!(string::length(&new_name) > 0, E_EMPTY_STRING);
    assert!(string::length(&new_name) <= MAX_NAME_LENGTH, E_NAME_TOO_LONG);

    // Safe to proceed
    let obj_data = borrow_global_mut<MyObject>(object::object_address(&obj));
    obj_data.name = new_name;
}

Key Example: Accessor Functions for Testing

struct ListingInfo has store, drop, copy {
    seller: address,
    price: u64,
    listed_at: u64,
}

/// Accessor function - tests cannot access struct fields directly
/// Use tuple returns for multiple fields
#[view]
public fun get_listing_details(nft_addr: address): (address, u64, u64) acquires Listings {
    let listings = borrow_global<Listings>(get_marketplace_address());
    assert!(table::contains(&listings.items, nft_addr), E_NOT_LISTED);
    let listing = table::borrow(&listings.items, nft_addr);
    (listing.seller, listing.price, listing.listed_at)
}

/// Single-field accessor when only one value needed
#[view]
public fun get_staked_amount(user_addr: address): u64 acquires Stakes {
    let stakes = borrow_global<Stakes>(get_vault_address());
    if (table_with_length::contains(&stakes.items, user_addr)) {
        table_with_length::borrow(&stakes.items, user_addr).amount
    } else {
        0
    }
}

Module Structure Template

module my_addr::my_module {
    // ============ Imports ============
    use std::signer;
    use std::string::String;
    use aptos_framework::object::{Self, Object};
    use aptos_framework::event;

    // ============ Events ============
    #[event]
    struct ItemCreated has drop, store {
        item: address,
        creator: address,
    }

    // ============ Structs ============
    // Define your data structures

    // ============ Constants ============
    const E_NOT_OWNER: u64 = 1;
    const E_UNAUTHORIZED: u64 = 2;

    // ============ Init Module ============
    fun init_module(deployer: &signer) {
        // Initialize global state, registries, etc.
    }

    // ============ Public Entry Functions ============
    // User-facing functions

    // ============ Public Functions ============
    // Composable functions

    // ============ Private Functions ============
    // Internal helpers
}

Storage Type Selection

⚠️ When user mentions storage ("store", "track", "registry", "mapping", "list", "collection"):

1. Ask 2-3 Questions (see references/storage-decision-tree.md)

• Access pattern? (sequential vs key-value vs both)
• Expected size? (small vs large vs unknown)
• Need .length()? (conditional)

2. Recommend from Patterns (references/storage-patterns.md)

Pattern	Recommended Storage
User registry	Table<address, UserInfo>
Staking records	Table<address, StakeInfo>
Leaderboard	BigOrderedMap<u64, address>
Transaction log	SmartVector<TxRecord> or Vector
Whitelist (<100)	Vector<address>
Voting records	TableWithLength<address, bool>
Config (<50)	OrderedMap<String, Value>
DAO proposals	BigOrderedMap<u64, Proposal>
Asset collection	Vector<Object<T>> or SmartVector

3. Include Brief Gas Context

Example recommendations:

• "For staking, I recommend Table<address, StakeInfo> because you'll have unbounded users with concurrent operations (separate slots enable parallel access)"
• "For leaderboard, I recommend BigOrderedMap<u64, address> because you need sorted iteration (O(log n), use allocate_spare_slots for production)"

Storage Types Available

• Vector - Small sequential (<100 items)
• SmartVector - Large sequential (100+ items)
• Table - Unordered key-value lookups
• TableWithLength - Table with count tracking
• OrderedMap - Small sorted maps (<100 items)
• BigOrderedMap - Large sorted maps (100+ items)

⚠️ NEVER use SmartTable (deprecated, use BigOrderedMap)

Details: See references/ for decision tree, type comparisons, and gas optimization.

Anti-patterns

1. ❌ Never use legacy TokenV1 standard or import aptos_token::token
2. ❌ Never use resource accounts (use named objects instead)
3. ❌ Never return ConstructorRef from public functions
4. ❌ Never skip signer verification in entry functions
5. ❌ Never skip input validation (amounts, addresses, strings)
6. ❌ Never deploy without 100% test coverage
7. ❌ Never create helper functions that just return named addresses
8. ❌ Never skip event emission for significant activities
9. ❌ Never use old syntax when V2 syntax is available
10. ❌ Never skip init_module for contracts that need initialization
11. ❌ Never hardcode real private keys or secrets in code — use @my_addr named addresses and "0x..." placeholders
12. ❌ Never read .env or ~/.aptos/config.yaml — these contain private keys

Edge Cases to Handle

Scenario	Check	Error Code
Zero amounts	assert!(amount > 0, E_ZERO_AMOUNT)	E_ZERO_AMOUNT
Excessive amounts	assert!(amount <= MAX, E_AMOUNT_TOO_HIGH)	E_AMOUNT_TOO_HIGH
Empty vectors	assert!(vector::length(&v) > 0, E_EMPTY_VECTOR)	E_EMPTY_VECTOR
Empty strings	assert!(string::length(&s) > 0, E_EMPTY_STRING)	E_EMPTY_STRING
Strings too long	assert!(string::length(&s) <= MAX, E_STRING_TOO_LONG)	E_STRING_TOO_LONG
Zero address	assert!(addr != @0x0, E_ZERO_ADDRESS)	E_ZERO_ADDRESS
Overflow	assert!(a <= MAX_U64 - b, E_OVERFLOW)	E_OVERFLOW
Underflow	assert!(a >= b, E_UNDERFLOW)	E_UNDERFLOW
Division by zero	assert!(divisor > 0, E_DIVISION_BY_ZERO)	E_DIVISION_BY_ZERO
Unauthorized access	assert!(signer == expected, E_UNAUTHORIZED)	E_UNAUTHORIZED
Not object owner	assert!(object::owner(obj) == user, E_NOT_OWNER)	E_NOT_OWNER

References

Detailed Patterns (references/ folder):

• references/storage-decision-tree.md - ⭐ Storage type selection framework (ask when storage mentioned)
• references/storage-patterns.md - ⭐ Use-case patterns and smart defaults
• references/storage-types.md - Detailed comparison of all 6 storage types
• references/storage-gas-optimization.md - Gas optimization strategies for storage
• references/object-patterns.md - Named objects, collections, nested objects
• references/access-control.md - RBAC and permission systems
• references/safe-arithmetic.md - Overflow/underflow prevention
• references/initialization.md - init_module patterns and registry creation
• references/events.md - Event emission patterns
• references/v2-syntax.md - Modern Move V2 features (method calls, indexing, lambdas)
• references/complete-example.md - Full annotated NFT collection contract

Pattern Documentation (patterns/ folder):

• ../../../patterns/move/DIGITAL_ASSETS.md - Digital Asset (NFT) standard - CRITICAL for NFTs
• ../../../patterns/move/OBJECTS.md - Comprehensive object model guide
• ../../../patterns/move/SECURITY.md - Security checklist and patterns
• ../../../patterns/move/MOVE_V2_SYNTAX.md - Modern syntax examples

Official Documentation:

• Digital Asset Standard: https://aptos.dev/build/smart-contracts/digital-asset
• Object Model: https://aptos.dev/build/smart-contracts/object
• Security Guidelines: https://aptos.dev/build/smart-contracts/move-security-guidelines

Related Skills:

• search-aptos-examples - Find similar examples in aptos-core (optional)
• generate-tests - Write tests for contracts (use AFTER writing contracts)
• security-audit - Audit contracts before deployment