Skip to content

Latest commit

 

History

History
648 lines (546 loc) · 77.2 KB

kit-spec.md

File metadata and controls

648 lines (546 loc) · 77.2 KB

Strata Vault Kit Specification

This document is the authoritative kit reference for the Strata Vault Protocol. It provides a third party with everything needed to configure, deploy, and verify an instance without inspecting contract source code.

It covers:

  1. Core Invariants & Testable Properties
  2. Deploy-Time Parameters & Runtime Configuration
  3. Role & Authority Matrix (Privileges & Anti-Capabilities)

1. Protocol Invariants & Testable Properties

The contracts enforce a set of mathematical and state-machine invariants across all operations. Each invariant is stated below as a formal, testable property matching the on-chain test suite.

Invariant 1: Escrow Stays, Only Free Reserve Moves

  • Definition: Cancellable subscription escrow never leaves the vault, and only the free reserve can move to the custodian. Priced redemption liabilities (committed) may exceed the liquid reserve; the shortfall is reported as uncovered, not refused. Here $\text{held}$ is the vault's balance of the settlement asset.

  • Mathematical Statement: $\text{liquid\_reserve} = \text{held} - \text{cancellable\_escrow}$

    $\text{free\_reserve} = \max(\text{liquid\_reserve} - \text{committed} - \text{wind\_down\_owed}, 0)$

    $\text{uncovered} = \max(\text{committed} - \text{liquid\_reserve}, 0)$

  • Testable Property: deploy_to_custodian(assets) is refused with ReserveCommittedToExits when $\text{assets} > \text{free\_reserve}$, so after every operation $\text{held} \ge \text{cancellable\_escrow}$, unless the asset's issuer takes from the vault's balance. While $\text{uncovered} > 0$, the free reserve is zero and nothing leaves for the custodian.

  • Enforcement: deploy_to_custodian is the only outbound path to the custodian, and it moves at most the free reserve.

  • When the vault holds less than it owes: the asset's issuer can claw back part of the vault's balance. The kit cannot stop that. The vault then pays in this order and refuses the rest by name until it is funded:

    1. Escrow a depositor can still cancel is paid first. cancel_deposit pays from the vault's whole balance when that balance covers the deposit's own amount, in any order; otherwise EscrowNotCovered. While $\text{held} < \text{cancellable\_escrow}$, request_deposit is refused with EscrowNotCovered, so a new deposit never pays an earlier cancellation.
    2. Priced redemption claims come next. Each pays when the liquid reserve covers its own amount, in any order; otherwise ClaimNotCovered.
    3. What wind-down rounds owe sits beside priced claims in the free reserve. A wind-down claim's own gap is described in THREAT_MODEL X8.
    4. A refund of a deposit below one share and a transfer to the custodian come last, only from the free reserve (ClaimNotCovered, ReserveCommittedToExits).
    5. uncovered() shows the gap, $\text{committed} + \text{cancellable\_escrow} - \text{held}$ when positive. Funding that gap with fund lifts the refusals for cancellations, priced claims and new deposits. A refund of a deposit below one share and a transfer to the custodian also need free reserve, which uncovered() does not show.
    6. The vault does not decide who finally bears the loss. Until treasury funds the gap, whoever acts first within a class is paid first. Pricing does not read the balance: an epoch priced during the gap mints its deposits in full, and the loss reaches holders through the NAV.
    7. A freeze of the vault's balance, unlike a clawback, leaves the balance readable. The vault's checks pass, and the asset refuses the transfer with its own error.

Invariant 2: Notice Period Respected

  • Definition: An epoch cannot be fulfilled or priced until its standing notice period has fully elapsed.

  • Mathematical Statement: $\text{priceable\_at} = \text{closed\_at} + \text{notice}$

    $\text{fulfill\_epoch}(\text{epoch}) \implies \text{ledger.timestamp} \ge \text{priceable\_at}$

  • Testable Property: Invocations of fulfill_epoch before priceable_at are rejected with NoticeNotElapsed. Changing the notice period via set_notice applies only to future epochs and never shortens the notice of an already closed epoch.

Invariant 3: Post-Close Valuation Timing

  • Definition: An epoch is never priced against a valuation accepted before that epoch closed.
  • Mathematical Statement: $\text{attested\_at} \ge \text{closed\_at}$
  • Testable Property: If the latest oracle attestation timestamp precedes closed_at, fulfill_epoch is rejected with AttestationBeforeClose. A valuation accepted in the exact closing ledger timestamp or later is accepted. attested_at is the ledger time the oracle accepted the report, stored as accepted_at, not a valuation date: the attester submits no time of its own. So "accepted before the close" compares acceptance time. The reporter's expires_at can only shorten a report's life: the oracle stores min(expires_at, attested_at + freshness_duration).

Invariant 4: Covered Claims Always Pay (Exit Guarantee)

  • Definition: Once an exit is priced and covered by the liquid reserve, its cash payout cannot be blocked by an administrative pause, oracle staleness, or an investor's compliance delisting.
  • Testable Property: If liquid_reserve >= assets_owed, claim_redeem succeeds when:
    1. The vault is paused (paused == true).
    2. The oracle feed has expired (is_stale == true) or the NAV is paused.
    3. The caller has been de-listed in the IdentityVerifier, unless the claim pays zero assets outside a wind-down (see below). Priced claims are never re-priced, and a cash payout never needs the identity check. A frozen investor's covered claim is held until the freeze is lifted (VaultError::Frozen); the cash stays in committed. One priced claim pays no cash: a redemption priced at zero assets gives its escrowed shares back, so the holder must be able to receive them. Outside a wind-down, a delisted holder's such claim is refused with HolderNotEligible and the request stays until the holder is listed again; in a wind-down the claim burns the shares instead (a_delisted_holders_redemption_that_pays_nothing_waits_until_relisted, a_delisted_holders_worthless_redemption_burns_in_a_wind_down).

Invariant 5: Exit Rights Never Gated or Pausable

  • Definition: Investors cannot be trapped in the vault by a vault pause.
  • Testable Property: When the vault is paused (paused == true):
    • request_deposit is refused by #[when_not_paused] (PausableError::EnforcedPause).
    • request_redeem succeeds and locks shares into escrow.
    • claim_redeem and claim_deposit remain open.
    • cancel_redeem remains open. Outside a wind-down, a delisted holder, or one the compliance rules refuse, exits through the cash claim instead; in a wind-down the escrow is surrendered. A frozen holder is held (Invariant 6).
    • cancel_deposit and cancel_redeem stay open for a sealed epoch while the vault is paused, because a paused vault cannot price it (Invariant 6).

Invariant 6: Single-Step Atomic Cancellation

  • Definition: Cancellation is all-or-nothing, and it is open exactly while the vault could not price the epoch now. Three rules decide it:
    1. A readable price closes cancellation, even while the notice still runs. A price is readable when the feed answers that it is valid, its report was accepted at or after the epoch closed, and it answers a share price above zero. A feed that fails to answer any of these has no readable price.
    2. If the vault can no longer price the epoch — the report expires, the NAV is paused, the vault is paused, or the feed fails to answer or prices at zero or less — cancellation opens again. That is the way out, so escrow is never stuck behind a stalled feed. An investor cannot cause the reopening; only a lapsed attester, a raised NAV pause, a paused vault or a broken feed installed by governance can.
    3. The epoch is priced at the latest valid report at fulfil time that was accepted at or after the close — not necessarily the report that first closed the window.
  • Testable Property:
    • While an epoch is Open, or Pending with no readable price or with the vault paused, cancel_deposit and cancel_redeem return 100% of the escrow, unless an issuer clawback leaves the balance below the deposit (EscrowNotCovered, see Invariant 1).
    • A readable price refuses cancellation with PriceAvailable, even before priceable_at; once that report expires, cancellation works again (cancellation_reopens_when_the_price_that_closed_it_expires).
    • Pausing the vault reopens cancellation; unpausing closes it again while the price is still readable (a_paused_vault_reopens_cancellation_of_an_epoch_it_could_price).
    • Outside a wind-down, cancel_redeem refuses a delisted holder (NotAllowlisted) and a move the compliance rules refuse (HolderNotEligible); the request stays pending and the cash claim remains open. It holds a frozen holder (Frozen): the request stays pending, and its cash claim is held too until the freeze is lifted. Neither the share token's transfer pause nor the vault's own allowlist place stops a cancellation (a_token_pause_stops_trading_but_not_a_share_return, a_delisted_vault_still_returns_escrowed_shares).
    • In an active wind-down, cancel_redeem never returns shares: the escrow joins the holder's wind-down entitlement (RedemptionSurrendered), whether the holder is allowlisted or not. A frozen holder's escrow stays until the freeze is lifted.
    • Once fulfilled, cancellation is refused with AlreadyPriced.
  • Operating note: keep freshness_duration longer than the notice, so a normal epoch's price does not lapse and reopen the window on its own.

