┌─────────────────────────────────────────────────────────────┐
│                    USER'S MACHINE (Off-Chain)                │
│                                                              │
│  1. User calls a function with private/public inputs         │
│  2. Function body executes locally                           │
│  3. Records are consumed (inputs) and created (outputs)      │
│  4. A zero-knowledge proof is generated                      │
│  5. Proof + encrypted outputs are sent to the network        │
│                                                              │
│  Available here: self.caller, self.signer, record ops,       │
│                  all computation, struct manipulation          │
│  NOT available: block.height, ChaCha::rand_*, mappings       │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    VALIDATORS (On-Chain)                      │
│                                                              │
│  6. Validators verify the proof (fast, no re-execution)      │
│  7. If the transition has a paired `async function`           │
│     (finalize), validators execute it on-chain to update      │
│     public state                                              │
│  8. If finalize fails, the ENTIRE transaction is rejected     │
│     (but the fee is still consumed)                          │
│                                                              │
│  Available here: Mapping::get/set/remove/contains,           │
│                  storage vars/vecs, block.height,             │
│                  block.timestamp, ChaCha::rand_*,            │
│                  snark.verify, snark.verify_batch             │
│  NOT available: private inputs, records, direct self.caller  │
│                 (must be passed as args from transition)       │
└─────────────────────────────────────────────────────────────┘

// 1. Imports (optional)
import credits.aleo;

// 2. Program declaration (required)
program my_program.aleo {
    @noupgrade
    async constructor() {}

    // 3. Struct definitions
    struct TokenInfo {
        name: field,
        symbol: field,
        decimals: u8,
    }

    // 4. Record definitions
    record Token {
        owner: address,        // mandatory field
        amount: u64,
        info: TokenInfo,       // records can contain structs
    }

    // 5. Mapping definitions (public on-chain key-value stores)
    mapping balances: address => u64;
    mapping total_supply: bool => u64;

    // 6. Storage variables (public on-chain singletons)
    storage supply: u64;

    // 7. Storage vectors (public on-chain dynamic arrays)
    storage holders: [address];

    // 8. Inline helper functions
    inline double(x: u64) -> u64 {
        return x * 2u64;
    }

    // 9. Entry-point transitions (off-chain only)
    transition mint_private(receiver: address, amount: u64) -> Token {
        return Token {
            owner: receiver,
            amount: double(amount),
            info: TokenInfo {
                name: 0field,
                symbol: 0field,
                decimals: 6u8,
            },
        };
    }

    // 10. Async transitions (off-chain + on-chain finalize)
    async transition mint(public receiver: address, public amount: u64) -> Future {
        // Off-chain logic here
        let caller: address = self.caller;
        return finalize_mint(caller, receiver, amount);
    }

    // 11. Finalize functions (on-chain logic)
    async function finalize_mint(caller: address, receiver: address, amount: u64) {
        // On-chain logic here
        let current: u64 = Mapping::get_or_use(balances, receiver, 0u64);
        Mapping::set(balances, receiver, current + amount);
    }
}

let arr: [u32; 4] = [1u32, 2u32, 3u32, 4u32];
let element: u32 = arr[0u32];  // Access by index
let nested: [[u32; 2]; 3] = [[1u32, 2u32], [3u32, 4u32], [5u32, 6u32]];

let t: (u32, bool) = (42u32, true);
let first: u32 = t.0;
let second: bool = t.1;

let some_val: u64? = 42u64;        // Has a value
let no_val: u64? = none;            // No value

// Unwrap (panics if none)
let val: u64 = some_val.unwrap();

// Unwrap with default (safe)
let val: u64 = no_val.unwrap_or(0u64);

let x: u32 = 42u32;
let y: u64 = x as u64;       // Widening cast (safe)
let z: field = x as field;    // Integer to field (safe)
let w: u8 = x as u8;         // Narrowing cast (may truncate)

let a: u8 = 255u8;
// let b: u8 = a + 1u8;           // FAILS: overflow
let b: u8 = a.add_wrapped(1u8);   // OK: wraps to 0u8

