### Build Aleo Program

Source: https://github.com/izar-bridge/aleo-contracts/blob/master/README.md

This command compiles the Aleo program. Ensure you have the Leo development environment set up before executing this command.

```bash
leo build
```

--------------------------------

### Protocol Upgrade Mechanism (Leo)

Source: https://context7.com/izar-bridge/aleo-contracts/llms.txt

The `upgrade` transition enables seamless contract upgrades by transferring token ownership to a new proxy contract. This facilitates protocol improvements without disrupting existing token balances or requiring user migrations. The caller must be the proxy owner to execute this transition.

```leo
transition upgrade(public new_contract: address) {
    assert_eq(self.caller, proxy_owner());
    izar_token.aleo/transfer_ownership(new_contract);
}
```

--------------------------------

### Receive Tokens from External Chains (Leo)

Source: https://context7.com/izar-bridge/aleo-contracts/llms.txt

The `receive_payload` transition handles incoming cross-chain token transfers. It validates signatures, verifies token metadata against the protocol, and mints tokens to the recipient's public balance on Aleo. This is the primary entry point for assets moving from external chains to Aleo.

```leo
struct IzarRecvMsg {
    protocol_addr: address,
    nonce: u128,
    to_addr: address,
    from_chain_id: u32,
    from_asset_addr: field,
    token_id: field,
    amount: u128,
}

transition receive_payload(signatures: [signature; 20], keepers: [address; 20], payload: IzarRecvMsg) {
    // Verify token registration matches payload
    izar_token.aleo/verify_token(payload.token_id, payload.from_chain_id, payload.from_asset_addr);

    // Verify keeper signatures (2/3+1 threshold)
    izar_protocol_v1.aleo/verify(signatures, keepers, payload);

    // Mint tokens to recipient's public balance
    izar_token.aleo/mint_public(payload.to_addr, payload.amount, payload.token_id);
}
```

--------------------------------

### Mint Private Tokens

Source: https://context7.com/izar-bridge/aleo-contracts/llms.txt

Creates a private token record for a given receiver, amount, and token ID. This function returns an `IzarToken` record representing the newly minted private balance. The minting operation itself is finalized by the caller.

```leo
record IzarToken {
    owner: address,
    amount: u128,
    token_id: field,
}

// Mint tokens to private record
transition mint_private(receiver: address, amount: u128, token_id: field) -> IzarToken {
    return IzarToken {
        owner: receiver,
        amount: amount,
        token_id: token_id,
    } then finalize(self.caller, token_id);
}
```

--------------------------------

### Register Multi-Token with Chain and Asset Data

Source: https://context7.com/izar-bridge/aleo-contracts/llms.txt

Implements ERC-1155-style multi-token registration, where each token is uniquely identified by a token ID derived from its chain ID and source asset address. Registration is restricted to the contract owner. It ensures that each token is uniquely identified before being added to the token metadata mapping.

```leo
struct IzarTokenMeta {
    from_chain_id: u32,         // Source blockchain ID
    from_asset_addr: field,     // Source token contract address as field
}

transition regist_token(metadata: IzarTokenMeta) {
    return then finalize(metadata, self.caller);
}

finalize regist_token(metadata: IzarTokenMeta, caller: address) {
    let is_initialized: bool = Mapping::get_or_use(initialed, true, false);
    assert(is_initialized);

    let current_owner: address = Mapping::get(contract_owner, true);
    assert_eq(current_owner, caller);

    // Token ID derived from metadata hash
    let token_id: field = BHP256::hash_to_field(metadata);

    // Ensure token doesn't already exist
    assert(!Mapping::contains(token_meta, token_id));

    Mapping::set(token_meta, token_id, metadata);
}

// Example: Register USDC from Ethereum
// metadata = IzarTokenMeta {
//     from_chain_id: 1u32, // Ethereum mainnet
//     from_asset_addr: 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48field, // USDC address
// }
// Resulting token_id: bhp256(metadata) = unique_field_value
```

--------------------------------