Invariant 7: Directional Rounding & Non-Creation of Value

  • Definition: Arithmetic conversions round in the vault's favor, preventing arbitrage and value creation from rounding residue.

  • Mathematical Statement: $\text{assets\_to\_shares}(a) = \lfloor (a \cdot \text{SCALE}) / \text{NAV} \rfloor$

    $\text{shares\_to\_assets}(s) = \lfloor (s \cdot \text{NAV}) / \text{SCALE} \rfloor$

    $\text{assets\_to\_shares}(\text{shares\_to\_assets}(s)) \le s$

  • Testable Property: For all values of $a, s \in [1, 10^{30}]$ and $\text{NAV} \in [\text{min\_answer}, \text{max\_answer}]$, a round-trip conversion never creates value. Remainder satisfies: $(a \cdot \text{SCALE}) - (s \cdot \text{NAV}) < \text{NAV}$

  • Settlement: pricing records what each epoch promised (shares_promised, assets_promised, see get_epoch_settlement). Claims floor one by one, so together they pay at most that. When the last request of a priced epoch settles, the remainder leaves pending_mint_shares and committed and the vault publishes EpochReconciled { epoch, share_dust, cash_dust }. The cash stays in the reserve, owed to nobody, and reaches every holder through the NAV. A running total that would go below zero fails with AccountingMismatch (6070) instead of clamping. A deposit refunded after pricing (worth less than one share base unit) leaves the priced epoch's total_deposited as EpochFulfilled published it; only a cancellation still open for the epoch lowers it.

  • A request that can never settle keeps its epoch open, and the two cases leave different amounts behind. A zero-asset redemption whose holder may not take the shares back (HolderNotEligible, a_request_that_cannot_settle_keeps_its_epoch_open) leaves only the epoch's ordinary rounding remainder in committed — fewer units than the epoch had redemption requests — because that request was never owed any cash. A priced deposit whose mint a compliance module refuses (a_refused_mint_keeps_a_priced_deposit_epoch_open) is not rounding dust: the mint reverts, so that deposit's whole share entitlement stays in pending_mint_shares, on top of the epoch's own remainder, until the mint is allowed. Either way it is still owed to nobody.

  • A deposit worth less than one share base unit mints nothing and is refunded at claim, from the free reserve (a_deposit_below_one_share_is_refunded_at_claim). Pricing moves the epoch's whole deposit into the reserve and records no refund, so deploy_to_custodian or a wind-down round can spend that cash first; the claim then fails with ClaimNotCovered until the free reserve covers it again (a_dust_refund_never_takes_committed_money, a_zero_share_refund_is_refused_once_a_round_has_taken_the_reserve). This is accepted: pricing sees only the epoch's totals, so reserving these refunds would mean visiting every request, and each is worth less than one share base unit.

Settlement and upgrades. The settlement record counts a request only from the moment it exists. A vault upgraded in place to this version while any request is open would under-count its open epochs: claims in epochs priced before the upgrade would revert, and a mixed epoch could reconcile early. This version is therefore deployed fresh: an earlier vault is not upgraded to it in place.

Invariant 8: Bounded Governance Timelocks

  • Definition: Upgrades and wind-downs cannot execute without advance notice, and delays cannot be set to invalid boundaries.
  • Testable Property:
    • Upgrade delay $\in [7 \text{ days}, 90 \text{ days}]$ and $\text{delay} \ge \text{notice}$, checked when a delay change is proposed and again when it applies.
    • Wind-down delay $\in [7 \text{ days}, 90 \text{ days}]$ (WindDownDelayTooShort, WindDownDelayTooLong); 7 days when none was set.
    • The vault takes no deposit, redemption, seal or pricing, and proposes no wind-down, until its one-time setup closes (SetupOpen). finish_setup refuses with SetupIncomplete until the share token and the oracle report this vault with their own setup closed, the vault is the token's only manager, the token has no shares outstanding, the vault passes the token's identity check, the token has not frozen the vault's address, and the token is bound to its compliance contract. It also needs the asset to have the token's decimals, four different addresses for the asset, the token, the oracle and the vault, an oracle that answers state() and freshness_duration(), a custodian other than the vault, and the vault's own books empty: the first epoch, with no deposit or redemption booked in it, nothing committed, and no shares owed or to burn. A compliance contract that answers vault() and setup_open() must report this vault with its own setup closed; one that does not answer them is an external module and is accepted. Shares minted before setup closes would redeem against depositors' money, and a request booked before setup would be paid from it, so both the token supply and the vault's books must be empty. It refuses with AdminTransferPending while an admin hand-over offered during setup is pending. Setup never reopens (SetupClosed).
    • After setup, the vault's custodian, role grants, revoking manager, admin hand-overs and lowering the notice or the wind-down delay go through the queue; a direct call is refused with UseTimelock. Raising the notice or the wind-down delay, the deposit cap, pause/unpause and revoking any other role stay instant. A Notice or WindDownDelay change is checked against its bounds when proposed and again when it applies.
    • Minimum epoch duration $\in [1 \text{ day}, 30 \text{ days}]$ (InvalidAmount); None until governance sets one, so only the manager seals. Set directly during setup; afterwards both raising and lowering it go through the queue, unlike the notice and wind-down delay, where raising stays instant. Once set, it stays within bounds and cannot be cleared back to None: manager-only sealing cannot return.
    • Every change waits in the queue (propose_change → apply_change). Applying before its eta reverts with ChangeNotReady.
    • A change whose delay is shorter than the notice standing at apply time reverts with UpgradeDelayBelowNotice.
    • Time spent paused does not count. Applying while paused is refused.
    • Nothing is proposed or applied during an active wind-down, and no admin hand-over is accepted (WindDownActive). The one exception is a grant of the share token's compliance role, which waits the normal delay.
    • One code change (upgrade or upgrade delay) waits at a time (UpgradeProposalExists).
    • Renouncing admin is permanently refused (AdminRequired).
    • Once its one-time setup closes, the share token's upgrades, grants, manager revocations, admin hand-overs and compliance or verifier swaps wait on the vault's clock under the same rules; a direct call is refused with UseTimelock. Revoking compliance stays instant, granting it also lands during a wind-down, and the last holder cannot renounce (LastComplianceHolder).
    • A compliance swap needs a contract that lists the token in linked_tokens; one that answers vault() and setup_open() must also name the token's vault with its own setup finished (ComplianceNotBound). As at finish_setup, one that does not answer them is an external module and is accepted. A verifier swap needs a verifier whose verify_identity accepts the vault's address (VerifierRefusesVault). Both are checked when the change is proposed and again when it applies, and a contract that does not answer linked_tokens or verify_identity fails the check.
    • Once its one-time setup closes, the oracle's upgrades, grants, admin hand-overs and every config change except a shorter freshness_duration wait on the vault's clock under the same rules; a direct call is refused with UseTimelock. Revoking attester or guardian, the NAV pause and clear_latest stay instant.
    • Once its one-time setup closes, the compliance contract's module changes, token bindings and admin hand-overs wait on the vault's clock under the same rules; a direct call is refused with UseTimelock.

