📜 Smart Contract Terms SOROBAN

2.1 Soroban Contract Structure

The contract is compiled from Rust to WebAssembly (WASM) and deployed on the Stellar Soroban runtime. All state is stored in Soroban persistent and temporary storage entries.

use soroban_sdk::{contract, contractimpl, Address, Env, Symbol};

// Contract entry point
#[contract]
pub struct SmartCardCoin;

#[contractimpl]
impl SmartCardCoin {
    /// Initialize card contract with issuer + fee config
    pub fn initialize(
        env: Env,
        issuer: Address,
        fee_bps: u32,       // basis points (e.g. 150 = 1.5%)
        card_tiers: Vec<CardTier>,
    ) -> Result<(), ContractError> { ... }

    /// Issue a new card to a user
    pub fn issue_card(
        env: Env,
        user: Address,
        tier: Symbol,
    ) -> Result<CardId, ContractError> { ... }

    /// Process a payment transaction
    pub fn process_payment(
        env: Env,
        from: Address,
        to: Address,
        amount: i128,
        asset: Address,
    ) -> Result<TxReceipt, ContractError> { ... }
}

2.2 Storage Model

The contract uses Soroban's three storage types:

• Persistent Storage — Card registrations, user balances, tier configurations (survives ledger expiry with rent payments)
• Temporary Storage — Transaction nonces, rate-limit counters (auto-expire)
• Instance Storage — Contract-level config: issuer address, fee schedule, version

2.3 Token Integration

The contract interacts with Stellar Asset Contract (SAC) tokens via the soroban_sdk::token::Client interface. Supported assets include XLM, USDC (Centre), and custom Soroban tokens meeting the SEP-41 token standard.

3.1 Public Functions

3.2 Authorization Model

All state-changing functions require Soroban's require_auth() from the invoking address. Multi-party operations (e.g., issue_card) require authorization from all involved parties within the same transaction envelope.

3.3 Error Codes

#[contracterror]
pub enum ContractError {
    NotInitialized     = 1,
    AlreadyInitialized = 2,
    Unauthorized       = 3,
    InsufficientFunds  = 4,
    CardNotFound       = 5,
    CardFrozen         = 6,
    InvalidTier        = 7,
    RateLimited        = 8,
    AmountOverflow     = 9,
    InvalidAsset       = 10,
}

4.1 Soroban Resource Fees

Every contract invocation consumes Soroban resources (CPU instructions, memory, storage reads/writes, transaction size). Fees are paid in XLM and are determined by the Stellar network's base fee + resource consumption.

4.2 Application-Level Fees

4.3 Storage Rent

Soroban persistent storage entries require periodic rent payments to prevent expiry. The contract auto-extends entry TTL (time-to-live) to a minimum of 120 days on each interaction. Users are responsible for ensuring sufficient XLM to cover rent bumps for their card data.

5.1 Smart Contract Risks

5.2 Audit & Verification

• Contract WASM hash is published and verifiable via stellar contract info
• Source code is open-source and reproducibly buildable with soroban contract build
• Independent security audit completed — report hash anchored on-chain
• Bug bounty program active for critical and high-severity findings

5.3 Emergency Procedures

The issuer multi-sig can invoke freeze_card on compromised accounts. A global circuit breaker (pause_contract) exists for critical vulnerabilities — requires 3-of-5 admin signatures and triggers a 48-hour cooldown before reactivation.

6.1 No Warranty

The smart contract is provided "AS IS" without warranty of any kind. The issuer makes no guarantees regarding uptime, transaction finality timing, or freedom from defects in the WASM bytecode.

6.2 Limitation of Liability

• The issuer is not liable for losses arising from Stellar network outages or consensus failures
• No liability for losses due to user key mismanagement or unauthorized access
• Maximum aggregate liability shall not exceed the user's total deposited balance
• The issuer is not liable for losses from sudden asset devaluation or market volatility

6.3 Immutability Notice

Once deployed, the contract's WASM bytecode is immutable unless upgraded via the issuer's admin function upgrade_contract. Upgrades require multi-sig approval and a 7-day timelock. Users are notified via on-chain events before any upgrade takes effect.

6.4 Regulatory Compliance

Users are solely responsible for compliance with applicable laws and regulations in their jurisdiction. This contract does not constitute a financial product, investment advice, or a regulated payment service. The issuer may restrict access from sanctioned jurisdictions.

7.1 Admin Multi-Sig

The contract issuer is a 3-of-5 multi-signature Stellar account. Critical operations (contract upgrade, fee changes, emergency pause) require threshold approval. Signer keys are distributed across geographically separate hardware security modules.

7.2 Upgrade Process

• Step 1: New WASM bytecode submitted and hash published
• Step 2: 7-day timelock initiated — on-chain event emitted
• Step 3: Community review period
• Step 4: Multi-sig approval (3-of-5)
• Step 5: upgrade_contract(new_wasm_hash) invoked
• Step 6: Post-upgrade verification & monitoring

7.3 Fee Adjustments

Application-level fee changes require multi-sig approval and a 14-day notice period. Fee changes are emitted as contract events. Maximum fee caps are hardcoded: transaction fee ≤ 3%, withdrawal fee ≤ 2%.

7.4 Dispute Resolution

Disputes arising from contract interactions shall first be resolved through the on-chain dispute mechanism (raise_dispute). If unresolved within 30 days, disputes may be escalated to binding arbitration under the rules of the jurisdiction specified by the issuer.