### Send Tokens to External Chains (Leo)

Source: https://context7.com/izar-bridge/aleo-contracts/llms.txt

The `cross_public` transition manages outgoing cross-chain token transfers. It burns the user's tokens on Aleo, collects fees, and triggers off-chain relayers to unlock equivalent assets on the destination chain. Token verification ensures only registered cross-chain assets can be bridged.

```leo
struct IzarCrossMsg {
    to_chain_id: u32,           // Destination chain (e.g., 1 for Ethereum)
    to_addr: field,             // Recipient address on destination chain
    to_asset_addr: field,       // Asset address on destination chain
    token_id: field,            // Token being transferred
    amount: u128,               // Amount to transfer
    fee: u128,                  // Bridge fee in token units
}

transition cross_public(public payload: IzarCrossMsg) {
    // Verify token is valid for target chain
    izar_token.aleo/verify_token(payload.token_id, payload.to_chain_id, payload.to_asset_addr);

    // Burn user's tokens (reverts if insufficient balance)
    izar_token.aleo/burn_public(self.caller, payload.amount, payload.token_id);

    // Collect fee by minting to protocol owner
    izar_token.aleo/mint_public(proxy_owner(), payload.fee, payload.token_id);
}
```

--------------------------------

### Transfer Private Tokens

Source: https://context7.com/izar-bridge/aleo-contracts/llms.txt

Enables the transfer of tokens held in private records. This function takes a private `IzarToken` record, the recipient's address, and the amount to transfer. It splits the original record into a remaining part and a new record for the transferred amount, returning both.

```leo
record IzarToken {
    owner: address,
    amount: u128,
    token_id: field,
}

// Transfer private records
transition transfer_private(token: IzarToken, receiver: address, amount: u128) -> (IzarToken, IzarToken) {
    let difference: u128 = token.amount - amount;

    let remaining: IzarToken = IzarToken {
        owner: token.owner,
        amount: difference,
        token_id: token.token_id,
    };

    let transferred: IzarToken = IzarToken {
        owner: receiver,
        amount: amount,
        token_id: token.token_id,
    };

    return (remaining, transferred);
}

// Example: Transfer 100 tokens from private to public balance
// transfer_private_to_public(private_token_record, aleo1receiver..., 100000000u128)
```

--------------------------------

### Verify Cross-Chain Message - Leo

Source: https://context7.com/izar-bridge/aleo-contracts/llms.txt

Verifies incoming cross-chain messages by validating keeper signatures and checking nonce uniqueness to prevent replay attacks. It ensures that a sufficient number of keepers (2/3+1 threshold) have signed the payload and that the message is directed to the correct protocol contract. Replay attacks are prevented by checking against a stored list of processed nonces.

```leo
struct IzarRecvMsg {
    protocol_addr: address,     // Target protocol contract
    nonce: u128,                // Unique transaction identifier
    to_addr: address,           // Recipient on Aleo
    from_chain_id: u32,         // Source chain identifier (e.g., 1 for Ethereum)
    from_asset_addr: field,     // Source token contract address
    token_id: field,            // Token identifier (hash of metadata)
    amount: u128,               // Amount to transfer
}

transition verify(signatures: [signature; 20], keepers: [address; 20], payload: IzarRecvMsg) {
    assert_eq(payload.protocol_addr, protocol_contract());
    let (result, accepted): (scalar, u32) = verify_sigs(keepers, signatures, payload);
    let nonce: Nonce = Nonce {
        chain_id: payload.from_chain_id,
        nonce: payload.nonce,
    };

    return then finalize(nonce, result, accepted);
}

finalize verify(nonce: Nonce, keeper_digest: scalar, accepted: u32) {
    // Prevent replay attacks
    assert(!Mapping::get_or_use(nonces, nonce, false));

    // Validate keeper set and signature threshold
    assert(keeper_digest == Mapping::get(izar_digest, true));
    let num: u32 = Mapping::get(izar_config, 1u8);
    assert(accepted >= num - (num - 1u32) / 3u32); // 2/3+1 threshold

    Mapping::set(nonces, nonce, true);
}

// Example: Receiving 1000 tokens from Ethereum
// payload = IzarRecvMsg {
//     protocol_addr: aleo1e5szs84jql2hn08ffxc7yn97wa8s9vk7jgshcddxmaekdxh85upsdt8p9g,
//     nonce: 12345u128,
//     to_addr: aleo1user123...,
//     from_chain_id: 1u32, // Ethereum mainnet
//     from_asset_addr: 0x1234567890abcdef..., // USDC on Ethereum
//     token_id: bhp256_hash(metadata),
//     amount: 1000000000u128, // 1000 USDC (6 decimals)
// }
```