Invariant 9: Wind-Down Pro-Rata Solvency

  • Definition: In an active wind-down, total round payouts across all share claims can never exceed the capital the rounds have credited.
  • Mathematical Statement: with $D$ the assets all rounds credited and $S$ the snapshot, $\text{payout}_i = \lfloor e_i \cdot D / S \rfloor$ and $\sum_i \text{payout}_i \le D$.
  • Testable Property: In any distribution round with arbitrary share distributions and rounding remainders, the vault remains solvent for the last claimant. A round credits the whole free reserve at any price the oracle allows: the vault records assets credited, not a rate per share, so a round never rounds to zero while the pot holds one unit (a_round_of_one_unit_at_the_lowest_price_still_credits_it). Once every holder has claimed, wind_down_owed keeps less than one asset base unit per holder (at_the_lowest_price_holders_collect_the_reserve_less_a_unit_each). Active wind-down is strictly irreversible.
  • wind_down_claimable and claim_wind_down compute the payout with one function and fail alike (the_claimable_view_and_the_claim_fail_alike_at_the_overflow_edge).
  • The vault's own address is refused with NoEntitlement, since the shares it holds are escrow (the_vault_cannot_claim_against_its_own_escrowed_shares).
  • A proposal already stops new deposits (WindDownAlreadyProposed); exits, pricing and treasury go on until it activates, and cancelling the proposal reopens deposits.
  • An escrowed redemption cancelled during the wind-down counts toward the holder's entitlement, and so does a priced deposit a delisted holder claims. Credited before the first round, those shares count in its supply snapshot (a_credit_before_the_first_round_leaves_every_holder_their_share).
  • During an active wind-down, a priced redemption whose claim pays nothing burns its escrowed shares instead of returning them, because the snapshot left them out (a_redemption_that_pays_nothing_returns_no_shares_in_a_wind_down).
  • The share token refuses a plain transfer into the vault, so the snapshot counts holders' shares only (shares_sent_to_the_vault_are_refused_so_the_snapshot_counts_holders_only). Shares sent to a vault before its token was upgraded to carry this refusal stay in the snapshot, with no one able to claim their slice.
  • Each payout floors per holder. Once every holder whose shares were all surrendered has claimed, wind_down_owed keeps less than one unit per such holder, plus whatever value the snapshot counted in shares that never actually minted (for example pending_mint_shares from an epoch that promised more shares than it later minted). That remainder is not released: a later round lets each holder's floor catch up and needs it (a_later_round_needs_the_units_an_earlier_round_left_in_owed, owed_stays_below_the_holder_count_once_every_share_is_surrendered).
  • A frozen holder's slice stays in wind_down_owed until the freeze lifts, and lifting it needs a holder of the share token's compliance role. So the claim depends on a live compliance holder: the last one cannot renounce, a grant of the role passes the token's timelock during a wind-down after the normal delay, and a deployment keeps a backup holder granted during setup (§4) (a_frozen_holder_is_paid_once_a_compliance_holder_granted_in_the_wind_down_lifts_the_freeze).

2. Deploy-Time Parameters & Runtime Configuration

Deploying the Strata Vault Kit involves five contracts configured via environments.toml. Parameters are split into immutable deploy-time constructor arguments and governance-tunable runtime settings.

Deploy-Time Parameters (constructor_args)

Contract Parameter Type / Units Meaning & Constraints Where Set
compliance admin Address Administrator account for compliance configuration compliance.constructor_args
identity_verifier admin Address Administrator account authorized to update allowlist identity_verifier.constructor_args
share_token name String Human-readable token name (e.g. "Strata Vault USDC") share_token.constructor_args
share_token symbol String Token ticker symbol (e.g. "bvUSDC") share_token.constructor_args
share_token admin Address Token administrative multisig (Governance) share_token.constructor_args
share_token compliance_authority Address Compliance multisig; receives the compliance role for freezes, plus legal transfers and recovery with governance's co-signature. The vault's manager role is granted after deploy share_token.constructor_args
share_token compliance Address Address of deployed compliance contract share_token.constructor_args
share_token identity_verifier Address Address of deployed identity_verifier contract share_token.constructor_args
nav_oracle admin Address Oracle admin multisig (Governance) nav_oracle.constructor_args
nav_oracle attester Address Authorized reporter multisig for NAV attestations nav_oracle.constructor_args
nav_oracle guardian Address Guardian multisig authorized to pause the NAV nav_oracle.constructor_args
nav_oracle config.freshness_duration u64 (seconds) Validity window of an attestation before it is stale; from 1 s to 35 days (MAX_FRESHNESS_SECS) nav_oracle.constructor_args
nav_oracle config.cooldown_secs u64 (seconds) Minimum time between consecutive attestations. At least 1 s (MIN_COOLDOWN_SECS), so at most one report per ledger. At most freshness_duration, so a new report can always replace the last one before the freshness window ends nav_oracle.constructor_args
nav_oracle config.max_up_bps u32 (basis points) Largest upward move per attestation, 1 to 10,000 nav_oracle.constructor_args
nav_oracle config.max_down_bps u32 (basis points) Largest downward move per attestation, 1 to 10,000; 10,000 lets a loss of any size land at once nav_oracle.constructor_args
nav_oracle config.min_answer i128 (18 decimals) Absolute floor price per share, at least MIN_ANSWER ($10^{12}$, a millionth of an asset unit per share). An oracle upgraded in place with a stored min_answer below the floor keeps it; even its instant set_config (a shorter freshness window) is refused until a timelocked Config change raises it to the floor nav_oracle.constructor_args
nav_oracle config.max_answer i128 (18 decimals) Absolute ceiling price per share ($\ge \text{min\_answer}$, $\le 10^{6} \times 10^{18}$, MAX_ANSWER) nav_oracle.constructor_args
async_vault asset Address Settlement asset SAC contract address (e.g. USDC). Must have the share token's 7 decimals: finish_setup refuses with SetupIncomplete otherwise (health().decimals_match). Every classic Stellar asset has 7; a Soroban token with other decimals needs a fork of the share token async_vault.constructor_args
async_vault share_token Address Deployed share token contract address async_vault.constructor_args
async_vault oracle Address Deployed NAV oracle contract address async_vault.constructor_args
async_vault roles.governance Address Governance multisig authority async_vault.constructor_args
async_vault roles.treasury Address Treasury multisig authority async_vault.constructor_args
async_vault roles.guardian Address Guardian multisig authority async_vault.constructor_args
async_vault roles.manager Address Account that gets the vault's manager role (closes epochs); a role, not one of the five authorities async_vault.constructor_args
async_vault roles.compliance Address Compliance multisig authority async_vault.constructor_args
async_vault roles.attester Address Attestation authority. Not read: nothing checks that it matches the oracle's attester async_vault.constructor_args

The share token's decimals are fixed at 7 in its constructor; they are not a parameter.

Role Separation Checked at Construction

The async_vault constructor refuses these four pairs of equal addresses and compares no other:

  • treasury != guardian
  • treasury != governance
  • compliance != governance
  • compliance != treasury

Runtime Parameters (Governance-Tunable)

