┌──────────────────────────────────────────────────────────────┐
│                  CALLER'S MACHINE (off-chain)                │
│                                                              │
│  1. Caller invokes an entry point with private/public inputs │
│  2. The fn body executes locally                             │
│  3. Records are consumed (inputs) and created (outputs)      │
│  4. A zero-knowledge proof is generated                      │
│  5. Proof plus encrypted outputs go to the network           │
│                                                              │
│  Available: std::ctx::caller(), std::ctx::signer(),          │
│             record operations, all circuit computation       │
│  Not available: mappings, storage, block height, ChaCha      │
└────────────────────────────┬─────────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────────┐
│                    VALIDATORS (on-chain)                     │
│                                                              │
│  6. Validators verify the proof without re-executing it      │
│  7. If the entry point returns Final, validators run the     │
│     lifted final block to update public state                │
│  8. If the final block fails, the whole transaction is       │
│     rejected and the fee is still charged                    │
│                                                              │
│  Available: mapping get/set/remove/contains, storage vars    │
│             and vectors, std::ctx::block_height(),           │
│             std::ctx::block_timestamp(), ChaCha::rand_*,     │
│             snark.verify, snark.verify_batch                 │
│  Not available: private inputs, records                      │
└──────────────────────────────────────────────────────────────┘

// 1. Imports
import credits.aleo;

// 2. Global constants
const MAX_SUPPLY: u64 = 1000000u64;

// 3. Structs live outside the program block
struct TokenInfo {
    name: field,
    symbol: field,
    decimals: u8,
}

// 4. Helper functions live outside; they are inlined into callers
fn double(x: u64) -> u64 {
    return x * 2u64;
}

// 5. Reusable finalization logic lives outside
final fn credit_account(receiver: address, amount: u64) {
    let current: u64 = balances.get_or_use(receiver, 0u64);
    balances.set(receiver, current + amount);
}

program my_program.aleo {
    // 6. The constructor is mandatory and carries the upgrade policy
    @noupgrade
    constructor() {}

    // 7. Records are part of the public interface, so they stay inside
    record Token {
        owner: address,
        amount: u64,
        info: TokenInfo,
    }

    // 8. Public key-value state
    mapping balances: address => u64;

    // 9. Public singleton state
    storage supply: u64;

    // 10. Public dynamic list state
    storage holders: [address];

    // 11. Entry point with no on-chain effects
    fn mint_private(receiver: address, amount: u64) -> Token {
        return Token {
            owner: receiver,
            amount: double(amount),
            info: TokenInfo { name: 0field, symbol: 0field, decimals: 6u8 },
        };
    }

    // 12. Entry point with on-chain effects
    fn mint(public receiver: address, public amount: u64) -> Final {
        assert(amount <= MAX_SUPPLY);
        return final {
            credit_account(receiver, amount);
            supply = supply.unwrap_or(0u64) + amount;
        };
    }
}

let arr: [u32; 4] = [1u32, 2u32, 3u32, 4u32];
let element: u32 = arr[0u32];
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;
let no_val: u64? = none;

let val: u64 = some_val.unwrap();       // fails if none
let safe: u64 = no_val.unwrap_or(0u64); // never fails

let x: u32 = 42u32;
let y: u64 = x as u64;      // widening, safe
let z: field = x as field;   // integer to field, safe
let w: u8 = x as u8;         // narrowing, may truncate

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

// 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
    constructor() {}

    record Token {
        owner: address,   // mandatory
        amount: u64,
    }

    fn mint(receiver: address, amount: u64) -> Token {
        return Token { owner: receiver, amount: amount };
    }

    // Consumes one record, creates two
    fn send(sender_token: Token, receiver: address, amount: u64) -> (Token, Token) {
        let remaining: u64 = sender_token.amount - amount;

        let receiver_token: Token = Token { owner: receiver, amount: amount };
        let change_token: Token = Token { owner: sender_token.owner, amount: remaining };

        return (receiver_token, change_token);
    }
}

record Token {
    owner: address,          // always encrypted
    private amount: u64,     // encrypted, and the default
    public token_type: u8,   // visible on-chain in the transaction
}

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

    mapping counts: address => u64;

    fn increment(public amount: u64) -> Final {
        let caller: address = std::ctx::caller();
        return final {
            let current: u64 = counts.get_or_use(caller, 0u64);
            counts.set(caller, current + amount);
        };
    }
}