--------------------------------

### Mint Public Tokens

Source: https://context7.com/izar-bridge/aleo-contracts/llms.txt

Mints tokens to a public (transparent) balance. This function requires the receiver's address, the amount to mint, and the token ID. It first checks if the token ID is valid and then updates the public account balance. The operation is restricted to the contract owner.

```leo
record IzarToken {
    owner: address,
    amount: u128,
    token_id: field,
}

struct Account {
    holder: address,
    token_id: field,
}

// Mint tokens to public balance
transition mint_public(public receiver: address, public amount: u128, public token_id: field) {
    let account: Account = Account {
        holder: receiver,
        token_id: token_id,
    };
    return then finalize(account, amount, self.caller);
}

finalize mint_public(public receiver: Account, public amount: u128, public caller: address) {
    let current_owner: address = Mapping::get(contract_owner, true);
    assert_eq(current_owner, caller);

    assert(Mapping::contains(token_meta, receiver.token_id));

    let current_amount: u128 = Mapping::get_or_use(accounts, receiver, 0u128);
    Mapping::set(accounts, receiver, current_amount + amount);
}

// Example: Mint 5000 tokens publicly
// mint_public(aleo1user123..., 5000000000u128, usdc_token_id)
```

--------------------------------

### Update Keeper Set - Leo

Source: https://context7.com/izar-bridge/aleo-contracts/llms.txt

Updates the keeper set for multisig verification in the IZAR protocol. It requires owner access and uses a digest-based validation to ensure the integrity of the keeper set. The function defines a dynamic keeper set with configurable thresholds for transaction approval.

```leo
transition update_keeper(keepers: [address; 20]) {
    assert_eq(self.caller, protocol_owner());
    let digest: scalar = Poseidon8::hash_to_scalar(keepers);
    return then finalize(keepers, digest);
}

finalize update_keeper(keepers: [address; 20], digest: scalar) {
    let accepted: u32 = 0u32;

    // Count valid keepers (non-zero addresses)
    for i: u8 in 0u8..20u8 {
        if keepers[i] != invalid_validator() {
            accepted += 1u32;
        }
    }

    Mapping::set(izar_keeper, true, keepers);
    Mapping::set(izar_config, 1u8, accepted);
    Mapping::set(izar_digest, true, digest);
}

// Example keeper array with 5 active validators
// [validator1_addr, validator2_addr, validator3_addr, validator4_addr, validator5_addr,
//  aleo1qqqqq..., aleo1qqqqq..., ...] // remaining 15 slots are zero addresses
```

--------------------------------

### Transfer Public Tokens

Source: https://context7.com/izar-bridge/aleo-contracts/llms.txt

Facilitates the transfer of tokens between public accounts. It requires the sender's account, the receiver's account, and the amount to transfer. The function updates the balances of both the sender and receiver in the public accounts mapping. This operation is restricted to the contract owner.

```leo
struct Account {
    holder: address,
    token_id: field,
}

// Transfer between public accounts
transition transfer_public(public receiver: address, public amount: u128, public token_id: field) {
    let sender_account: Account = Account {
        holder: self.caller,
        token_id: token_id,
    };
    let receiver_account: Account = Account {
        holder: receiver,
        token_id: token_id,
    };
    return then finalize(sender_account, receiver_account, amount);
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.