Parameter Method Authority Constraints & Defaults
Standing Notice set_notice(secs: u64); after setup, lowering goes through propose_change(Notice(secs)) → apply_change(id) Governance Notice wait before pricing. Default: 0. Must satisfy $\text{secs} \le \text{upgrade\_delay}$ and $\text{secs} \le 30 \text{ days}$ (MAX_NOTICE_SECS), checked again when a Notice change applies. Raising is instant.
Custodian Address set_custodian(custodian: Address) during setup; afterwards propose_change(Custodian(address)) → apply_change(id) Governance Recipient address for off-chain capital deployment. Required before finish_setup and deploy_to_custodian. Never the vault itself (InvalidCustodian), checked when it is set, proposed and applied. The deploy sets it before setup closes.
Deposit Cap set_deposit_cap(cap: Option<i128>) Governance Maximum capacity for deposited capital (see Supply and Capital Figures). None = unbounded. Refuses negative cap. Instant both ways, also after setup. The cap is vault-wide; there is no cap per investor.
Wind-Down Delay set_wind_down_delay(secs: u64); after setup, lowering goes through propose_change(WindDownDelay(secs)) → apply_change(id) Governance Minimum notice before wind-down activation. Default and minimum 7 days (MIN_WIND_DOWN_DELAY), maximum 90 days (MAX_WIND_DOWN_DELAY). Raising is instant.
Minimum Epoch Duration set_min_epoch_duration(secs: u64) during setup; afterwards propose_change(MinEpochDuration(secs)) → apply_change(id) Governance How long the open epoch must stay open before anyone may seal it. From 1 day (MIN_EPOCH_DURATION_FLOOR) to 30 days (MIN_EPOCH_DURATION_CEILING), checked again when a MinEpochDuration change applies (InvalidAmount). Default None: only the manager seals until governance sets one. After setup, both raising and lowering go through the timelock.
Upgrade Delay propose_change(UpgradeDelay(secs)) → apply_change(id) Governance Timelock delay for wasm upgrades. Must be $\ge 7 \text{ days}$, $\le 90 \text{ days}$, and $\ge \text{notice}$.
Oracle Configuration set_config(config: OracleConfig); after setup, propose_change(Config(config)) → apply_change(id) Governance Updates oracle parameters within the constructor's bounds. set_config is instant during the oracle's setup. After it, set_config is instant only for a shorter freshness_duration: later reports go stale sooner, and no value moves. Every other change, tighter limits included, goes through propose_change(Config(config)) → apply_change(id), and the bounds are checked again when it applies. A tighter fall cap or a longer cooldown can hold the price above a real loss, and a narrower band can stop pricing. Applying a Config change sets every field, freshness included; to keep a cut made after the proposal, cancel the queued change and propose again.
Oracle Feed propose_change(Oracle(address)) → apply_change(id) Governance Waits for the timelock. The new feed must name this vault through vault() with its own setup finished, and must answer state() and freshness_duration(), at proposal and again at apply (FeedNotBound). The next fulfilment prices from it, including an epoch sealed before the swap.

Transfer Modes

The SCF Tranche 2 admin panel lists allowlist management, pause, and transfer modes: disabled, or allowed when both sides are allowlisted. The kit already has both modes, so it adds no separate transfer-mode setting.

  • Allowed when both sides are allowlisted is the default and is always on. The share token's transfer and transfer_from refuse a move unless the sender and the receiver both pass the identity verifier (IdentityVerificationFailed) and neither address is frozen (AddressFrozen). The token runs these checks itself, whatever the compliance contract answers. The kit's compliance contract registers no modules, so its can_transfer accepts any pair. That leaves the decision to the token's own checks; it does not open transfers (rules_with_no_modules_accept_any_pair_yet_the_token_still_checks_both_sides). A module can only refuse more moves, and after setup adding one waits for the timelock.
  • Disabled is the share token's pause. Only the token admin (governance) can call pause and unpause; anyone else is refused with AdminRequired, and the guardian has no role on the token. Both calls take effect at once, before and after setup: they do not go through the timelock. While the token is paused, transfer and transfer_from are refused with EnforcedPause (the_token_admin_pauses_transfers_at_once_after_setup).
  • Exits stay open in either mode. Both modes apply only to transfers between holders. The vault moves shares with mint, burn and forced_transfer, which ignore the pause, and legal_transfer ignores it too. While the token is paused, deposit and redemption requests (the redemption escrows shares with forced_transfer), cancellations of both, deposit claims (mint) and redemption claims (burn and cash payout) all go through (a_token_pause_leaves_deposits_exits_and_cancellations_open, a_token_pause_stops_trading_but_not_a_share_return, a_token_pause_does_not_hold_a_redemption_in_a_wind_down). A delisted holder still exits in cash (Invariant 4); only a freeze holds an exit, as below. burn is the RWA extension's manager-only call, with the vault as the token's sole manager; the token has no burn_from, so no holder can burn their own shares.
  • Freezes and the pauses. A freeze is per holder and set by the compliance authority. It stops that holder's transfers and also holds what the vault owes them until it is lifted (see the compliance matrix). The token pause is global and set by governance. It stops every transfer between holders and nothing else. The vault's own pause (the guardian pauses, governance unpauses) is a separate control. It stops deposit requests, pricing and applying queued changes, not transfers.

Health View

health() returns one flag per check. A deployment is ready when setup_open is false and every other flag is true. health() leaves out three finish_setup checks: that the share token has no shares outstanding, which stops being true at the vault's first claim, that the vault's own books are empty, which stops being true at its first request, and that no admin hand-over offered during setup is pending (AdminTransferPending). If finish_setup refuses with SetupIncomplete while every field from token_bound to feed_answers is true, there are two possible causes. Shares were minted before setup: the token's total_supply() shows them. Or the vault's books are not empty: current_epoch() is past 1, get_epoch(1) shows a deposit or redemption booked, or committed(), pending_mint_shares() or pending_burn_shares() is not zero.

Field True when
setup_open finish_setup has not run yet. While true, admin changes are instant and requests and epochs are refused.
token_bound The share token names this vault through vault() and its own setup is finished.
oracle_bound The oracle names this vault through vault() and its own setup is finished.
sole_token_manager This vault is the share token's only manager.
allowlisted This vault passes the share token's identity verifier. Escrowing and returning shares do not need it. Only a delisted holder's conversion does: it mints the shares into the vault's own escrow. While this flag is false, those conversions wait until the vault is allowlisted again, and nothing is lost.
vault_unfrozen The share token has not frozen this vault's address. The vault's own share moves ignore an address freeze, so freezing the vault stops nothing; finish_setup still refuses a frozen vault.
compliance_bound The share token is in its compliance contract's linked_tokens, and a compliance contract that answers vault() and setup_open() names this vault with its own setup finished. One that does not answer them is an external module and passes; its own governance is a trust assumption.
decimals_match The asset's decimals() equals the share token's. Pricing converts base units at the attested price, so a mismatch would put every deposit and exit off by a power of ten.
addresses_distinct The asset, the share token, the oracle and the vault are four different addresses.
custodian_set A custodian is set, and it is not the vault itself.
feed_answers The oracle answers state() and freshness_duration(). A new feed with no report passes. oracle_bound cannot tell a feed from another contract bound to this vault, such as the compliance contract.
feed_valid The oracle reports Valid: a report exists, it has not expired, it is in band and the NAV is not paused.
freshness_covers_notice The oracle's freshness_duration is at least the vault's notice.

freshness_covers_notice false means a report can expire before the notice ends. A sealed epoch's cancellation window can then reopen on its own, so set freshness_duration above the notice. feed_valid false right after a deploy is normal until the first attestation.

Supply and Capital Figures

  • total_economic_supply() counts share base units held outside the vault plus those priced for deposits and not yet minted: the token's total_supply(), less the vault's own share balance, plus pending_mint_shares(). It leaves out every share in the vault's escrow. That includes the shares of a redemption that is not priced yet: the next price still applies to them, and a cancellation can return them (economic_supply_excludes_shares_locked_in_redemption_escrow). The first wind-down round's supply snapshot counts those shares, so the two figures differ while redemptions wait to be priced.
  • Deposited capital, which the deposit cap limits, is the asset the vault holds plus net_deployed(), less committed(). It counts money in and out, not the vault's value (what the vault and the custodian hold): a deposit request adds what it brings, and a priced redemption takes off what it pays. A gain or a loss at the custodian does not move it, even once funded back. After a gain, the figure is below the vault's value. Once leavers are paid the gain, it can go negative, and the cap then admits more than its own amount (a_gain_paid_out_to_leavers_leaves_room_above_the_cap). After a loss, the figure stays above the vault's value, and the cap refuses deposits sooner (a_loss_at_the_custodian_still_counts_toward_the_cap).
  • net_deployed() is what deploy_to_custodian sent less what fund brought back; it goes negative once more came back than went out. The custodian repays through fund. A plain transfer to the vault raises the vault's balance but leaves net_deployed as it was, so from then on the same money counts twice in deposited capital and the cap refuses deposits sooner.

Days and Ledgers

The kit measures time two ways. Durations in seconds read the ledger's close time, so they do not depend on how often ledgers close: the timelock delay, the notice, the freshness window, the cooldown, the wind-down delay and the minimum epoch duration.