// Available wrapping variants:
// add_wrapped, sub_wrapped, mul_wrapped, div_wrapped
// pow_wrapped, shl_wrapped, shr_wrapped

CREATE → ENCRYPT → STORE ON-CHAIN → DECRYPT (owner only) → CONSUME → NULLIFY

program token.aleo {
    @noupgrade
    async constructor() {}

    // Record definition — owner field is MANDATORY
    record Token {
        owner: address,     // REQUIRED: who can spend this record
        amount: u64,
    }

    // Mint: creates a new record
    transition mint(receiver: address, amount: u64) -> Token {
        return Token {
            owner: receiver,
            amount: amount,
        };
    }

    // Transfer: consumes one record, creates two new records
    transition transfer(
        sender_token: Token,       // This record is CONSUMED (destroyed)
        receiver: address,
        amount: u64
    ) -> (Token, Token) {          // Two new records are CREATED
        let remaining: u64 = sender_token.amount - amount;

        // New record for receiver
        let receiver_token: Token = Token {
            owner: receiver,
            amount: amount,
        };

        // Change back to sender
        let change_token: Token = Token {
            owner: sender_token.owner,
            amount: remaining,
        };

        return (receiver_token, change_token);
    }
}

record Token {
    owner: address,            // Always private (encrypted)
    private amount: u64,       // Private (encrypted) — default
    public token_type: u8,     // Public (visible on-chain in transaction)
}

program counter.aleo {
    @noupgrade
    async constructor() {}

    mapping counts: address => u64;

    async transition increment(public amount: u64) -> Future {
        let caller: address = self.caller;
        return finalize_increment(caller, amount);
    }

    async function finalize_increment(caller: address, amount: u64) {
        // Static syntax (preferred)
        let current: u64 = Mapping::get_or_use(counts, caller, 0u64);
        Mapping::set(counts, caller, current + amount);

        // Method syntax (also valid)
        // let current: u64 = counts.get_or_use(caller, 0u64);
        // counts.set(caller, current + amount);
    }
}

program config.aleo {
    @noupgrade
    async constructor() {}

    storage admin: address;
    storage paused: bool;
    storage counter: u64;

    async transition initialize(public addr: address) -> Future {
        return finalize_initialize(addr);
    }

    async function finalize_initialize(addr: address) {
        admin = addr;              // Set value
        paused = false;            // Set value
        counter = 0u64;            // Set value
    }

    async transition increment() -> Future {
        return finalize_increment();
    }

    async function finalize_increment() {
        let current: u64 = counter.unwrap_or(0u64);
        counter = current + 1u64;
        // counter = none;         // Clear value
    }
}

program registry.aleo {
    @noupgrade
    async constructor() {}

    storage members: [address];

    async transition add_member(public member: address) -> Future {
        return finalize_add_member(member);
    }

    async function finalize_add_member(member: address) {
        members.push(member);
    }

    async transition remove_last() -> Future {
        return finalize_remove_last();
    }

    async function finalize_remove_last() {
        members.pop();
    }

    async transition get_member(public index: u32) -> Future {
        return finalize_get_member(index);
    }

    async function finalize_get_member(index: u32) {
        let member: address? = members.get(index);
        // Also available:
        // members.set(index, new_value);
        // members.len();
        // members.clear();
        // members.swap_remove(index);
    }
}

// If/else
if amount > 100u64 {
    // ...
} else if amount > 50u64 {
    // ...
} else {
    // ...
}

// Ternary
let fee: u64 = condition ? 10u64 : 5u64;

// For loops — bounds MUST be compile-time constants
for i: u8 in 0u8..10u8 {
    // Loop body
}

// This is INVALID — variable bounds are forbidden:
// let n: u8 = get_count();
// for i: u8 in 0u8..n { }  // COMPILER ERROR

// Workaround: use a fixed upper bound with early termination
for i: u64 in 0u64..100u64 {
    if i < actual_count {
        // Do work
    }
}

assert(condition);                    // Fails transaction if false
assert_eq(a, b);                      // Fails if a != b
assert_neq(a, b);                     // Fails if a == b

