feat(oracle): put admin powers behind the timelock

[hpmaxi]

Summary

The oracle's limits could be changed at once, and the oracle could not be upgraded.

Every oracle config change except a shorter freshness window now waits for the vault's timelock, and the oracle upgrades under that timelock. Attester, guardian and admin grants wait too. Tightening waits as well, because a tighter fall cap or a longer cooldown can hold the price above a real loss. A one-time setup window keeps the deploy's own wiring instant.

Changes

• bind_vault and finish_setup: oracle admin changes are instant only until setup finishes, and setup cannot finish while a hand-over offered during setup is pending
• After setup, set_config is instant only for a shorter freshness_duration; every other change goes through propose_change / apply_change, checked against the bounds when proposed and when applied
• Grants, admin hand-overs and upgrades wait after setup; revokes, the NAV pause and clear_latest stay instant; set_role_admin is always refused
• The oracle reads the vault's clock: a vault pause moves the eta and holds the change, a wind-down refuses it
• The oracle reports its vault and setup state through VaultBinding
• Upgrade tested on built Wasm under a live valuation, including a one-time migrate in a probe build
• The harness deploy binds the oracle and finishes its setup; npm run extend also extends the oracle's pending changes

Deviations

• The plan made every tightening instant; now only a shorter freshness window is (owner decision).
• The Wasm tests' CI step waits as a patch (no workflow scope).
• The upgrade test uses an oracle probe build, like the token's; probe error code 3100.
• shortens_freshness_only compares the whole config except freshness, so a field added later waits.
• Extra tests: binding, hand-over expiry, events, clock reads, instance TTL, bounds at apply, hostile configs, live harness checks.
• New admin calls and overridden role calls extend the instance.
• The token's no-instant-upgrade test moves to the built-Wasm tests, as the oracle's.

Acceptance criteria

• After setup, set_config is instant only for a shorter freshness_duration; any other change, tighter limits included, waits
• A config change lands through propose_change / apply_change
• Attester and guardian grants and admin hand-overs wait after setup; revokes, the NAV pause and clear_latest stay instant; setup cannot finish while a hand-over from setup is pending
• The oracle upgrades through the timelock and exposes no instant upgrade

Test plan

Automated tests

1. cargo test --locked: all green, with 80 tests in nav-oracle (39 new), 51 in share-token and 328 in async-vault.
2. Build the fixture, the token, the oracle and both probe builds (CARGO_TARGET_DIR=target/upgrade-probe stellar contract build --package nav-oracle --features upgrade_probe), then cargo test --locked -p async-vault -p nav-oracle --features upgrade_wasm with_wasm: 7 passed, including the_oracle_upgrades_under_a_live_valuation and the two …_exposes_no_immediate_upgrade tests. 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 (43 passed).

Manual verification

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

Breaking changes

After finish_setup, the oracle refuses grant_role, transfer_admin_role with a non-zero ledger, and every set_config except a shorter freshness_duration with UseTimelock (3015); set_role_admin is always refused. The deploy must call bind_vault and finish_setup on the oracle. New error codes 3011–3021 and 3025. 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 12:11pm UTC