Figures counted in ledgers assume a ledger every 5 seconds, 17,280 a day. They are the storage lifetimes in §5 (30 days, renewed once 29 or fewer remain; 90 days for role entries, set by OpenZeppelin), the 7 days a new admin has to accept a hand-over (ADMIN_ACCEPT_LEDGERS), the 30 days the extend script asks for, and the 7-day window of the app's activity list.

If the network makes ledgers faster, each ledger-counted figure lasts less on the clock by the same factor; the second-based ones do not change. At 2.5-second ledgers, an entry extended to 30 days lasts 15, so the extend script must run twice as often, and a hand-over must be accepted within 3.5 days.


3. Role & Authority Matrix

Strata distributes control across five native Stellar multisig authorities, two manager roles and permissionless public entrypoints. Every privileged function needs exactly one of these authorities or roles, except the share token's legal_transfer and recover_balance, which need compliance and governance in the same call. Each call asks each account it needs for one signature. An admin entrypoint the kit defines takes no caller argument: the stored admin signs it.

Authority Capabilities & Anti-Capabilities

Authority Quorum / Profile Authorized Capabilities Anti-Capabilities (What It Cannot Do)
Governance High-quorum deliberative multisig Set parameters (notice, custodian, deposit_cap, wind_down_delay, min_epoch_duration), propose/apply upgrades, propose/cancel wind-down, unpause the vault, pause/unpause the share token, transfer admin, finish each contract's one-time setup, co-sign compliance's legal_transfer and recover_balance as the share token's admin. After setup, these wait for the timelock: role grants, revoking the manager, admin hand-over, the custodian, lowering the notice or the wind-down delay, the minimum epoch duration in either direction, upgrades, the token's compliance and verifier swaps, the compliance contract's module and token-binding changes, and oracle config changes other than a shorter freshness window. Revoking the treasury or the guardian stays instant, because taking a power away moves no value. Cannot pause the vault directly; cannot move funds; cannot initiate custodian transfers; cannot attest prices; cannot bypass timelocks.
Guardian Low-threshold fast-reaction multisig pause (vault); pause_nav (oracle emergency price freeze). Cannot unpause; cannot move funds; cannot block redemption requests; cannot block payable claims or cancellations.
Treasury Operational capital multisig deploy_to_custodian (moves free reserve). Capital comes back through fund, which anyone may call. Cannot deploy while anything is uncovered; cannot touch escrowed subscription assets; cannot alter parameters or pause.
Attester High-security attestation multisig attest (submits a NAV report: the price, its expiry and a proof reference). Cannot price outside deviation band; cannot violate cooldown; cannot operate on the vault directly.
Compliance Legal / KYC operator multisig Manage allowlist (allow), topic claims; token interventions (freeze; legal_transfer and recovery co-signed by governance). Cannot touch vault reserve; cannot move a holder's shares without governance's signature in the same call; cannot move shares out of or into the vault's address, or freeze it once the token knows its vault (an earlier freeze makes the vault's finish_setup refuse); cannot pause vault operations; cannot bypass exit-only cash redemptions for an unfrozen holder — freezing holds a covered claim until it lifts, rather than paying or redirecting it.
Manager (vault role) Operational keeper account; a role, not one of the five authorities close_epoch: seals the open epoch at any time, nothing else. Cannot choose prices; cannot mint, burn or move shares; cannot stop a sealed epoch from being priced; not sealing stalls requests only until the open epoch has run the minimum epoch duration, if one is set; cannot alter timelocks. After setup, granting or revoking it waits for the timelock.
Manager (share-token role) The vault contract, alone: the vault's finish_setup refuses while another account holds it mint, burn, forced_transfer on the share token: the vault mints and burns at claim and moves escrowed shares. Cannot freeze, recover or make a legal transfer. After setup, granting or revoking it waits for the vault's timelock. See AUTHORIZATION_MATRIX.md §2.
Permissionless Any caller / keeper / investor close_epoch once the open epoch has run the minimum epoch duration, fulfill_epoch, request_deposit, cancel_deposit, claim_deposit, request_redeem, cancel_redeem, claim_redeem, fund, activate_wind_down, finalize_wind_down_round, claim_wind_down. Operations are strictly constrained by contract state, timing, and solvency guards.

Replacing a Compromised Attester

Pause first, so no report lands while the roles change, and lift the pause last:

  1. Pause the NAV: the oracle's guardian calls pause_nav, or its admin calls set_nav_paused(true). The oracle refuses every report and the vault prices nothing; sealed epochs reopen to cancellation. The vault also refuses deposits (FeedNotValid) until the new attester's first report in step 6.
  2. Revoke the compromised attester: revoke_role(attester, "attester", admin) on the oracle. It is instant, during setup and after it.
  3. Grant a replacement. During the oracle's setup, grant_role is instant. After it, propose a GrantRole change and apply it once the vault's delay has run, plus any time the vault spends paused. The NAV stays paused that whole time, at least seven days, so replacing an attester stops subscriptions for at least the timelock delay.
  4. Clear the stored report: clear_latest (admin; only while the NAV is paused). Left in place, it is valid again once the pause lifts, and anyone can price with it any epoch sealed before it was accepted, until it expires. Skip this only if you know the report predates the compromise. The next report then has no earlier price to cap its move: only min_answer and max_answer bound it.
  5. Lift the NAV pause: set_nav_paused(false) (admin).
  6. The new attester posts a report. Pricing resumes: an epoch can be priced once a report accepted after its seal is valid.

Upgrading the Oracle from an Earlier Release

Releases before the proof reference stored the report as nav_per_share, expires_at and timestamp. This version stores nav_per_share, expires_at, accepted_at, proof_hash and proof_uri, and cannot read a report of the earlier shape. After an in-place upgrade, every call that reads the old report fails: latest, nav_per_share, attested_at, is_stale and attest, and also state and ensure_consumable while the NAV is not paused. The vault then cannot price or take a deposit, and cancelling a request in a sealed epoch fails. No migration rewrites the old report. Clear it instead:

  1. Pause the NAV before the upgrade applies: the guardian calls pause_nav, or the admin calls set_nav_paused(true). While the NAV is paused, state answers Paused without reading the report, so the vault prices nothing and requests in sealed epochs stay cancellable. Deposits are refused while the NAV is paused (FeedNotValid) or the feed cannot answer, so the vault takes none from here until the attester's report in step 5. If the upgrade applied first, pause the NAV at once: neither pause_nav nor clear_latest reads the report.
  2. Apply the upgrade: apply_change once its delay has run.
  3. Remove the old report: clear_latest (admin). It deletes the entry without reading it.
  4. Lift the NAV pause: set_nav_paused(false) (admin).
  5. The attester posts a report with its proof. As after any clear, no earlier price caps its move: only min_answer and max_answer bound it.

The test a_report_of_the_earlier_shape_is_cleared_and_replaced stores a report of the earlier shape and recovers it this way. A fresh deployment has no such report and skips these steps.

When the Manager or the Attester Stops

Pricing needs both roles. Once governance has set a minimum epoch duration, anyone can seal in the manager's place; nothing on chain replaces the attester. The kit assumes both keep working; until then, holders keep these ways out:

  • The manager stops sealing. Requests in the open epoch stay pending, and each holder can still cancel: a deposit comes back as cash, a redemption as shares. Once governance has set a minimum epoch duration, anyone may seal the open epoch once it has been open that long; the earliest a holder then sees a price is the minimum plus the standing notice, counted from when the epoch opened. Without a minimum set, the way out is the same as today: governance grants a new manager, which after setup waits for the vault's timelock, at least seven days, plus any time the vault spends paused.
  • The attester stops reporting. Once the last report expires, new deposits are refused (FeedNotValid). An epoch sealed after the last report has no readable price, so its requests stay cancellable, and claims already priced still pay. Governance revokes the attester on the oracle at once and grants a replacement, which waits for the timelock after setup, as in steps 2 and 3 above.
  • Neither comes back. No holder can exit at a price. Governance can propose a wind-down; once its delay has run, anyone activates it, and its rounds pay every holder pro rata from the cash the vault holds and whatever the custodian returns through fund, with no price needed.

Comprehensive Entrypoint Permission Matrix

