Skip to content

README.md

Latest commit

 

History

History
164 lines (118 loc) · 6.49 KB

README.md

File metadata and controls

164 lines (118 loc) · 6.49 KB

Callora Contracts

Soroban smart contracts for the Callora API marketplace: prepaid vault (USDC) and balance deduction for pay-per-call settlement.

CI Coverage

Tech stack

  • Rust with Soroban SDK (Stellar)
  • Contract compiles to WebAssembly and deploys to Stellar/Soroban
  • Minimal WASM size (~17.5KB for vault)

What’s included

1. callora-vault

The primary storage and metering contract.

  • init(owner, usdc_token, ..., authorized_caller, min_deposit, revenue_pool, max_deduct) — Initialize with owner and optional configuration.
  • deposit(caller, amount) — Owner or allowed depositor increases ledger balance.
  • deduct(caller, amount, request_id) — Decrease balance for an API call; routes funds to settlement.
  • batch_deduct(caller, items) — Atomically process multiple deductions.
  • set_allowed_depositor(caller, depositor) — Owner-only; delegate deposit rights.
  • set_authorized_caller(caller) — Owner-only; set the address permitted to trigger deductions.
  • get_price(api_id) — returns Option<i128> with the configured price per call for api_id.

Architecture & Flow

The following diagram illustrates the interaction between the backend, the user's vault, and the settlement contracts during an API call.

sequenceDiagram
    participant B as Backend/Metering
    participant V as CalloraVault
    participant S as Settlement/Pool
    participant D as Developer Wallet

    Note over B,V: Pricing Resolution
    B->>V: get_price(api_id)
    V-->>B: price

    Note over B,V: Metering & Deduction
    B->>V: deduct(caller, total_amount, request_id)
    V->>V: validate balance & auth
    
    Note over V,S: Fund Movement
    V->>S: USDC Transfer (via token contract)
    
    Note over S,D: Distribution
    S->>D: distribute(to, amount)
    D-->>S: Transaction Complete
Loading
  • get_meta() / balance() — View configuration and current ledger balance.
  • set_metadata / get_metadata — Attach off-chain metadata (IPFS/URI) to offerings.

2. callora-revenue-pool

A simple distribution contract for revenue.

  • init(admin, usdc_token) — Initialize with an admin and USDC token.
  • distribute(caller, to, amount) — Admin sends USDC from this contract to a developer.
  • batch_distribute(caller, payments) — Atomically distribute to multiple developers.
  • receive_payment(caller, amount, from_vault) — Log payment receipt for indexers.

3. callora-settlement

Advanced settlement with individual developer balance tracking.

  • init(admin, vault_address) — Link to the vault and set admin.
  • receive_payment(caller, amount, to_pool, developer) — Receive funds from vault; credit global pool or specific developer.
  • get_developer_balance(developer) — Check tracked balance for a specific developer.
  • get_global_pool() — View total accumulated pool balance.
  • set_vault(caller, new_vault) — Admin-only; update the linked vault address.

Local setup

  1. Prerequisites:

  2. Build and test:

    cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo build
cargo test

  3. Build WASM:

    # Build all publishable contract crates and verify their release WASM sizes
./scripts/check-wasm-size.sh

# Or build a specific contract manually
cargo build --target wasm32-unknown-unknown --release -p callora-vault

Development

Use one branch per issue or feature. Run cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, cargo test, and ./scripts/check-wasm-size.sh before pushing so every publishable contract stays within Soroban's WASM size limit.

Test coverage

The project enforces a minimum of 95% line coverage on every push via GitHub Actions.

# Run coverage locally
./scripts/coverage.sh

Project layout

callora-contracts/
├── .github/workflows/
│   ├── ci.yml              # CI: fmt, clippy, test, WASM build
│   └── coverage.yml        # CI: enforces 95% coverage on every push
├── contracts/
│   ├── vault/              # Primary storage and metering
│   ├── revenue_pool/       # Simple revenue distribution
│   └── settlement/         # Advanced balance tracking
├── scripts/
│   ├── coverage.sh         # Local coverage runner
│   └── check-wasm-size.sh  # WASM size verification
├── docs/
│   ├── interfaces/         # JSON contract interface summaries (vault, settlement, revenue_pool)
│   └── ACCESS_CONTROL.md   # Role-based access control overview
├── BENCHMARKS.md           # Gas/cost notes
├── EVENT_SCHEMA.md         # Event topics and payloads
├── UPGRADE.md              # Upgrade and migration path
├── SECURITY.md             # Security checklist
└── tarpaulin.toml          # cargo-tarpaulin configuration

Contract interface summaries

Machine-readable JSON summaries of every public function and parameter for each contract are maintained under docs/interfaces/. They serve as the canonical reference for backend integrators using @stellar/stellar-sdk.

File Contract
docs/interfaces/vault.json callora-vault
docs/interfaces/settlement.json callora-settlement
docs/interfaces/revenue_pool.json callora-revenue-pool

See docs/interfaces/README.md for the schema description and regeneration steps.

Security Notes

  • Checked arithmetic: All mutations use checked_add / checked_sub.
  • Input validation: Enforced amount > 0 for all deposits and deductions.
  • Overflow checks: Enabled in both dev and release profiles.
  • Role-Based Access: Documented in docs/ACCESS_CONTROL.md.

Security

See SECURITY.md for the Vault Security Checklist and audit recommendations.

Part of Callora.