let balance: u64 = credits.aleo::account.get_or_use(addr, 0u64);

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

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

    fn initialize(public addr: address) -> Final {
        return final {
            admin = addr;
            paused = false;
            counter = 0u64;
        };
    }

    fn bump() -> Final {
        return final {
            let current: u64 = counter.unwrap_or(0u64);
            counter = current + 1u64;
            // counter = none;   // clears the value
        };
    }
}

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

    storage members: [address];

    fn register(public member: address) -> Final {
        return final {
            members.push(member);
        };
    }

    fn drop_last() -> Final {
        return final {
            members.pop();
        };
    }

    fn inspect(public index: u32) -> Final {
        return final {
            let count: u32 = members.len();
            assert(index < count);

            // get() returns an optional, so unwrap it
            let member: address = members.get(index).unwrap();
            members.set(index, member);
        };
    }
}

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

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

// Loop bounds must be compile-time constants
for i: u8 in 0u8..10u8 {
    // ...
}

// Leo 4.0 added inclusive bounds
for i: u32 in 0u32..=10u32 {
    // i runs 0 through 10
}

// Variable bounds are rejected:
// for i: u8 in 0u8..n { }   // compiler error

// Use a fixed bound with a guard instead
for i: u64 in 0u64..100u64 {
    if i < actual_count {
        // ...
    }
}

assert(condition);
assert_eq(a, b);
assert_neq(a, b);

fn double(x: u64) -> u64 {
    return x * 2u64;
}

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

    fn compute(public input: u64) -> u64 {
        return double(input);
    }
}

'add' is a reserved opcode.
Error [ECLI0377044]: failed to parse Aleo program `my_app`

const ADMIN: address = aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px;

program guarded.aleo {
    @noupgrade
    constructor() {}

    fn admin_only() {
        // Correct: checks the human who signed the transaction
        assert_eq(std::ctx::signer(), ADMIN);

        // Wrong for user auth: in a cross-program call this is the
        // intermediate program's address
        // assert_eq(std::ctx::caller(), ADMIN);
    }
}

let h: field = Poseidon2::hash_to_field(my_struct);
let a: address = BHP256::hash_to_address(my_data);

// Pedersen64 accepts inputs up to 64 bits
let small: field = Pedersen64::commit_to_field(value_u32, salt);
// BHP256 accepts larger inputs including fields and structs
let large: group = BHP256::commit_to_group(value_field, salt);

let ok: bool = signature::verify(sig, addr, message);
let also_ok: bool = sig.verify(addr, message);

program lottery.aleo {
    @noupgrade
    constructor() {}

    storage roll: u32;

    fn draw() -> Final {
        return final {
            roll = ChaCha::rand_u32();
            // Also: rand_bool, rand_field, rand_u8/16/64/128,
            // rand_i8/16/32/64/128, rand_scalar, rand_address
        };
    }
}

leo add credits.aleo --network         # deployed program
leo add my_lib.aleo --local ../my_lib  # local dependency
leo remove my_lib.aleo

import credits.aleo;

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

    mapping payments: field => u64;

    fn pay(public receiver: address, public amount: u64) -> Final {
        let payer: address = std::ctx::caller();
        let payment_id: field = BHP256::hash_to_field(payer);

        // A cross-program call to a stateful entry point returns a Final
        let transfer: Final = credits.aleo::transfer_public(receiver, amount);

        return final {
            // Run the callee's finalization before your own
            transfer.run();
            let total: u64 = payments.get_or_use(payment_id, 0u64);
            payments.set(payment_id, total + amount);
        };
    }
}

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

interface Counter {
    fn increment(amount: u64) -> u64;
}

program my_counter.aleo : Counter {
    @noupgrade
    constructor() {}

    fn increment(amount: u64) -> u64 {
        return amount + 1u64;
    }
}

interface Base {
    fn get_value() -> u64;
}