Contract Entrypoint Calling Authority Access Control Guard Pausable?
AsyncVault request_deposit Investor (Caller) holder.require_auth(); refused until setup finishes (SetupOpen), while the feed is not valid (FeedNotValid) and while the vault holds less than its pending escrow (EscrowNotCovered) Yes (halted by pause)
AsyncVault cancel_deposit Investor (Caller) holder.require_auth(); refused while the vault's balance cannot cover the refund (EscrowNotCovered) No (open during pause)
AsyncVault claim_deposit Investor (Caller) holder.require_auth() No (open during pause)
AsyncVault request_redeem Investor (Caller) holder.require_auth(); refused until setup finishes (SetupOpen) No (open during pause; refused in a wind-down)
AsyncVault cancel_redeem Investor (Caller) holder.require_auth() No (open during pause)
AsyncVault claim_redeem Investor (Caller) holder.require_auth() No (always open)
AsyncVault close_epoch Manager; anyone once the open epoch has run the minimum epoch duration caller.require_auth(); without manager, MinEpochDurationNotElapsed before the minimum, AccessControlError::Unauthorized when none is set; refused until setup finishes (SetupOpen) No
AsyncVault fulfill_epoch Permissionless None; refused until setup finishes (SetupOpen) Yes (halted by pause)
AsyncVault pause Guardian #[only_role(caller, "guardian")] N/A
AsyncVault unpause Governance caller must be the admin (AdminRequired), then caller.require_auth() N/A
AsyncVault set_notice Governance #[only_admin]; raising is instant, lowering is instant during setup, then propose_change No
AsyncVault set_custodian Governance #[only_admin]; instant during setup, then propose_change; never the vault itself (InvalidCustodian) No
AsyncVault set_deposit_cap Governance #[only_admin]; instant both ways No
AsyncVault set_min_epoch_duration Governance #[only_admin]; instant during setup, then propose_change; 1 to 30 days No
AsyncVault set_wind_down_delay Governance #[only_admin]; raising is instant, lowering is instant during setup, then propose_change; never below 7 days No
AsyncVault finish_setup Governance #[only_admin]; needs the wiring complete, the vault's own books empty, and no pending admin hand-over; once No
AsyncVault setup_open Permissionless None (view) No
AsyncVault propose_wind_down Governance #[only_admin]; new deposits stop until it is cancelled No
AsyncVault cancel_wind_down_proposal Governance #[only_admin] No
AsyncVault activate_wind_down Permissionless None (requires timelock elapsed) No
AsyncVault finalize_wind_down_round Permissionless None No
AsyncVault claim_wind_down Shareholder (Caller) holder.require_auth() No
AsyncVault deploy_to_custodian Treasury #[only_role(caller, "treasury")] No (open during pause)
AsyncVault fund Anyone: the custodian, treasury or a backer caller.require_auth(); the caller pays No
AsyncVault propose_change Governance #[only_admin]; after setup No
AsyncVault cancel_change Governance #[only_admin] No
AsyncVault apply_change Governance #[only_admin] Refused if paused or winding down
AsyncVault pending_changes Permissionless None (view) No
AsyncVault grant_role, transfer_admin_role Governance Instant during setup, then propose_change (a zero live_until_ledger cancels at once) No
AsyncVault revoke_role Governance treasury, guardian: instant. manager: instant during setup, then propose_change No
AsyncVault set_role_admin None Always refused (UseTimelock) N/A
AsyncVault accept_admin_transfer Proposed Admin The pending admin's require_auth(); refused during an active wind-down (WindDownActive) No
NavOracle attest Attester #[only_role(caller, "attester")] Refused if the NAV is paused
NavOracle pause_nav Guardian #[only_role(caller, "guardian")] N/A
NavOracle set_nav_paused Governance #[only_admin] N/A
NavOracle set_config Governance #[only_admin]; instant during setup, then only for a shorter freshness_duration; otherwise propose_change No
NavOracle clear_latest Governance #[only_admin] (requires NAV paused) No
NavOracle bind_vault Governance (oracle admin) #[only_admin]; during setup, once No
NavOracle finish_setup Governance #[only_admin]; needs a bound vault and no pending admin hand-over No
NavOracle propose_change Governance #[only_admin]; after setup No
NavOracle cancel_change Governance #[only_admin] No
NavOracle apply_change Governance #[only_admin]; after the vault's delay Refused while the vault is paused or winding down
NavOracle pending_changes Permissionless None (view) No
NavOracle grant_role, transfer_admin_role Governance Instant during setup, then propose_change (a zero live_until_ledger cancels at once) No
NavOracle accept_admin_transfer Proposed Admin The pending admin's require_auth(); refused during an active wind-down (WindDownActive) No
NavOracle revoke_role Governance Instant (attester, guardian) No
NavOracle set_role_admin None Always refused (UseTimelock) N/A
ShareToken pause Admin (Governance) caller must be the admin (AdminRequired), then caller.require_auth() N/A
ShareToken unpause Admin (Governance) caller must be the admin (AdminRequired), then caller.require_auth() N/A
ShareToken mint Manager (Vault) #[only_role(operator, "manager")] Bypasses token pause
ShareToken burn Manager (Vault) #[only_role(operator, "manager")] Bypasses token pause
ShareToken forced_transfer Manager (Vault) #[only_role(operator, "manager")] Bypasses token pause
ShareToken legal_transfer Compliance, co-signed by Governance (token admin) #[only_role(caller, "compliance")] and the admin's require_auth() in the same call, from two different accounts; never from or to the vault's address; the destination passes verify_identity; a reference of 1–128 bytes Bypasses token pause
ShareToken set_address_frozen, freeze_partial_tokens, unfreeze_partial_tokens Compliance #[only_role(operator, "compliance")]; never freezes the vault's address once the token knows its vault No
ShareToken recover_balance Compliance, co-signed by Governance (token admin) #[only_role(operator, "compliance")] and the admin's require_auth() in the same call, from two different accounts; never from or to the vault's address No
ShareToken set_compliance, set_identity_verifier Governance operator must be the admin (AdminRequired), then operator.require_auth(); instant during setup, then propose_change No
ShareToken bind_vault Governance (token admin) #[only_admin]; during setup, once No
ShareToken finish_setup Governance #[only_admin]; needs a bound vault and no pending admin hand-over No
ShareToken propose_change Governance #[only_admin]; after setup; refused while the vault is winding down, except a grant of compliance; a compliance or verifier swap passes its check (ComplianceNotBound, VerifierRefusesVault) No
ShareToken cancel_change Governance #[only_admin] No
ShareToken apply_change Governance #[only_admin]; after the vault's delay; a compliance or verifier swap passes its check again Refused while the vault is paused; while it winds down too, except a grant of compliance
ShareToken pending_changes Permissionless None (view) No
ShareToken grant_role, transfer_admin_role Governance Instant during setup, then propose_change (a zero live_until_ledger cancels at once) No
ShareToken accept_admin_transfer Proposed Admin The pending admin's require_auth(); refused during an active wind-down (WindDownActive) No
ShareToken revoke_role Governance compliance: instant, the last holder included; a successor's grant waits one delay, during a wind-down too. manager: instant during setup, then propose_change No
ShareToken renounce_role The role's holder caller.require_auth(); the last compliance holder is refused (LastComplianceHolder) No
ShareToken set_role_admin None Always refused (UseTimelock) N/A
IdentityVerifier allow Admin (Compliance) #[only_admin] No
IdentityVerifier set_claim_topics_and_issuers Admin (Compliance) #[only_admin]; operator is not read No
Compliance bind_token, unbind_token, add_module_to, remove_module_from Governance #[only_admin], operator is not read; instant during setup, then propose_change No
Compliance bind_vault Governance (compliance admin) #[only_admin]; during setup, once No
Compliance finish_setup Governance #[only_admin]; needs a bound vault and no pending admin hand-over No
Compliance propose_change Governance #[only_admin]; after setup No
Compliance cancel_change Governance #[only_admin] No
Compliance apply_change Governance #[only_admin]; after the vault's delay Refused while the vault is paused or winding down
Compliance pending_changes Permissionless None (view) No
Compliance transfer_admin_role Governance Instant during setup, then propose_change (a zero live_until_ledger cancels at once) No
Compliance accept_admin_transfer Proposed Admin The pending admin's require_auth(); refused during an active wind-down (WindDownActive) No

