Trust model
What each party has to trust, and what the contract guarantees.
Orbit is designed so that the trust each party needs is small and written down.
The most a merchant can ever take is min(allowance, balance). The allowance is set by the subscriber, expires at live_until_ledger, and can be set to zero at any time.
Within the allowance, Orbit allows at most one amount_per_interval pull per interval_seconds, measured by env.ledger().timestamp(). The caller cannot supply or influence the clock.
A successful pull_funds means the tokens are already in the merchant's wallet. There is no off-chain settlement step and no chargeback.
The contract has no admin, no pause switch, no fee and no upgrade key. The Merchant API is a convenience layer that submits transactions signed by the merchant. It never holds user funds.
Authorization boundaries
| Entrypoint | require_auth on | Who is protected |
|---|---|---|
create_vault | user | Nobody can set billing terms on a subscriber's behalf |
pull_funds | merchant | Only the merchant named in the vault key can pull |
batch_disburse | sender | Only the sender can spend their own allowance |
Guarantees
Non-custodial
Orbit is only the spender. The contract never holds a token balance.
Atomic
A failed transfer reverts the whole invocation, including any earlier batch transfers and the cadence update.
No double pull
last_pull_timestamp is written in the same invocation as the transfer.
Overflow-safe
Release builds use overflow-checks = true, so arithmetic aborts instead of wrapping.
Known limitations
The contract is an MVP and has not been audited.
create_vaultdoes not reject zero values.interval_seconds = 0lets the merchant pull at any time, still capped by the allowance.- Re-running
create_vaultresets the cadence, so the merchant can pull again immediately. Clients should warn the subscriber before they re-subscribe. - Events are only published on success. A failed pull leaves no Orbit event, so track failures from the transaction result.
- Errors are string panics, not typed error codes. See Contract errors.