aptos-framework

---
name: aptos-framework
description: Expert on Aptos Framework (0x1 standard library) modules including account, coin, fungible_asset, object, timestamp, table, smart_table, event, randomness, aggregator, and resource_account. Essential for all Aptos development.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
license: MIT
metadata:
  author: raintree
  version: "1.0"
---

# Aptos Framework Expert

Expert on the Aptos Framework (0x1 address) - the standard library of core modules.

## Triggers

- aptos framework, 0x1::, aptos_framework::
- account module, table, smarttable
- event, timestamp, randomness
- aggregator, resource account

## Framework Architecture

### Core Modules (0x1::)

```
aptos_framework/
├── account.move           - Account management
├── coin.move              - Fungible token standard (v1)
├── fungible_asset.move    - Fungible asset standard (v2)
├── object.move            - Object model primitives
├── timestamp.move         - Block timestamp access
├── table.move             - Key-value storage
├── smart_table.move       - Auto-split table
├── event.move             - Event emission
├── randomness.move        - Secure randomness (VRF)
├── aggregator_v2.move     - Parallel execution
├── resource_account.move  - Deterministic deployment
```

### Standard Library (std::)

```
move-stdlib/
├── vector.move      - Dynamic arrays
├── option.move      - Optional values
├── string.move      - UTF8 strings
├── signer.move      - Signer operations
├── error.move       - Error codes
```

## Key Modules

### account.move

```move
use aptos_framework::account;

// Create account
account::create_account(new_address);

// Get sequence number
account::get_sequence_number(addr);

// Check existence
account::exists_at(addr);

// SignerCapability pattern
let (resource_signer, signer_cap) = account::create_resource_account(deployer, b"SEED");
```

### table.move / smart_table.move

```move
use aptos_framework::table::{Self, Table};

struct Registry has key {
    data: Table<address, UserData>
}

table::add(&mut t, key, value);
table::borrow(&t, key);
table::borrow_mut(&mut t, key);
table::remove(&mut t, key);
table::contains(&t, key);
```

### event.move (V2 - Recommended)

```move
#[event]
struct TransferEvent has drop, store {
    from: address,
    to: address,
    amount: u64,
}

event::emit(TransferEvent { from, to, amount });
```

### timestamp.move

```move
use aptos_framework::timestamp;

timestamp::now_seconds();
timestamp::now_microseconds();
```

### randomness.move

```move
use aptos_framework::randomness;

#[randomness]
public entry fun random_mint(user: &signer) {
    let random_value = randomness::u64_integer();
    let amount = randomness::u64_range(100, 1000);
}
```

### aggregator_v2.move

```move
use aptos_framework::aggregator_v2::{Self, Aggregator};

struct Stats has key {
    total: Aggregator<u64>  // Parallel-safe counter
}

aggregator_v2::create_aggregator(0);
aggregator_v2::add(&mut agg, 1);
aggregator_v2::read(&agg);
```

### resource_account.move

```move
// Deterministic address: hash(creator_address, seed)
let (resource_signer, signer_cap) = account::create_resource_account(deployer, b"SEED");

// Store capability for later use
move_to(&resource_signer, Data { signer_cap });

// Use later
let signer = account::create_signer_with_capability(&signer_cap);
```

## Common Patterns

### Time-Locked Operations

```move
struct TimeLock has key {
    unlock_time: u64,
}

public fun withdraw() acquires TimeLock {
    assert!(timestamp::now_seconds() >= timelock.unlock_time, ERROR_LOCKED);
}
```

### Registry with Table

```move
struct Registry<K: copy + drop, V: store> has key {
    data: Table<K, V>,
    count: u64,
}
```

### Event-Driven State

```move
#[event]
struct StateChanged has drop, store {
    old_state: u8,
    new_state: u8,
    timestamp: u64,
}

event::emit(StateChanged { old_state, new_state, timestamp: timestamp::now_seconds() });
```

## Best Practices

- Use SmartTable for large datasets (100k+ entries)
- Use Event V2 API (simpler, cheaper)
- Use Aggregator for global counters (parallel execution)
- Use resource accounts for protocol addresses
- Check timestamp carefully (validator-set, can drift)
- Use randomness only in entry functions with #[randomness]