4. Deployment Runbook Summary

A clean deployment executes in three sequenced phases:

  1. Phase 1: Contract Deployment
    • Deploy compliance, identity_verifier, share_token, nav_oracle, and async_vault with constructor arguments matching environments.toml.
    • The harness deploy script (scripts/harness/deploy.ts) gives each authority one key. It does not create multisig accounts or check the deposit asset's auth flags yet; see the design doc's §8.10.
  2. Phase 2: Post-Deployment Role Wiring
    • Call ShareToken::grant_role(vault_address, "manager", governance) to authorize lazy share minting and burning.
    • Call ShareToken::grant_role(backup, "compliance", governance) for a second compliance account kept cold, before the token's finish_setup. Required: lifting a freeze needs a compliance holder, and after setup a new one waits one timelock delay.
    • Call ShareToken::bind_vault(vault_address), then ShareToken::finish_setup(). The token's admin changes are instant until then and wait for the vault's timelock afterwards.
    • Call IdentityVerifier::allow(vault_address, true), signed by the compliance key, so a delisted holder's priced deposit can be minted into the vault's escrow; finish_setup requires it.
    • Call Compliance::bind_token(share_token_address, governance) to link SEP-57 rule verification, then Compliance::bind_vault(vault_address) and Compliance::finish_setup(). Its module and binding changes are instant until then and wait for the vault's timelock afterwards.
    • Call NavOracle::bind_vault(vault_address), then NavOracle::finish_setup(). The oracle's admin changes are instant until then and wait for the vault's timelock afterwards.
    • Call set_min_epoch_duration(secs) on the vault while setup is open, so the protection is on from the start: anyone can then seal an epoch once it has run that long. Set it above the manager's usual epoch length, so an outsider only seals once the manager has really stopped, not while a normal epoch is still running. Left unset, only the manager seals, and once setup closes the minimum changes only through the timelock.
    • On the vault, call set_custodian(custodian), set_notice(secs) and, if initial capital intake is bounded, set_deposit_cap(cap). All three are instant during setup, so deposits never open without the cap. The custodian is required, and the vault's own address is refused (InvalidCustodian).
    • Then call finish_setup() on the vault. It refuses with SetupIncomplete until every wiring step above is in place, the token has no shares outstanding and the vault's address is not frozen on it. It also needs the asset to have the token's decimals, four different addresses for the asset, the token, the oracle and the vault, an oracle that answers state() and freshness_duration(), and the vault's own books empty: the first epoch, with no deposit or redemption booked in it, nothing committed, and no shares owed or to burn. It refuses with AdminTransferPending while an admin hand-over offered during setup is pending. health() shows which check is false. The vault takes no deposit, redemption, seal or pricing before it.
  3. Phase 3: Operational Parameterization
    • Oracle reporter submits the genesis NAV attestation (attest). Deposits open only once it is valid, so post it before announcing the vault.

5. Storage Lifetime (TTL) Policy

Soroban archives a ledger entry when its time to live (TTL) runs out. An archived entry cannot be read until it is restored, so a contract whose instance is archived refuses every call.

The kit runs the same code on every network. Each persistent entry, the contract instance included, has a target lifetime and a threshold one day shorter. Writing an entry does not extend it on its own: an entry goes back to its target only when a call asks for that and its TTL has fallen to the threshold. The kit's storage helpers ask on every read and every write of the kit's own entries. OpenZeppelin asks when it reads an entry that already exists, never when it writes one, so the kit reads back each entry it creates through OpenZeppelin. The transaction that creates an entry therefore extends it to its target at once. The network decides only how long a new entry lives before any extension (see Network settings).

Contract What it extends When To how long
async_vault Its instance, and every persistent entry it reads or writes: epochs, requests, settlements, wind-down positions, pending governance changes Every call that reads or writes the entry 30 days (518,400 ledgers), once 29 days or less remain
nav_oracle Its instance, the latest report, and each pending governance change it reads or writes attest extends the instance and the report; bind_vault, finish_setup, grant_role, transfer_admin_role, propose_change, cancel_change and apply_change extend the instance; every other call extends whichever entry it reads or writes Same
share_token Its instance, each balance and freeze entry it writes, and each pending governance change it reads or writes Every call that moves shares or changes token settings: transfer, transfer_from, approve, mint, burn, forced_transfer, legal_transfer, freezes, recovery, set_compliance, set_identity_verifier, pause, unpause, grant_role, revoke_role, transfer_admin_role, bind_vault, finish_setup, propose_change, cancel_change, apply_change; also the reads balance and total_supply, which may be the only token calls during a wind-down Same
identity_verifier Its instance and each allowlist entry allow, is_allowed, verify_identity Same
compliance Its instance, the modules and bound tokens it writes, and each pending governance change it reads or writes Every hook the token calls (can_create, can_transfer, created, transferred, destroyed) and its admin calls Same
async_vault, share_token, nav_oracle The four entries a grant writes: the account's role, its member-list slot, the member count and the role list Each grant (in the constructor, grant_role and an applied GrantRole change) extends all four. After that, a role check extends only that account's role entry; the slot, the count and the list are extended only by grants and by calls that list role members (such as the vault's manager() or the token's get_role_member_count) 90 days (1,555,200 ledgers), once 89 days or less remain

The kit's own lengths are the constants in crates/strata-storage (PERSISTENT_EXTEND_AMOUNT, INSTANCE_EXTEND_AMOUNT, and thresholds one day shorter). The entries OpenZeppelin stores keep OpenZeppelin's own lengths. All of them are fixed in code: a governance setting would add an admin power for little gain.

Pending governance changes. A change waiting in the timelock of async_vault, share_token, nav_oracle or compliance lives as a persistent entry, extended to 30 days when it is proposed. The wait itself can run up to 90 days (strata_timelock::MAX_DELAY), so a change nobody touches can archive before it is due. Nothing is lost: the call that applies it restores the archived entry itself and pays the restore fee, the same as any other archived entry. npm run extend also keeps it alive. It reads each contract's open ids from the contract's instance, where the timelock stores them, so it never reads the pending entries to find them. It builds each entry's storage key the way the timelock crate does, and a test checks that the two agree. If the entry has archived, it restores it, then extends it the same 30 days as every instance and Wasm.

