Docs / Protocol reference

Bond Registry

Stake is slashable seller capital, held per service in a single stake token per registry deployment (USDC on the first deployment). It is not per-call insurance: a service’s total payouts can never exceed its stake. The registry also stores every terms version and every signing key a service has ever had.

Service states

The registry sets the state during the slash, so suspension is automatic. The seller middleware issues offers only while Active, and the buyer SDK pays only Active services. Every change emits StateChanged { service_id, from, to }.

Functions

// seller
register_service(seller, signing_key, terms, min_stake) -> Result<service_id, Error>
update_terms(service_id, terms) -> Result<terms_hash, Error>      // not while Unbonding or Closed
rotate_key(service_id, signing_key) -> Result<key_version, Error> // not while Closed
deposit(service_id, amount) -> Result<(), Error>
request_unbond(service_id, amount) -> Result<(), Error>
cancel_unbond(service_id) -> Result<(), Error>
withdraw(service_id) -> Result<amount, Error>

// claims contract only
slash(service_id, buyer, amount) -> Result<paid, Error>

// anyone
collect_fee(service_id) -> Result<fee, Error>
extend_service_ttl(service_id) -> Result<(), Error>
extend_instance_ttl()
apply_claims_contract() -> Result<Address, Error>      apply_limits() -> Result<LaunchLimits, Error>      apply_fees() -> Result<FeeConfig, Error>

// reads
get_service(service_id) -> Result<Service, Error>       get_terms(service_id, terms_hash) -> Result<Terms, Error>
get_key(service_id, key_version) -> Result<SigningKey, Error>     terms_hash(terms) -> BytesN<32>
get_config() -> ProtocolConfig   get_token() -> Address   get_claims_contract() -> Option<Address>   get_pending_claims_contract() -> Option<PendingChange>
get_limits() -> LaunchLimits     get_pending_limits() -> Option<PendingLimits>     get_fees() -> FeeConfig     get_pending_fees() -> Option<PendingFees>
is_paused() -> bool              is_seller_allowed(seller) -> bool                 get_total_stake() -> i128

// admin
set_claims_contract(claims) -> Result<eta, Error>      cancel_claims_change()
set_validator lives on the Claims contract
set_limits(limits) -> Result<eta, Error>               cancel_limits_change()
set_fees(fees) -> Result<eta, Error>                   cancel_fees_change()
set_paused(paused)                                     set_seller_allowed(seller, allowed)

Every public function returns a typed result, so generated clients, apps and agents receive the named error code rather than an opaque host failure.

Rules per function

Error codes

Events

Protocol floors

Fixed at registry construction in ProtocolConfig. Values of the first deployment:

Safeguards

• Claim cap. One receipt pays at most max_claim, never more than the stake left, and never more than max_payout when a launch limit is set.
• Unbonding delay. max_claim_window_ever + unbond_margin, so every receipt issued before an exit can still be claimed, whatever terms version it was issued under. Terms cannot change while a service is Unbonding.
• Partial withdrawal. Stake above the minimum leaves through the same delay, and the service stays Active. The pending amount stays slashable until it is withdrawn.
• Automatic suspension. The registry sets Suspended during the slash or fee collection that takes stake below the minimum.
• Slash rate limit. Below.
• Time-locked administration. Below.

Slash rate limit

The contract never checks that a payment happened, so a seller could sign receipts for invented payments to addresses it controls and claim them, pulling stake out instantly and ahead of honest buyers. The rate limit removes the advantage: stake can leave through claims no faster than through a normal withdrawal.

epoch_len = max_claim_window + unbond_margin                 // same length as the unbonding delay
if epoch_base_stake == 0 or now >= epoch_start + epoch_len:  // start a new epoch
    epoch_start, epoch_base_stake, epoch_slashed = now, stake, 0
cap = epoch_base_stake * slash_epoch_cap_bps / 10000          // 50% of stake at epoch start
if epoch_slashed > 0 and epoch_slashed + payout > cap: fail EpochCapReached   // first slash of an epoch is always allowed
epoch_slashed += payout

The first slash of an epoch is always allowed (still bounded by max_claim and remaining stake), so a single honest claim is never blocked even when max_claim exceeds the cap. A claim refused by the cap fails with SlashRateLimited, records nothing, and can be retried in the next epoch if its window is still open. The trade-off: a genuine mass breach is paid out over more than one epoch.

Unbonding maths

unbonding_delay = max_claim_window_ever + unbond_margin
full_exit       = stake - amount < min_stake
pending         = full_exit ? stake : amount
unlock_at       = now + unbonding_delay
withdraw pays   = full_exit ? stake : min(pending, stake)      // slashes and fees reduce pending with the stake

Examples: a service whose largest claim window ever was 1 hour unbonds in 2 hours; one that once registered a 24-hour window unbonds in 25 hours, for the rest of its life. The admin time lock (26 hours) is longer than any possible unbonding delay by design.

Calculator

Protocol fees

Two fees in the stake token, paid to a treasury address, both of which may be zero:

fee = stake * stake_fee_bps_per_year * elapsed_seconds / (10000 * 31_536_000)   // integer division, capped at stake
// example: 200 USDC at 100 bps for 30 days -> 2_000_000_000 * 100 * 2_592_000 / 315_360_000_000 = 1_643_835 units = 0.1643835 USDC

The fee can take a service below its minimum, which suspends it like a slash would, so sellers should stake above the minimum. The first deployment runs a 1 USDC registration fee and 100 bps (1%) per year; proposed launch values on a production network are 10 USDC and 100 bps. Fee changes are time-locked.

Guarded launch: limits, pause, allowlist

The first deployment runs with no limits and no allowlist. A guarded production launch is expected to start with low caps and allowlist_only on, then loosen them through the time lock.

Time locks

The one way slashing rights can move is through the admin, and every such change is announced on-chain and delayed long enough for every seller to withdraw first. The first setting of each value applies immediately (initial wiring); every later change is a two-step proposal.

admin_delay = max_claim_window + 2 * unbond_margin = 86400 + 7200 = 93,600 s (26 h)   // registry
change_delay = 93,600 s                                                                 // Claims contract, set at construction

26 hours is longer than any service’s unbonding delay (at most 25 hours), so every seller can fully withdraw before a change takes effect. Contracts have no upgrade function. Sellers and monitors should watch for the *ChangeProposed events.

Storage lifetime

Services, terms versions, keys and claim records live in persistent storage. Every access extends their lifetime (threshold 30 days, extended to 60 days, counted in ledgers of about five seconds). extend_service_ttl(service_id) refreshes a service’s entries and extend_instance_ttl() the contract’s own; anyone may call them, and a keeper does so on a schedule. Long-idle services may need such a refresh.