# Master Ledger

The Master Ledger is the canonical source of truth for all Tortuga assets. It maintains the authoritative record of token ownership, regardless of which chain tokens are held on.

# Overview

flowchart TB
    subgraph Master Ledger
        REG[Token Registry]
        BAL[Balance Tracker]
        HIST[Transaction History]
        META[Bond Metadata]
    end

    KYC[KYC Registry] --> BAL
    CF[Chain Fusion] <--> BAL
    ISSUER[Issuer] --> REG
    ISSUER --> META
    YLD[Yield Distributor] --> BAL

# Responsibilities

Function	Description
Token Registry	Register new tokenized bonds with metadata
Balance Tracking	Canonical balances across all chains
Transfer Validation	Verify KYC and compliance before transfers
Cross-chain Sync	Coordinate with Chain Fusion for external chain state
Yield Snapshots	Provide holder snapshots for yield distribution

# Data Model

# Token

type Token = record {
    id : TokenId;
    isin : Text;
    name : Text;
    symbol : Text;
    decimals : nat8;
    total_supply : nat;
    bond_metadata : BondMetadata;
    created_at : Timestamp;
    status : TokenStatus;
};

type BondMetadata = record {
    issuer : Text;
    maturity_date : Timestamp;
    coupon_rate : nat;           // Basis points (e.g., 750 = 7.5%)
    coupon_frequency : CouponFrequency;
    collateral_type : Text;
    collateral_location : Text;
    prospectus_url : Text;
};

type TokenStatus = variant {
    Active;
    Matured;
    Suspended;
    Redeemed;
};

type CouponFrequency = variant {
    Annual;
    SemiAnnual;
    Quarterly;
    Monthly;
};

# Balance Entry

type BalanceEntry = record {
    owner : Principal;
    token_id : TokenId;
    balance : nat;
    chain : Chain;
    last_updated : Timestamp;
};

type Chain = variant {
    ICP;
    EVM : EvmChain;
    Solana;
    Cosmos : CosmosChain;
};

type EvmChain = variant {
    Ethereum;
    Base;
    Arbitrum;
    Polygon;
};

type CosmosChain = variant {
    Osmosis;
    CosmosHub;
};

# Transaction Record

type Transaction = record {
    id : TransactionId;
    token_id : TokenId;
    tx_type : TransactionType;
    from : opt Principal;
    to : opt Principal;
    amount : nat;
    chain : Chain;
    external_tx_hash : opt Text;
    timestamp : Timestamp;
    status : TransactionStatus;
};

type TransactionType = variant {
    Mint;
    Burn;
    Transfer;
    CrossChainMint;
    CrossChainBurn;
    YieldPayment;
};

type TransactionStatus = variant {
    Pending;
    Confirmed;
    Failed : Text;
};

# Canister Interface

# Token Management

candid
service : {
    // Register a new tokenized bond (issuer only)
    create_token : (CreateTokenArgs) -> (Result<TokenId, Error>);

    // Get token details
    get_token : (TokenId) -> (opt Token) query;

    // List all tokens
    list_tokens : () -> (vec Token) query;

    // Update token status (issuer only)
    update_token_status : (TokenId, TokenStatus) -> (Result<(), Error>);
}

# Balance Operations

candid
service : {
    // Get balance for a principal on specific chain
    balance_of : (Principal, TokenId, Chain) -> (nat) query;

    // Get total balance across all chains
    total_balance_of : (Principal, TokenId) -> (nat) query;

    // Get all holders of a token (for yield distribution)
    get_holders : (TokenId) -> (vec BalanceEntry) query;

    // Get holder snapshot at specific time (for yield calculation)
    get_holder_snapshot : (TokenId, Timestamp) -> (vec BalanceEntry) query;
}

# Transfer Operations

candid
service : {
    // Internal transfer (ICP chain only)
    transfer : (TransferArgs) -> (Result<TransactionId, Error>);

    // Request cross-chain mint (called by Chain Fusion)
    cross_chain_mint : (CrossChainMintArgs) -> (Result<TransactionId, Error>);

    // Request cross-chain burn (called by Chain Fusion)
    cross_chain_burn : (CrossChainBurnArgs) -> (Result<TransactionId, Error>);

    // Update balance after external chain confirmation
    confirm_cross_chain_tx : (TransactionId, Text) -> (Result<(), Error>);
}

# Query Operations

candid
service : {
    // Get transaction history for a principal
    get_transactions : (Principal, opt TokenId, Pagination) -> (vec Transaction) query;

    // Get specific transaction
    get_transaction : (TransactionId) -> (opt Transaction) query;

    // Get transaction by external chain hash
    get_transaction_by_hash : (Text) -> (opt Transaction) query;
}

# State Management

# Stable Storage

The Master Ledger uses stable memory for persistence across upgrades:

flowchart TB
    subgraph Stable Memory
        TOKENS[Token Registry]
        BALANCES[Balance Map]
        TXS[Transaction Log]
        INDEX[Indexes]
    end

    subgraph Indexes
        BY_OWNER[By Owner]
        BY_TOKEN[By Token]
        BY_CHAIN[By Chain]
        BY_TIME[By Timestamp]
    end

    INDEX --> BY_OWNER & BY_TOKEN & BY_CHAIN & BY_TIME

# Memory Layout

Region	Data	Estimated Size
Tokens	Token registry	~1KB per token
Balances	Owner→Token→Chain→Balance	~100 bytes per entry
Transactions	Append-only log	~200 bytes per tx
Indexes	B-tree indexes	~20% of data size

# Balance Synchronization

The Master Ledger maintains consistency with external chains through Chain Fusion:

sequenceDiagram
    participant EVM as EVM Chain
    participant CF as Chain Fusion
    participant ML as Master Ledger

    Note over EVM,ML: Mint Flow
    ML->>CF: Request Mint (user, amount, chain)
    CF->>EVM: Sign & Submit Mint TX
    EVM-->>CF: TX Confirmed
    CF->>ML: Confirm Mint (tx_hash)
    ML->>ML: Update Balance

    Note over EVM,ML: Burn Flow
    EVM->>CF: Burn Event Detected
    CF->>ML: Report Burn (user, amount)
    ML->>ML: Update Balance
    ML-->>CF: Acknowledged

# Consistency Guarantees

Scenario	Handling
External chain reorg	Wait for finality before confirming
Failed external TX	Rollback pending balance change
Duplicate events	Idempotent processing via TX ID
Network partition	Retry with exponential backoff

# Access Control

flowchart TB
    ISSUER[Issuer Principal] --> CREATE[Create Token]
    ISSUER --> UPDATE[Update Status]

    CF[Chain Fusion Canister] --> MINT[Cross-chain Mint]
    CF --> BURN[Cross-chain Burn]
    CF --> CONFIRM[Confirm TX]

    YIELD[Yield Distributor] --> SNAPSHOT[Get Snapshots]

    ANY[Any Principal] --> QUERY[Query Operations]
    VERIFIED[KYC Verified] --> TRANSFER[Transfer]

Role	Permissions
Issuer	Create tokens, update status, emergency pause
Chain Fusion	Cross-chain mint/burn, confirm transactions
Yield Distributor	Read holder snapshots
KYC Verified Users	Transfer tokens
Public	Read-only queries

# Error Handling

type Error = variant {
    NotAuthorized;
    TokenNotFound;
    InsufficientBalance;
    KycNotVerified : Principal;
    TransferRestricted : Text;
    InvalidAmount;
    TokenSuspended;
    TokenMatured;
    DuplicateTransaction;
    ChainNotSupported;
    InternalError : Text;
};