Callora Contracts

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

Tech stack

• Rust with Soroban SDK (Stellar)
• Contract compiles to WebAssembly and deploys to Stellar/Soroban

What’s included

• callora-vault contract:
  • init(owner, initial_balance, min_deposit) — initialize vault for an owner; optional minimum deposit (0 = none)
  • get_meta() — owner, current balance, and min_deposit
  • deposit(amount) — increase balance (panics if amount < min_deposit)
  • deduct(caller, amount, request_id) — decrease balance (e.g. per API call)
  • batch_deduct(caller, items) — multiple deducts in one transaction (reverts entire batch if any would exceed balance)
  • withdraw(amount) — owner-only; decreases balance (USDC transfer when integrated)
  • withdraw_to(to, amount) — owner-only; withdraw to a designated address
  • balance() — current balance

Events are emitted for init, deposit, deduct, withdraw, and withdraw_to. See EVENT_SCHEMA.md for indexer/frontend use. Approximate gas/cost notes: BENCHMARKS.md. Upgrade and migration: UPGRADE.md.

Local setup

1. Prerequisites:

   • Rust (stable)
   • Stellar Soroban CLI (cargo install soroban-cli)

2. Build and test:

   cd callora-contracts
   cargo build
   cargo test

3. Build WASM (for deployment):

   cd contracts/vault
   cargo build --target wasm32-unknown-unknown --release

   Or use soroban contract build if you use the Soroban CLI workflow.

Development

Use one branch per issue or feature (e.g. test/minimum-deposit-rejected, docs/vault-gas-notes) to keep PRs small and reduce merge conflicts. Run cargo fmt, cargo clippy --all-targets --all-features -- -D warnings, and cargo test before pushing.

Project layout

callora-contracts/
├── .github/workflows/
│   └── ci.yml              # CI: fmt, clippy, test, WASM build
├── Cargo.toml              # Workspace and release profile
├── BENCHMARKS.md           # Vault operation gas/cost notes
├── EVENT_SCHEMA.md         # Event names, topics, and payload types
├── UPGRADE.md              # Vault upgrade and migration path
├── contracts/
│   └── vault/
│       ├── Cargo.toml
│       └── src/
│           ├── lib.rs      # Contract logic
│           └── test.rs     # Unit tests
└── README.md

Deployment

Use Soroban CLI or Stellar Laboratory to deploy the built WASM to testnet/mainnet and configure the vault (owner, optional initial balance). The backend will call deduct after metering API usage.

This repo is part of Callora. Frontend: callora-frontend. Backend: callora-backend.