program example.aleo {
    @noupgrade
    async constructor() {}

    // Inline helper — defined INSIDE the program block
    // Automatically inlined, cannot be called externally
    inline double(x: u64) -> u64 {
        return x * 2u64;
    }

    // Entry point (callable externally)
    transition compute(public input: u64) -> u64 {
        return double(input); // Calls inline function
    }
}

transition admin_only() {
    // CORRECT: checks the original user
    assert_eq(self.signer, ADMIN_ADDRESS);

    // DANGEROUS: in cross-program calls, self.caller is the
    // intermediate program, not the user
    // assert_eq(self.caller, ADMIN_ADDRESS); // Don't do this for user auth
}

// Hash a struct to a field element
let hash: field = Poseidon2::hash_to_field(my_struct);

// Hash to an address
let addr: address = BHP256::hash_to_address(my_data);

// Pedersen64 accepts inputs up to 64 bits (u32, u16, u8, bool, etc.)
let small_commit: field = Pedersen64::commit_to_field(value_u32, salt);
// BHP256 accepts larger inputs including field, structs, etc.
let large_commit: group = BHP256::commit_to_group(value_field, salt);
// salt must be type `scalar`

let is_valid: bool = signature::verify(sig, addr, message);

async transition lottery() -> Future {
    return finalize_lottery();
}

async function finalize_lottery() {
    let random_bool: bool = ChaCha::rand_bool();
    let random_field: field = ChaCha::rand_field();
    let random_u32: u32 = ChaCha::rand_u32();
    let random_u64: u64 = ChaCha::rand_u64();
    // Also: rand_u8, rand_u16, rand_u128,
    //        rand_i8, rand_i16, rand_i32, rand_i64, rand_i128,
    //        rand_scalar, rand_address
}

# Add a network dependency (deployed program)
leo add credits.aleo --network

# Add a local dependency
leo add my_lib.aleo --local ../my_lib

# Remove a dependency
leo remove my_lib.aleo

import credits.aleo;

program my_app.aleo {
    @noupgrade
    async constructor() {}

    mapping payments: field => u64;

    async transition pay(public receiver: address, public amount: u64) -> Future {
        // Cross-program calls return a Future that must be awaited in the finalize function.
        let payer: address = self.caller;
        let transfer: Future = credits.aleo/transfer_public(receiver, amount);
        let payment_id: field = BHP256::hash_to_field(payer);
        return finalize_pay(transfer, payment_id, amount);
    }

    async function finalize_pay(transfer: Future, payment_id: field, amount: u64) {
        transfer.await();
        let total: u64 = Mapping::get_or_use(payments, payment_id, 0u64);
        Mapping::set(payments, payment_id, total + amount);
    }
}

{
    "program": "my_app.aleo",
    "version": "0.1.0",
    "description": "",
    "license": "MIT",
    "dependencies": [
        {
            "name": "credits.aleo",
            "location": "network",
            "network": "testnet"
        },
        {
            "name": "my_lib.aleo",
            "location": "local",
            "path": "../my_lib"
        }
    ]
}

