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:
- Core Invariants & Testable Properties
- Deploy-Time Parameters & Runtime Configuration
- Role & Authority Matrix (Privileges & Anti-Capabilities)
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.
-
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 asuncovered, 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 withReserveCommittedToExitswhen$\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_custodianis 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:
- Escrow a depositor can still cancel is paid first.
cancel_depositpays from the vault's whole balance when that balance covers the deposit's own amount, in any order; otherwiseEscrowNotCovered. While$\text{held} < \text{cancellable\_escrow}$ ,request_depositis refused withEscrowNotCovered, so a new deposit never pays an earlier cancellation. - Priced redemption claims come next. Each pays when the liquid reserve covers its own amount, in any order; otherwise
ClaimNotCovered. - 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.
- A refund of a deposit below one share and a transfer to the custodian come last, only from the free reserve (
ClaimNotCovered,ReserveCommittedToExits). -
uncovered()shows the gap,$\text{committed} + \text{cancellable\_escrow} - \text{held}$ when positive. Funding that gap withfundlifts 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, whichuncovered()does not show. - 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.
- 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.
- Escrow a depositor can still cancel is paid first.
-
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_epochbeforepriceable_atare rejected withNoticeNotElapsed. Changing the notice period viaset_noticeapplies only to future epochs and never shortens the notice of an already closed epoch.
- 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_epochis rejected withAttestationBeforeClose. A valuation accepted in the exact closing ledger timestamp or later is accepted.attested_atis the ledger time the oracle accepted the report, stored asaccepted_at, not a valuation date: the attester submits no time of its own. So "accepted before the close" compares acceptance time. The reporter'sexpires_atcan only shorten a report's life: the oracle storesmin(expires_at, attested_at + freshness_duration).
- 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_redeemsucceeds when:- The vault is paused (
paused == true). - The oracle feed has expired (
is_stale == true) or the NAV is paused. - 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 incommitted. 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 withHolderNotEligibleand 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).
- The vault is paused (
- Definition: Investors cannot be trapped in the vault by a vault pause.
- Testable Property: When the vault is paused (
paused == true):request_depositis refused by#[when_not_paused](PausableError::EnforcedPause).request_redeemsucceeds and locks shares into escrow.claim_redeemandclaim_depositremain open.cancel_redeemremains 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_depositandcancel_redeemstay open for a sealed epoch while the vault is paused, because a paused vault cannot price it (Invariant 6).
- Definition: Cancellation is all-or-nothing, and it is open exactly while the vault could not price the epoch now. Three rules decide it:
- 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.
- 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.
- 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, orPendingwith no readable price or with the vault paused,cancel_depositandcancel_redeemreturn 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 beforepriceable_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_redeemrefuses 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_redeemnever 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.
- While an epoch is
- Operating note: keep
freshness_durationlonger than the notice, so a normal epoch's price does not lapse and reopen the window on its own.
-
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, seeget_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 leavespending_mint_sharesandcommittedand the vault publishesEpochReconciled { 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 withAccountingMismatch(6070) instead of clamping. A deposit refunded after pricing (worth less than one share base unit) leaves the priced epoch'stotal_depositedasEpochFulfilledpublished 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 incommitted— 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 inpending_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, sodeploy_to_custodianor a wind-down round can spend that cash first; the claim then fails withClaimNotCovereduntil 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.
- 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_setuprefuses withSetupIncompleteuntil the share token and the oracle report this vault with their own setup closed, the vault is the token's onlymanager, 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 answersstate()andfreshness_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 answersvault()andsetup_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 withAdminTransferPendingwhile 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 withUseTimelock. Raising the notice or the wind-down delay, the deposit cap,pause/unpauseand revoking any other role stay instant. ANoticeorWindDownDelaychange is checked against its bounds when proposed and again when it applies. - Minimum epoch duration
$\in [1 \text{ day}, 30 \text{ days}]$ (InvalidAmount);Noneuntil 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 toNone: manager-only sealing cannot return. - Every change waits in the queue (
propose_change→apply_change). Applying before its eta reverts withChangeNotReady. - 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'scompliancerole, 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,
managerrevocations, admin hand-overs and compliance or verifier swaps wait on the vault's clock under the same rules; a direct call is refused withUseTimelock. Revokingcompliancestays 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 answersvault()andsetup_open()must also name the token's vault with its own setup finished (ComplianceNotBound). As atfinish_setup, one that does not answer them is an external module and is accepted. A verifier swap needs a verifier whoseverify_identityaccepts the vault's address (VerifierRefusesVault). Both are checked when the change is proposed and again when it applies, and a contract that does not answerlinked_tokensorverify_identityfails the check. - Once its one-time setup closes, the oracle's upgrades, grants, admin hand-overs and every config change except a shorter
freshness_durationwait on the vault's clock under the same rules; a direct call is refused withUseTimelock. Revokingattesterorguardian, the NAV pause andclear_lateststay 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.
- Upgrade delay
- 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_owedkeeps 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_claimableandclaim_wind_downcompute 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_owedkeeps less than one unit per such holder, plus whatever value the snapshot counted in shares that never actually minted (for examplepending_mint_sharesfrom 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_oweduntil the freeze lifts, and lifting it needs a holder of the share token'scompliancerole. 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).
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.
| 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 (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 (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.
The async_vault constructor refuses these four pairs of equal addresses and compares no other:
treasury != guardiantreasury != governancecompliance != governancecompliance != treasury
| 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 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 |
| 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. |
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
transferandtransfer_fromrefuse 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 itscan_transferaccepts 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
pauseandunpause; anyone else is refused withAdminRequired, 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,transferandtransfer_fromare refused withEnforcedPause(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,burnandforced_transfer, which ignore the pause, andlegal_transferignores it too. While the token is paused, deposit and redemption requests (the redemption escrows shares withforced_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.burnis the RWA extension's manager-only call, with the vault as the token's solemanager; the token has noburn_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() 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.
total_economic_supply()counts share base units held outside the vault plus those priced for deposits and not yet minted: the token'stotal_supply(), less the vault's own share balance, pluspending_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(), lesscommitted(). 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 whatdeploy_to_custodiansent less whatfundbrought back; it goes negative once more came back than went out. The custodian repays throughfund. A plain transfer to the vault raises the vault's balance but leavesnet_deployedas it was, so from then on the same money counts twice in deposited capital and the cap refuses deposits sooner.
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.
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 | 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. |
Pause first, so no report lands while the roles change, and lift the pause last:
- Pause the NAV: the oracle's guardian calls
pause_nav, or its admin callsset_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. - Revoke the compromised attester:
revoke_role(attester, "attester", admin)on the oracle. It is instant, during setup and after it. - Grant a replacement. During the oracle's setup,
grant_roleis instant. After it, propose aGrantRolechange 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. - 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: onlymin_answerandmax_answerbound it. - Lift the NAV pause:
set_nav_paused(false)(admin). - The new attester posts a report. Pricing resumes: an epoch can be priced once a report accepted after its seal is valid.
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:
- Pause the NAV before the upgrade applies: the guardian calls
pause_nav, or the admin callsset_nav_paused(true). While the NAV is paused,stateanswersPausedwithout 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: neitherpause_navnorclear_latestreads the report. - Apply the upgrade:
apply_changeonce its delay has run. - Remove the old report:
clear_latest(admin). It deletes the entry without reading it. - Lift the NAV pause:
set_nav_paused(false)(admin). - The attester posts a report with its proof. As after any clear, no earlier price caps its move: only
min_answerandmax_answerbound 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.
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.
| 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 |
A clean deployment executes in three sequenced phases:
- Phase 1: Contract Deployment
- Deploy
compliance,identity_verifier,share_token,nav_oracle, andasync_vaultwith constructor arguments matchingenvironments.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.
- Deploy
- 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'sfinish_setup. Required: lifting a freeze needs acomplianceholder, and after setup a new one waits one timelock delay. - Call
ShareToken::bind_vault(vault_address), thenShareToken::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_setuprequires it. - Call
Compliance::bind_token(share_token_address, governance)to link SEP-57 rule verification, thenCompliance::bind_vault(vault_address)andCompliance::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), thenNavOracle::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 withSetupIncompleteuntil 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 answersstate()andfreshness_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 withAdminTransferPendingwhile 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.
- Call
- 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.
- Oracle reporter submits the genesis NAV attestation (
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_tokensandunfreeze_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 appliedGrantRolechange; - the compliance stub reads back the hook's modules after
add_module_toand an appliedAddModulechange, and the bound tokens afterbind_tokenand an appliedBindTokenchange.
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.
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.
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_ledgeris a ledger number. - An error named without its enum is the contract's own. Any other error
carries its enum, as in
AccessControlError::Unauthorized. NotInitializedandAccountingMismatchare 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.