Skip to main content

​
How to Test

The repository includes a comprehensive Rust test suite. From the root of the contracts workspace:
This will run the current Soroban workspace tests, validating protection math, reserve accounting, username registration and lookup, receipt anchoring, payment locks, floor shields, oracle behavior, and proof-status records. The latest full local verification ran:
The latest local result was 46 unit tests passing plus doctests. A full workspace run may require Windows Application Control to allow generated Rust test binaries on some machines.

​
Current Testnet Deployment

The current XLM-only Testnet IDs are published in /contracts.json and the associated deployment report. Mainnet is not deployed. The current workspace contains these contracts:
  • protection_engine
  • reserve_vault
  • protected_balance_vault
  • oracle_adapter
  • quorum_oracle_source
  • username_registry
  • receipt_registry
  • zk_verifier
  • payment_lock_engine
  • floor_shield_engine
The initial Mainnet scope should stay limited to audited, launch-critical contracts. Experimental surfaces such as floor shield, payment lock, or proof-status flows should be promoted only after tests, docs, monitoring, and audit scope are ready.
Historical instructions later in this document reference the former CFTUSD, six-contract Testnet deployment. Do not use those values or commands for the current XLM deployment or Mainnet. Use /contracts.json, this page, and any current deployment runbook in coverfi-contracts.
If the app shows Protect as unavailable on Testnet, verify the configured IDs before changing frontend quote logic or position amounts:
The expected failure mode for the old public Testnet IDs is:
  • engine.quote_position fails with MissingValue, meaning the deployed engine does not expose the V2 quote ABI.
  • reserve.get_pool, reserve.get_projected_utilization_bps, and reserve.get_projected_concentration_bps fail with MissingValue, meaning the deployed reserve does not expose the V2 reserve ABI.
  • engine.create_position fails before wallet signing, so this is not a user wallet, amount, Freighter, or frontend bug.
When this happens, /api/status/reserve should return ok: false with status: "legacy_mismatch" instead of HTTP 502. The only protocol fix is a fresh V2 deploy, initialization, reserve funding, and smoke test. Do not promote a contract ID from a legacy or experimental section into the active Testnet section until the deployment workflow has:
  • built and hashed every required WASM,
  • deployed and initialized the contracts,
  • configured engine, vault, oracle, asset, partner, proof-status, and keeper references where relevant,
  • seeded the selected Testnet reserve and automation balances,
  • executed smoke lifecycles for username payment, receipt anchoring, quote, protection creation, settlement, payout claim, and withdrawal,
  • written a deployment report with transaction IDs and WASM hashes.
Recorded settings:
  • XLM reserve seed: re-check live state after each redeploy before publishing a demo script.
  • Oracle price: 100000000.
  • Source protection engine fee logic: duration-based schedule (30, 100, 150, 250 bps for 1, 7, 14, and 30 day terms). Verify or redeploy the listed contract IDs before treating a deployment as enforcing the latest source.
  • Max payout: 1000 bps.
  • Max oracle age: 3600 seconds.
  • Reserve accounting: position-specific maximum payout locks, reserved claims, matured underwriting premium, safety balance, automation balance, provider shares, and withdrawal requests.

​
How to Deploy

​
Repairing the Current Testnet Protect Flow

The current legacy Testnet IDs cannot be made V2-compatible by changing .env labels or lowering the protected amount. The engine and reserve must be redeployed together because they store each other’s contract IDs and the current public reserve does not expose the methods used by the V2 UI. Required local inputs: Build from a trusted/developer path or CI runner:
On some Windows machines, Application Control may block generated Rust build scripts with os error 4551. That is a host policy block. Move the repo to a developer-trusted path, allow generated build artifacts, or build in CI/WSL. Deploy the launch-critical WASMs with Stellar CLI. Add optional product contracts only when they are in scope for the deployment:
Initialize in this order:
  1. reserve_vault.initialize(admin, treasury).
  2. oracle_adapter.initialize(admin, source, source_asset, source_decimals, max_age_seconds, max_deviation_bps).
  3. oracle_adapter.configure_publishers(admin, publisher1, publisher2, publisher3, true) if using fallback publisher quorum.
  4. protected_balance_vault.initialize(admin, protection_engine).
  5. protection_engine.initialize(admin, protected_balance_vault, reserve_vault, oracle_adapter, protected_asset, payout_asset, 1000, 3600).
  6. reserve_vault.configure_protocol(admin, protection_engine, oracle_adapter).
  7. Initialize username_registry, receipt_registry, and zk_verifier with their current source-defined arguments.
  8. Initialize and configure quorum_oracle_source if it is part of the deployment.
  9. Fund the payout reserve with reserve_vault.deposit_reserve(provider, payout_asset, amount, min_shares).
  10. Fund automation with reserve_vault.fund_automation(provider, payout_asset, amount).
  11. Publish a fresh oracle observation for the protected XLM asset.
After deployment, update contracts.json, run node scripts/sync-contract-registry.js --write, copy the new active IDs into the frontend/backend env, restart both apps, and run:
Only publish the active Testnet IDs after diagnostics pass and end-to-end smoke tests cover username payment, receipt anchoring, quote, protection creation, settlement, payout claim, and principal withdrawal.

​
Production admin account policy

Do not use a personal Freighter wallet, demo wallet, backend hot wallet, or reserve funder wallet as the production admin. Recommended account split: For testnet, a single dedicated testnet admin is acceptable for speed. For mainnet, set the admin public key only after the team has chosen the multisig/admin-controller policy and documented signer custody. Publish the admin public key, deployment source, and contract IDs in the deployment record after verification. To deploy the contracts to the Stellar network, clone the coverfi-contracts repository and use the Stellar CLI.
  1. Build the WASM contracts:
  1. Deploy to Testnet:
Repeat the deployment step for the launch-critical workspace contracts, then configure their cross-contract initialization. If the reserve vault or engine ABI changes, redeploy the whole protection suite because the engine and vaults store each other’s contract IDs.

​
Security Notes

[!WARNING]
Audit Status: These contracts are currently in beta and have not undergone a formal security audit. Use at your own risk.
  • Oracle Dependency: The engine rejects stale oracle data, but the system still relies on updater quality and monitoring.
  • Reserve Payouts: Claims use position-specific reserved payout accounting. The owner can claim the settled amount once, and withdrawals cannot consume active collateral or restricted balances.
  • Deployment Drift: Source changes do not affect existing contract IDs until rebuilt, redeployed, initialized, and verified.
  • Reentrancy: State changes occur before external cross-contract token transfers to prevent reentrancy attacks.
  • Access Control: Critical functions like price updates and contract upgrades must be protected by admin authentication, preferably multisig in production.