API

The complete public interface of the five Soroban contracts that make up Agama on Stellar, taken from the deployed source rather than written alongside it. For the reasoning behind these entry points, which guard exists because of which failure, read Soroban Contracts. For the live addresses, read Deployments. The source is at github.com/agamafinance/agama-soroban.

How to read this page

Signatures are given as they appear in the contract, minus the leading e: Env that every Soroban function takes. The Stellar CLI takes each parameter as a named flag, so deposit(from: Address, amount: i128) is invoked as --from G... --amount 10000000.

Amounts are i128 at 7 decimals throughout, matching USDC on Stellar: 10000000 is one unit. Basis points are u32, where 10000 is 100%.

Caller is the address that must authorize the invocation, which is not always an address the function takes as a parameter. Where it says stored admin or stored Engine, the contract reads the address out of its own state and requires that one, so there is no argument to substitute. Where it says anyone, the function requires no authorization at all, and in each of those cases the caller chooses nothing: the arguments cannot redirect funds or select a beneficiary.

Errors are contract errors, returned rather than trapped, and each contract owns a numbered range. A call that fails returns Error(Contract, #NNN). The SEP-41 token functions are the exception: they trap with codes 1 to 4 from the shared token module rather than returning a typed error.

__constructor runs inside the transaction that deploys the contract and cannot be called again. It replaced a separate initialize entry point, which left a window between the deploy and the wiring in which anyone could send the same call naming themselves admin.

Vault

Custody, issuance and the withdrawal queue. It is the only contract that holds USDC. Errors are in the 300 range.

Capital in and out

The anti-dust minimum on request_withdrawal is 1 agUSD, or 10000000.

Allocation and the book

record_writedown and record_recovery are reached through the Allocation Engine's write_down and recover, which write the adapter's book and the Engine's in the same transaction.

Configuration

Views

oracle() -> Result<Address, VaultError> and oracle_feed() -> Result<Symbol, VaultError> read back the pair set_oracle writes. Every other counterparty this Vault points at could be read back and this one could not, so the only way to learn where it pointed was to call get_nav() and infer it from the number, and a wrong pointer produces a perfectly plausible number. The missing getter is what let the missing check go unnoticed.

Error codes

agUSD

The synthetic dollar the Vault mints, one for one against a deposit. A SEP-41 token that does nothing except keep balances and let exactly one address create them. Errors are in the 200 range.

SEP-41: balance(id), transfer(from, to, amount), transfer_from(spender, from, to, amount), approve(from, spender, amount, expiration_ledger), allowance(from, spender), burn(from, amount), burn_from(spender, from, amount), decimals(), name(), symbol(), total_supply().

burn and burn_from are the standard holder-authorized ones, because that is what Vault::request_withdrawal relies on. Supply therefore goes up only through the Vault and down only through the holder.

Error codes: 200 AlreadyInitialized (retired), 201 NotInitialized, 202 NotMinter (declared, never returned: a non-minter is stopped by the authorization check), 203 InvalidAmount, 204 NotAdmin, 205 MinterFrozen, 206 NoPendingAdmin, 207 NotPendingAdmin.

sagUSD

The staking contract. Yield reaches holders through share price appreciation rather than a moving redemption rate, which is what keeps agUSD usable as a unit of account. Errors are in the 800 range.

Views: nav() -> i128, total_shares() -> i128, exchange_rate() -> i128 (agUSD per share at 7 decimals), share_price() -> i128 (an alias kept because the first generation agUSD calls it), pending(addr) -> Pending with fields assets and claimable_at, cooldown() -> u64, allocations() -> Vec<Allocation>, stakes() -> u64, agusd() -> Address, admin() -> Address, pending_admin() -> Option<Address>.

SEP-41: balance, transfer, transfer_from, approve, allowance, decimals, name, symbol, total_supply. There is deliberately no burn: shares leave supply only through request_unstake.

Error codes: 800 AlreadyInitialized (retired), 801 NotInitialized, 802 NotAdmin, 803 CustodyTaken, 804 NoPendingAdmin, 805 NotPendingAdmin, 806 InvalidAmount, 807 ZeroShares, 808 NoSupply, 809 NothingPending, 810 StillInCooldown, 811 DecimalMismatch.

ZeroShares is worth naming separately from InvalidAmount: it is a stake large enough to be a positive number of assets and small enough to round to no shares at all, and taking it would be taking a deposit and giving nothing back for it.

Events: staked(staker, assets, shares, nav, supply) · unstake_requested(staker, shares, assets, claimable_at, nav, supply) · unstake_claimed(staker, assets) · yield_distributed(amount, nav, supply) · agusd_repointed(agusd) · admin_proposed(new_admin) · admin_changed(admin). The first four carry nav and supply as they stand after the call, because the share price is nav / supply and an indexer replaying the stream has no way back to a past pair: carrying both makes every price in a history a fact from the ledger rather than a sample somebody happened to take. unstake_claimed carries neither, on purpose, because the shares were burned at request time and nothing about the price moves at a payout.

Allocation Engine

The constraint layer. It decides nothing about where capital goes, which in V1 is an admin decision; what it does is refuse. Errors are in the 400 range.

Views

Error codes

Pool adapters

Every adapter implements the same interface, which is what lets the Engine route to an off-chain credit facility and to a tokenized bond through identical code. allocate, deallocate and write_down are callable only by the stored Engine; recover_surplus by the Engine or the adapter's admin, and it sends to the adapter's stored Vault rather than anywhere the caller names.

allocate(amount: i128), deallocate(amount: i128), write_down(amount: i128), recover_surplus(caller: Address) -> i128, get_exposure() -> i128, engine() -> Address, vault() -> Address, admin() -> Address, pool_kind() -> Symbol, oracle_feed() -> Symbol, set_counterparties(admin, engine, vault), propose_admin, accept_admin, pending_admin.

The settlement figure is the one place the two adapters differ, and they differ because the instruments do. Private credit publishes settlement_window() -> (u32, u32), a range of 15 to 90 days; Etherfuse publishes settlement_days() -> u32, which is zero, because a Stablebond redemption is on-chain and returns in the same call. Nothing on-chain enforces either. They are published so that the Engine's operators and the withdrawal queue can be sized against the real cash conversion time of the book.

Error ranges: 600 for the private credit adapter, 700 for Etherfuse, with matching variants. NotEmpty 605 and 705 is the refusal to repoint an adapter that is still holding something; NothingToRecover 611 and 711 is recover_surplus finding no surplus.

Oracle Adapter

NAV reporting, with the guards on the way in rather than on the way out. Errors are in the 500 range.

The minimum interval is measured on recorded_at, which is ledger time, and never on the timestamp the reporter supplies, because the reporter chooses that one.

Error codes

Calling a contract

Read-only, simulated and never submitted:

stellar contract invoke --id CONTRACT --source KEY --network testnet --send=no \
  -- free_reserves

State changing, submitted, returning a transaction hash:

stellar contract invoke --id CONTRACT --source KEY --network testnet \
  -- deposit --from GADDRESS --amount 10000000

The full interface of any deployed contract, including types, is on the ledger:

stellar contract info interface --id CONTRACT --network testnet

A refusal is contract logic and shows up identically in simulation, so simulating is enough to confirm an entry point rejects what it should. Authorization is not: simulation records the authorizations a call would need rather than enforcing them, so anything that turns on who signed has to be checked with a submitted transaction signed by the key under test.