Write Contracts Skill

Core Rules

Digital Assets (NFTs) ⭐ CRITICAL

• ALWAYS use Digital Asset (DA) standard for ALL NFT-related contracts (collections, marketplaces, minting)

• ALWAYS import aptos_token_objects::collection and aptos_token_objects::token modules

• ALWAYS use Object<AptosToken> for NFT references (NOT generic Object<T> )

• NEVER use legacy TokenV1 standard or aptos_token::token module (deprecated)

• See ../../../patterns/move/DIGITAL_ASSETS.md for complete NFT patterns

Object Model

• ALWAYS use Object<T> for all object references (NEVER raw addresses)

• Generate all refs (TransferRef, DeleteRef) in constructor before ConstructorRef destroyed

• Return Object<T> from constructors (NEVER return ConstructorRef)

• Verify ownership with object::owner(obj) == signer::address_of(user)

• Use object::generate_signer(&constructor_ref) for object signers

• Use named objects for singletons: object::create_named_object(creator, seed)

Security

• ALWAYS verify signer authority in entry functions: assert!(signer::address_of(user) == expected, E_UNAUTHORIZED)

• ALWAYS validate inputs: non-zero amounts, address validation, string length checks

• NEVER expose &mut references in public functions

• NEVER skip signer verification in entry functions

Modern Syntax

• Use inline functions and lambdas for iteration

• Use receiver-style method calls: obj.is_owner(user) (define first param as self )

• Use vector indexing: vector[index] instead of vector::borrow()

• Use direct named addresses: @marketplace_addr (NOT helper functions)

Required Patterns

• Use init_module for contract initialization on deployment

• Emit events for ALL significant activities (create, transfer, update, delete)

• Define clear error constants with descriptive names (E_NOT_OWNER, E_INSUFFICIENT_BALANCE)

Testability

• Add accessor functions for struct fields - tests in separate modules cannot access struct fields directly

• Use #[view] annotation for read-only accessor functions

• Return tuples from accessors for multi-field access: (seller, price, timestamp)

• Place #[view] BEFORE doc comments - /// comment before #[view] causes compiler warnings. Write #[view]

first, then ///

Quick Workflow

• Create module structure → Define structs, events, constants, init_module

• Implement object creation → Use proper constructor pattern with all refs generated upfront

• Add access control → Verify ownership and validate all inputs

• 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

• ❌ Never use legacy TokenV1 standard or import aptos_token::token

• ❌ Never use resource accounts (use named objects instead)

• ❌ Never return ConstructorRef from public functions

• ❌ Never skip signer verification in entry functions

• ❌ Never skip input validation (amounts, addresses, strings)

• ❌ Never deploy without 100% test coverage

• ❌ Never create helper functions that just return named addresses

• ❌ Never skip event emission for significant activities

• ❌ Never use old syntax when V2 syntax is available

• ❌ Never skip init_module for contracts that need initialization

• ❌ Never hardcode real private keys or secrets in code — use @my_addr named addresses and "0x..."

placeholders

• ❌ 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