program token.aleo {
    @noupgrade
    async constructor() {}

    // Private state: encrypted records
    record Token {
        owner: address,
        amount: u64,
    }

    // Public state: on-chain mappings
    mapping account: address => u64;

    // === PUBLIC OPERATIONS ===

    // Mint tokens to a public balance
    async transition mint_public(
        public receiver: address,
        public amount: u64,
    ) -> Future {
        return finalize_mint_public(receiver, amount);
    }

    async function finalize_mint_public(receiver: address, amount: u64) {
        let current_amount: u64 = Mapping::get_or_use(account, receiver, 0u64);
        Mapping::set(account, receiver, current_amount + amount);
    }

    // Transfer tokens between public balances
    async transition transfer_public(
        public receiver: address,
        public amount: u64,
    ) -> Future {
        let sender: address = self.caller;
        return finalize_transfer_public(sender, receiver, amount);
    }

    async function finalize_transfer_public(sender: address, receiver: address, amount: u64) {
        let sender_amount: u64 = Mapping::get_or_use(account, sender, 0u64);
        assert(sender_amount >= amount);
        Mapping::set(account, sender, sender_amount - amount);

        let receiver_amount: u64 = Mapping::get_or_use(account, receiver, 0u64);
        Mapping::set(account, receiver, receiver_amount + amount);
    }

    // === PRIVATE OPERATIONS ===

    // Mint tokens as a private record
    transition mint_private(
        receiver: address,
        amount: u64,
    ) -> Token {
        return Token {
            owner: receiver,
            amount: amount,
        };
    }

    // Transfer tokens between private records (UTXO model)
    transition transfer_private(
        sender_token: Token,       // consumed
        receiver: address,
        amount: u64,
    ) -> (Token, Token) {          // two new records created
        let change: u64 = sender_token.amount - amount;

        let to_receiver: Token = Token {
            owner: receiver,
            amount: amount,
        };

        let to_sender: Token = Token {
            owner: sender_token.owner,
            amount: change,
        };

        return (to_receiver, to_sender);
    }

    // === BRIDGE OPERATIONS (public <-> private) ===

    // Convert public balance to private record (shielding)
    async transition transfer_public_to_private(
        public receiver: address,
        public amount: u64,
    ) -> (Token, Future) {
        let new_record: Token = Token {
            owner: receiver,
            amount: amount,
        };

        let sender: address = self.caller;
        return (new_record, finalize_pub_to_priv(sender, amount));
    }

    async function finalize_pub_to_priv(sender: address, amount: u64) {
        let current: u64 = Mapping::get_or_use(account, sender, 0u64);
        assert(current >= amount);
        Mapping::set(account, sender, current - amount);
    }

    // Convert private record to public balance (unshielding)
    async transition transfer_private_to_public(
        sender_token: Token,        // consumed
        public receiver: address,
        public amount: u64,
    ) -> (Token, Future) {
        let change: u64 = sender_token.amount - amount;

        let change_record: Token = Token {
            owner: sender_token.owner,
            amount: change,
        };

        return (change_record, finalize_priv_to_pub(receiver, amount));
    }

    async function finalize_priv_to_pub(receiver: address, amount: u64) {
        let current: u64 = Mapping::get_or_use(account, receiver, 0u64);
        Mapping::set(account, receiver, current + amount);
    }
}

program tictactoe.aleo {
    @noupgrade
    async constructor() {}

    struct Board {
        r1: Row,
        r2: Row,
        r3: Row,
    }

    struct Row {
        c1: u8,
        c2: u8,
        c3: u8,
    }

    // Create a new empty board
    transition new() -> Board {
        return Board {
            r1: Row { c1: 0u8, c2: 0u8, c3: 0u8 },
            r2: Row { c1: 0u8, c2: 0u8, c3: 0u8 },
            r3: Row { c1: 0u8, c2: 0u8, c3: 0u8 },
        };
    }

    // Make a move: player 1 or 2, row 1-3, col 1-3
    transition make_move(
        board: Board,
        player: u8,
        row: u8,
        col: u8,
    ) -> Board {
        assert(player == 1u8 || player == 2u8);
        assert(row >= 1u8 && row <= 3u8);
        assert(col >= 1u8 && col <= 3u8);

        // Get current row
        let current_row: Row = row == 1u8 ? board.r1
            : (row == 2u8 ? board.r2 : board.r3);

        // Check cell is empty
        let current_val: u8 = col == 1u8 ? current_row.c1
            : (col == 2u8 ? current_row.c2 : current_row.c3);
        assert_eq(current_val, 0u8);

        // Set the cell
        let new_row: Row = Row {
            c1: col == 1u8 ? player : current_row.c1,
            c2: col == 2u8 ? player : current_row.c2,
            c3: col == 3u8 ? player : current_row.c3,
        };

        return Board {
            r1: row == 1u8 ? new_row : board.r1,
            r2: row == 2u8 ? new_row : board.r2,
            r3: row == 3u8 ? new_row : board.r3,
        };
    }
}