interface Extended : Base {
    fn set_value(v: u64) -> u64;
}

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

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

    // Public state
    mapping account: address => u64;

    // === Public operations ===

    fn mint_public(public receiver: address, public amount: u64) -> Final {
        return final {
            let current: u64 = account.get_or_use(receiver, 0u64);
            account.set(receiver, current + amount);
        };
    }

    fn transfer_public(public receiver: address, public amount: u64) -> Final {
        let sender: address = std::ctx::caller();
        return final {
            let sender_amount: u64 = account.get_or_use(sender, 0u64);
            assert(sender_amount >= amount);
            account.set(sender, sender_amount - amount);

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

    // === Private operations ===

    fn mint_private(receiver: address, amount: u64) -> Token {
        return Token { owner: receiver, amount: amount };
    }

    fn transfer_private(
        sender_token: Token,
        receiver: address,
        amount: u64,
    ) -> (Token, Token) {
        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);
    }

    // === Bridging public and private ===

    fn transfer_public_to_private(
        public receiver: address,
        public amount: u64,
    ) -> (Token, Final) {
        let new_record: Token = Token { owner: receiver, amount: amount };
        let sender: address = std::ctx::caller();

        return (new_record, final {
            let current: u64 = account.get_or_use(sender, 0u64);
            assert(current >= amount);
            account.set(sender, current - amount);
        });
    }

    fn transfer_private_to_public(
        sender_token: Token,
        public receiver: address,
        public amount: u64,
    ) -> (Token, Final) {
        let change: u64 = sender_token.amount - amount;
        let change_record: Token = Token { owner: sender_token.owner, amount: change };

        return (change_record, final {
            let current: u64 = account.get_or_use(receiver, 0u64);
            account.set(receiver, current + amount);
        });
    }
}

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

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

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

    fn start() -> 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 },
        };
    }

    fn 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);

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

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

        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,
        };
    }
}

[EPAR0370005] Error: expected '}', '@', 'record', 'struct', 'fn', 'final',
'const', 'mapping', 'storage', 'script', 'interface', found `transition`

// Before: `transition` was removed in Leo 4.0
transition mint(public receiver: address, public amount: u64) -> u64 {
    return amount;
}

// After
fn mint(public receiver: address, public amount: u64) -> u64 {
    return amount;
}

// Before: two functions, an explicit Future, and hand-threaded arguments
async transition mint(public receiver: address, public amount: u64) -> Future {
    return finalize_mint(receiver, amount);
}

async function finalize_mint(receiver: address, amount: u64) {
    balances.set(receiver, amount);
}

// After: one entry point; the `final` block closes over the arguments
fn mint(public receiver: address, public amount: u64) -> Final {
    return final {
        balances.set(receiver, amount);
    };
}

// Before: the body returns a Final, the signature promises nothing
fn mint(public receiver: address, public amount: u64) {
    return final { balances.set(receiver, amount); };
}

// After
fn mint(public receiver: address, public amount: u64) -> Final {
    return final { balances.set(receiver, amount); };
}

// Before: both are entry points, so the call is illegal
    fn double(x: u64) -> u64 {
        return x * 2u64;
    }

    fn mint(public amount: u64) -> u64 {
        return double(amount);
    }

// After: the helper moves above the block and is inlined into the caller
fn double(x: u64) -> u64 {
    return x * 2u64;
}

// Before
    constructor() {}

// After
    @noupgrade
    constructor() {}

// Before: @admin already states the policy, and the body repeats it
    @admin(address="aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px")
    constructor() {
        assert_eq(std::ctx::caller(), ADMIN);
    }

// After: the compiler inserts the check
    @admin(address="aleo1rhgdu77hgyqd3xjj8ucu3jj9r2krwz6mnzyd80gncr5fxcwlh5rsvzp9px")
    constructor() {}

// Before: @custom promises a policy that is not there
    @custom
    constructor() {}

// After: the body is the policy, and it reads on-chain state
    @custom
    constructor() {
        assert(upgrade_allowed.get_or_use(0u8, false));
    }

program upgradable.aleo {
    mapping upgrade_allowed: u8 => bool;

    @custom
    constructor() {
        assert(upgrade_allowed.get_or_use(0u8, false));
    }

    fn set_flag(public value: bool) -> Final {
        return final {
            upgrade_allowed.set(0u8, value);
        };
    }
}

// Before: a storage read is an option, not a value
        supply = supply + amount;

// After
        supply = supply.unwrap_or(0u64) + amount;

// Helpers and structs stay above the block
fn double(x: u64) -> u64 {
    return x * 2u64;
}

program token_fixed.aleo {
    @noupgrade
    constructor() {}

    mapping balances: address => u64;

    storage supply: u64;

    record Token {
        owner: address,
        amount: u64,
    }

    fn mint_private(receiver: address, amount: u64) -> Token {
        return Token { owner: receiver, amount: double(amount) };
    }

    fn mint_public(public receiver: address, public amount: u64) -> Final {
        return final {
            let current: u64 = balances.get_or_use(receiver, 0u64);
            balances.set(receiver, current + amount);
            supply = supply.unwrap_or(0u64) + amount;
        };
    }
}