What OpenZeppelin extends, and what the kit adds. stellar-tokens 0.7.2 stores the share token's balances and freeze entries, and the compliance contract's modules and bound tokens. stellar-access 0.7.2 stores the roles of the vault, the token and the oracle. OpenZeppelin extends an existing entry when it reads it: balances, freezes, modules and bound tokens to 30 days, roles to 90. It does not extend an entry when it writes one, so a new entry would start at the network's minimum lifetime and wait for a later caller to read it. The kit closes that gap by reading back what it writes, through OpenZeppelin's own reads, in the same call:

  • the share token reads back each balance and freeze entry after mint, burn, transfer, transfer_from, forced_transfer, legal_transfer, recover_balance, set_address_frozen, freeze_partial_tokens and unfreeze_partial_tokens;
  • the vault, the token and the oracle read back every entry a grant writes (the account's role, its place in the member list, the member count and the list of roles) after each grant in their constructors, in grant_role, and in an applied GrantRole change;
  • the compliance stub reads back the hook's modules after add_module_to and an applied AddModule change, and the bound tokens after bind_token and an applied BindToken change.

So a new balance, freeze, role, module or bound-token entry reaches its target in the transaction that creates it, and the kit keeps OpenZeppelin's thresholds without copying them. A revoke creates nothing: it rewrites the member count and moves the last member into the freed slot with plain writes, and extends none of the entries it moves. Allowances are temporary entries that live until their live_until_ledger. OpenZeppelin never extends an instance; the kit does, as above. The token's total supply and metadata live in its instance.

Network settings. Each network sets how long a new persistent entry lives and how far one extension can reach. Validators can change these settings by vote; the kit hardcodes neither. Check Stellar Lab's network limits for current values.

Setting Testnet Mainnet
Minimum lifetime of a new persistent entry 120,960 ledgers (about 7 days) 2,073,600 ledgers (about 120 days)
Longest lifetime one extension can reach 3,110,400 ledgers (about 180 days) 3,110,400 ledgers (about 180 days)

Read over RPC on 2026-10-20.

What this means on each network. On testnet a new entry would live about 7 days, less than any threshold, so renewals start in its first week: the transaction that creates it extends it to its target, and from the next day any call that reads it renews it. On mainnet a new entry already lives 120 days, more than any target, so the extension in the creating transaction changes nothing. No call renews a 30-day entry there until about the fourth month (day 91), or a role until day 31. A restored entry comes back with the network's minimum lifetime, so a mainnet restore pays at least 120 days of rent.

Why the same values on every network. The protocol already applies each network's minimum, so mainnet entries start at 120 days without the kit knowing it. The same Wasm runs on testnet and on mainnet, so what is tested on testnet is what ships; a build-time network profile would mean two Wasm files to review. The threshold one day under the target means an entry in daily use is renewed at most once a day, for about a day of rent. Capping each extension (extend_ttl_with_limits) would let rarely used entries archive sooner, and each of those restores would pay at least 120 days of rent on mainnet.

Who pays. The account that sends a transaction pays the rent for every extension that transaction triggers. The transaction that creates an entry pays for its target, or for the network's minimum when that is longer: 30 or 90 days on testnet, 120 days on mainnet. A later call pays only to bring an entry back to its target once it has fallen to its threshold: about a day of rent when the entry is read daily, up to a whole target after a long quiet period. A restore pays for the network's minimum, as above.

What frontends should do.

  • Expect uneven renewal fees. The first call after a quiet period pays to renew every entry it reads that has fallen to its threshold, so the same call can cost more after a quiet week than on a busy day.
  • Simulate again just before submitting. The fee comes from the simulation. If an entry falls to its threshold between simulation and submission, the call pays a renewal the fee does not cover, and the transaction fails.
  • Let RPC add a restore when simulation asks for one. When a call needs an archived entry, simulation adds its restore to the transaction (see Restoring). Submit the transaction as simulated, restore included.

Idle deployments. An entry nobody reads archives when its lifetime runs out: 30 days after its last renewal (90 for a role), and on mainnet never sooner than 120 days after it was created. Run STELLAR_ACCOUNT=<funded account> npm run extend -w scripts/harness after every deploy and before a long quiet period. It restores, when archived, and extends by 30 days three kinds of entry only: each contract instance, the Wasm it runs, and each pending timelock change. Other entries, such as balances and roles, are restored by the call that needs them (see Restoring). It reads the contracts in environments.toml [staging.contracts]; --env <name> picks another environment, and --config <record> reads a deployment record instead. With --config it uses the network the record names, unless --env names another, and it prints the network and RPC before it sends anything. Put flags after --, or npm swallows them: npm run extend -w scripts/harness -- --config <record>. Extending needs no authority, so any funded account can pay.

Restoring. Since Protocol 23 an invocation can restore archived entries itself, so a call to an archived contract usually goes through once simulation adds the restore. Restoring many entries in one transaction can still hit per-transaction limits. Restore them first, in batches: each RestoreFootprintOp transaction takes as many entries as the limits allow. stellar contract restore sends one: --id <contract> restores an instance, --id <contract> --key-xdr <key> a data entry, and --wasm-hash <hash> a Wasm. After a restore, simulate the call again before sending it.

Production modules. The compliance and identity contracts in this repository are testnet stubs. A production compliance module or identity registry must extend its own instance and entries the same way, each entry in the transaction that creates it, or the share token stops working when they archive.


6. Contract Interfaces for Adopters

The vault reaches the other contracts only through these traits. An adopter who replaces one implements the trait, and the compiler checks the implementation against what the vault calls.

Interface Defined in Implemented here by What the vault calls
OracleFeed crates/strata-bindings nav-oracle state, nav_per_share, attested_at, freshness_duration
FungibleToken OpenZeppelin stellar-tokens 0.7.2 share-token transfer, balance, total_supply, decimals
RWAToken OpenZeppelin stellar-tokens 0.7.2 share-token mint, burn, forced_transfer
IdentityVerifier OpenZeppelin stellar-tokens 0.7.2 identity-verifier (testnet stub) verify_identity, called by the share token

A feed that implements OracleFeed can replace nav-oracle; it must report Stale once its report outlives freshness_duration, and attested_at must be the ledger time the report was accepted, not a time the reporter supplies.

The testnet identity verifier sets one address per call (allow), emits no event and offers no paged listing. These are limits of the stub: a production identity registry replaces it.

Two more traits connect the share token, the oracle and the kit's compliance contract to the vault's timelock. The vault implements ClockSource (crates/strata-timelock), and the three read its timelock_clock to time their own changes. Each implements VaultBinding (crates/strata-bindings): vault names the vault it is bound to, and setup_open says whether its admin changes are still instant.

The vault's finish_setup reads the token and the oracle through VaultBinding and refuses until each reports this vault with its own setup closed. It reads the compliance contract the same way, but accepts one that does not answer VaultBinding: such an external module keeps its own governance, which is a trust assumption. It also reads the token's manager members (OpenZeppelin AccessControl), its total_supply and decimals (FungibleToken) and the asset's decimals, runs verify_identity on its own address, reads linked_tokens from the token's compliance contract (OpenZeppelin TokenBinder), and calls the oracle's state and freshness_duration (OracleFeed). A replacement for any of these must answer those calls, or the vault's setup cannot finish.

After setup, the share token makes the same check before it swaps a contract, when the swap is proposed and again when it applies. New compliance rules must list the token in linked_tokens, and rules that answer VaultBinding must name the token's vault with their setup closed. Like finish_setup, the token accepts an external module that does not answer VaultBinding, on trust. A new identity verifier must accept the vault's address in verify_identity.


7. Error Codes and Entrypoint Docs

Each kit contract owns a block of error codes. A call that fails inside another contract returns that contract's code: a deposit claim the identity verifier refuses returns 304, not a vault code. The blocks never overlap, so a code inside them always names the kit contract that raised it. OpenZeppelin's codes are shared: every contract built on its libraries returns the same code for the same failure, so 304 says what failed, not where.

Contract Error enum Block Codes in use
nav_oracle OracleError 3000–3999 3001–3021, 3023–3026
async_vault VaultError 6000–6999 6000–6001, 6005, 6007, 6009, 6012, 6014, 6029–6035, 6037–6077
share_token ShareTokenError 7000–7999 7000–7013, 7015–7019
compliance ComplianceContractError 8000–8999 8001–8011

The blocks are defined once, in crates/strata-bindings (ORACLE_ERRORS, VAULT_ERRORS, TOKEN_ERRORS, COMPLIANCE_ERRORS). Each contract declares its enum through strata_bindings::error_enum!, and the build fails if a code leaves its contract's block or two blocks overlap. A code is never reused: a removed variant leaves its number retired. The testnet identity verifier has no enum of its own; it refuses with OpenZeppelin's RWAError::IdentityVerificationFailed (304). OpenZeppelin's libraries keep their codes outside the kit's blocks: below 3000 in the modules the kit uses, and from 4000 to 5999 in its governance crate.

Every entrypoint the kit defines or overrides carries a doc in its contract's spec, so generated clients and block explorers show it. The doc is a one-line summary, then # Arguments, # Errors, # Events and # Authorization; a section that would be empty is left out, so a view has no # Events and no # Authorization. Functions that OpenZeppelin's traits add without an override keep OpenZeppelin's docs.

  • Amounts are in the asset's base units and shares in the share token's base units. Prices are in WAD: asset base units per share base unit, times 10^18. Times and durations are in seconds; live_until_ledger is a ledger number.
  • An error named without its enum is the contract's own. Any other error carries its enum, as in AccessControlError::Unauthorized.
  • NotInitialized and AccountingMismatch are not listed per entrypoint. They mean the contract's own state is broken, and any call that reads the broken entry can return them.
  • A call into another contract can fail with that contract's error. The docs name the ones a caller should plan for, such as the asset's own error when the payer cannot pay. A replacement identity verifier or compliance module may refuse with codes of its own.