feat(token): put admin powers behind the timelock

[hpmaxi]

Summary

aha G: "What is the plan if the token has a bug?" Today the share token cannot be upgraded, and its admin swaps rules, verifier and roles at once.

Our reply: the token upgrades under the vault's timelock, with a migration hook tested on built Wasm, and role, compliance and verifier changes wait for the same timelock. This PR delivers that for the share token. A one-time setup window keeps the deploy's own wiring instant.

Changes

• bind_vault and finish_setup: admin changes are instant only until setup finishes, and setup cannot finish while a hand-over offered during setup is pending
• After setup, grants, revoking manager, admin hand-overs, rule and verifier swaps and upgrades go through propose_change / apply_change; a direct call is refused with UseTimelock
• Revoking compliance and cancelling a hand-over stay instant; set_role_admin is always refused
• The token reads the vault's clock: a vault pause moves the eta and holds the change, a wind-down refuses it
• The token reports its vault and setup state through a new VaultBinding trait
• Upgrade tested on built Wasm with a live balance, an open deposit request and an open redemption, including a one-time migrate in a probe build
• The harness deploy binds the token and finishes its setup; npm run extend also extends the token's pending changes

Deviations

• The CI step for the Wasm tests is not pushed: the push token lacks the workflow scope. It waits as a patch, with the earlier Wasm CI step, for the owner to push.
• Extra tests: the VaultBinding view, binding an address that is not a clock source, the instance TTL on every admin call, and the token's timelock on the local network.
• The new admin entrypoints and the overridden role calls extend the instance.
• A second bind_vault is refused with SetupClosed.
• Four commits: token, Wasm test, harness, docs. TESTING.md also gets one stale test name fixed.

Acceptance criteria

• bind_vault and finish_setup work once, during setup only; setup cannot finish while an admin hand-over offered during setup is pending
• After setup, grants, revoking manager, admin hand-over, set_compliance and set_identity_verifier are refused and go through propose_change; revoking compliance and cancelling a hand-over stay instant
• The token upgrades through the timelock, tested on built Wasm with live balances, an open deposit request and an open redemption; it exposes no instant upgrade
• A vault pause moves the eta and holds the change; a wind-down refuses it

Test plan

Automated tests

1. cargo test --locked: all green, with 52 tests in share-token (30 new) and 328 in async-vault.
2. Build the fixture, the token and its probe (CARGO_TARGET_DIR=target/upgrade-probe stellar contract build --package share-token --features upgrade_probe), then cargo test --locked -p async-vault --features upgrade_wasm with_wasm: 4 passed, including the_token_upgrades_under_live_balances_and_open_requests. CI does not run this yet (see Deviations).
3. On a local quickstart network: HARNESS_NETWORK=local npm run deploy -w scripts/harness, then test:happy-path (24 passed) and test:guards (40 passed).

Manual verification

1. Run HARNESS_NETWORK=local npm run deploy -w scripts/harness. It prints "share_token bound to the vault, setup finished".
2. Propose a change on the token as governance, then run STELLAR_ACCOUNT=<funded account> npm run extend -w scripts/harness -- --config scripts/harness/deployed.local.json. It prints "share_token pending change live until ledger …".

Breaking changes

After finish_setup, the token refuses grant_role, revoking manager, transfer_admin_role with a non-zero ledger, set_compliance and set_identity_verifier with UseTimelock (7005); set_role_admin is always refused. The deploy must call bind_vault and finish_setup on the token. New error codes 7001–7011 and 7016. The console still calls the instant setters and adapts at the testnet redeploy.

Checklist

• Self-reviewed my own diff
• Tests added or updated
• Docs updated (if applicable)
• No unrelated changes bundled in

Screenshots

None.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
strata-vault-kit-app	Ready	Preview	Oct 17, 2026 10:35am UTC