chore: merge feedback into main

.github/workflows/build.yml

@@ -74,6 +74,16 @@ jobs:
           if ! command -v stellar &> /dev/null; then
             cargo binstall --locked stellar-cli@27.0.0
           fi
+      # The upgrade tests run built Wasm, so they need the fixture, both
+      # contracts and their probe builds first (docs/TESTING.md).
+      - name: Run the Wasm upgrade tests
+        run: |
+          stellar contract build --manifest-path fixtures/upgrade-target/Cargo.toml
+          stellar contract build --package share-token
+          stellar contract build --package nav-oracle
+          CARGO_TARGET_DIR=target/upgrade-probe stellar contract build --package share-token --features upgrade_probe
+          CARGO_TARGET_DIR=target/upgrade-probe stellar contract build --package nav-oracle --features upgrade_probe
+          SOROBAN_SDK_BUILD_SYSTEM_SUPPORTS_SPEC_SHAKING_V2=1 cargo test --locked -p async-vault -p nav-oracle --features upgrade_wasm with_wasm
       - name: Start Stellar local network
         # No tagged releases upstream, so this pins main as read on 2026-08-14
         uses: stellar/quickstart@864f91d804c0061bd11ef8872d3e318581febb55
@@ -148,10 +158,45 @@ jobs:
         run: npm run test:guards -w scripts/harness
         env:
           HARNESS_NETWORK: local
+      - name: Build the vault without the wind-down minimum
+        run:
+          CARGO_TARGET_DIR=target/short-wind-down stellar contract build
+          --package async-vault --features short_wind_down
+      - name: Run a wind-down on a throwaway vault on the local network
+        run: npm run test:wind-down -w scripts/harness
+        env:
+          HARNESS_NETWORK: local
       - name: Keep the harness report when it fails
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: harness-runs
           path: scripts/harness/runs/
           if-no-files-found: ignore
+
+  rust-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: |
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            target/
+          key: ${{ runner.os }}-cargo-checks-${{ hashFiles('**/Cargo.lock') }}
+      # rustup reads rust-toolchain.toml, which includes clippy and rustfmt.
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+      - name: Lint with warnings as errors
+        run: cargo clippy --locked --workspace --all-targets -- -D warnings
+      - name: Check licences, advisories, bans and sources
+        uses: EmbarkStudios/cargo-deny-action@3c6349835b2b7b196a839186cb8b78e02f7b5f25 # v2.1.1
+        with:
+          # Replaces the action's default --all-features, so CI runs the
+          # same command as docs/TESTING.md.
+          arguments: --locked
+          command: check

AGENTS.md

@@ -20,15 +20,18 @@ result. Three states per side, none skipped: **pending, priced, claimed**.
 
 What the contracts enforce:
 
-1. **Entry is gated** by a post-KYC allowlist, checked on the receiver of a
-   subscription (enforced on share claim in contracts today; request-time
-   check is targeted for a future milestone) and on every share transfer.
+1. **Only allowlisted addresses enter.** The post-KYC allowlist is checked
+   when a subscription is requested, again when its shares are minted, and on
+   every share transfer.
 2. **A covered claim always pays.** Once priced and covered, a cash claim cannot
    be blocked by a pause, a stale valuation, or the investor losing their
    allowlist place. Priced claims are never re-priced and never identity-gated;
-   a delisted, non-frozen investor leaves through the exit-only cash path.
-3. **Cancellation is atomic and single-step**, open only until the attestation
-   that prices the request is accepted. There is no instant exit.
+   a delisted, non-frozen investor leaves through the exit-only cash path,
+   including a deposit that was priced before the delisting.
+3. **Cancellation is atomic and single-step**, open only while the vault cannot
+   price the request: the attestation that prices it closes cancellation, and
+   cancellation reopens if that report expires, the NAV is paused or the vault
+   is paused. There is no instant exit.
 
 Five authorities, each a native Stellar multisig: governance, compliance,
 attestation, treasury, guardian. Testnet only. Not audited.
@@ -111,15 +114,54 @@ Not recorded here on purpose. The reference base kept them in this file and they
 drifted: its `AGENTS.md` and its generated client pointed at two different vault
 contracts. The addresses emitted by the deploy script are authoritative.
 
+## Code conventions
+
+- **Crate names.** Shared crates in `crates/` start with `strata-`
+  (`strata-timelock`, `strata-storage`, `strata-bindings`), so a path such as
+  `strata_timelock::DAY_DURATION` reads as the kit's own code.
+- **Addresses in entrypoints.** In an entrypoint the kit defines, `caller` is
+  the account that must sign the call, and `holder` is the account whose
+  position, request or balance the call is about. When one account is both, the
+  entrypoint takes `holder` and that account signs. The two ends of a share
+  transfer are `from` and `to`, and other addresses are named for what they
+  are (`custodian`, `vault`, the allowlisted `account`). OpenZeppelin trait
+  methods keep their own names (`operator`, `user_address`).
+- **Named errors.** Contract code fails with a named error variant, never with
+  `unwrap`, `expect` or a bare `panic!`. Tests may unwrap. Each contract
+  declares its error enum through `strata_bindings::error_enum!`, which fails
+  the build if a code leaves the contract's block (`docs/kit-spec.md`, section
+  7).
+- **No boolean switches.** A new entrypoint does one thing. Two behaviours get
+  two functions, like `freeze_partial_tokens` and `unfreeze_partial_tokens`,
+  not one function that takes a `bool`.
+- **Guards.** Each precondition is a `pub(crate) fn` in the contract's
+  `guards.rs`. Its name is the condition it checks (`positive_amount`,
+  `not_winding_down`), and it panics with a named error when the condition
+  fails. An entrypoint calls its guards first and then does its work, so its
+  preconditions are the first lines a reader sees.
+- **Doc comments.** Every public entrypoint has one, in OpenZeppelin's style: a
+  one-line summary, then `# Arguments` with units (asset base units, share base
+  units, WAD prices, seconds or ledgers), `# Errors`, `# Events` and
+  `# Authorization`. Every error variant's doc says when it happens. Keep them
+  short: they are stored in the Wasm as part of the contract spec, which keeps
+  1,024 bytes of each doc and drops the rest without a warning.
+  `every_contract_doc_fits_the_spec` (`crates/strata-bindings/tests/spec_docs.rs`)
+  fails when one is longer.
+- **Design notes.** Each contract's `lib.rs` opens with a `//! # Design`
+  section: five to ten bullets, each a choice and its trade-off, in plain words
+  and with no issue numbers or decision ids.
+- **Exact pins.** Every crates.io dependency, dev-dependencies included, is
+  pinned with `=` to the version in `Cargo.lock`.
+
 ## Conventions
 
 - Conventional Commits, imperative, subject ≤ 50 chars. **No AI attribution.**
 - Issue-first: every PR closes an issue (`Closes #N`). Branches are
   `feat/<issue>-<desc>`, `fix/...`, `chore/...`.
 - Issue bodies follow the templates in `.github/ISSUE_TEMPLATE/`, 200 words of
   prose hard cap. Titles are natural language with no prefix.
-- Exact dependency pins. Dependencies are never upgraded mid-milestone; each
-  migration is its own issue in the following one.
+- Dependencies are never upgraded mid-milestone; each migration is its own
+  issue in the following one.
 - Estimates live in the `Estimate` field of the
   [project board](https://github.com/orgs/BootNodeDev/projects/29), not in issue
   bodies.

README.md

@@ -35,11 +35,11 @@ deploy from `environments.toml` → `[staging.contracts]`, which is the record.
 <!-- deployed-addresses:start -->
 | Contract | Address |
 | --- | --- |
-| `async_vault` | `CD5LYYXGOJ7R23P6D7YUN6DUJQYMI23KEUEOIFKXOSWOX3KHKTXRITED` |
-| `nav_oracle` | `CBKVMUMIX7MXYHX5K34N5HYZOP6S2VGWF7MN27RIWBV3A3WD3X3L63CO` |
-| `share_token` | `CDOISQTQRCYOTH6S3DFQ6UKJ2TEXLNO7NFIGOZS4RZL63IRCVXXCGP5N` |
-| `identity_verifier` | `CCTCCY7AVFAIRGEWWJZT2UDMBHS3NGNKVUWLY43CHDNN75AQEV6P3EOY` |
-| `compliance` | `CDEH6FJBK7NDFLALO3X3GDXZUREYHUSNC7ODPM64RBG3BBXW2USMW7OO` |
+| `async_vault` | `CCDWVENC7GNFO757JON65OKWJXHYIEGPVPDWVCGRZOPAHOQURPHQRPUG` |
+| `nav_oracle` | `CADX6LVWOQ6DGFHEQ6AMJHDPKWOO2RTHEEIERVPWHOUJCN3WNEGYHHL3` |
+| `share_token` | `CDRAUSDVE7OKWKCJJNPD4HYTMLGF5XFVG5DY7KMLQCBHJTW53TYN7UGK` |
+| `identity_verifier` | `CBZEZBVOFNEYBGWRMON7WDFAXCNLH3DEAF3EDIS7PJRSLY6BK7XN5O7J` |
+| `compliance` | `CDHEEBIAMKLMJHJZHQ3R63PVWQUMQAX4WY6WDODZOY2E5X5GNSFFG6DR` |
 | `asset` | `CCOHKZLQ5EAD2A3RLHYHH7W4K2TNLNELXUVLWZIZALH45WXHH5H3QV7E` |
 <!-- deployed-addresses:end -->
 
@@ -139,16 +139,21 @@ Output of a real run from a fresh clone. Contract IDs differ on every run.
 deploying to local (http://localhost:8000/rpc)
 account keys in .env.keys.local (13 new)
 funded 13 accounts; 0 already existed
-asset contract CDKWXRAHPQVFOAEBOOWWR62ZXAE2IV4V47PATFN7IX4XDW5QIUUL7D2B
-compliance CDGKQCYSMTDRBO7SYV3V72H6AMCQ3UNQFKUU4AD5GSU2I32XDYFS6F3U
-identity_verifier CCZE76VWEWJ47NSFMIXCKU3L55CZZTI5JJY4CSYAWPO3WXPDFXUCA5G6
-share_token CD6IA3BOPFX7VNADJ3GFK7IZGPVPNZA6HBCF425CNPSQ2GN7QZ3UUCP2
-nav_oracle CAHD5ZKMIDD67ZEJUB5ACR62FMAYMQJ2KCRV2MBDNXWT7WEZ2VV3MRDD
-async_vault CDQNMAZP7D5IA7AXZGK3XWYPFD2LDR6V5HQD2OLXZJYNQN4BMNN6SXWJ
+asset contract CCW7OKVOXBBBX3YK6O7F6TZPNIFG32OG4UY7R2K6NSWZUI4R75QCEPVT
+compliance CDPCD2BQQKVQBQFAFI4YBLN3TRX34J5NZUQQMUBGHPYNY64LCEM63DTL
+identity_verifier CC4SRUIMKOBZSEO2GKGVQMDWPWCBJBBIMYYE7BBCUEZE6VMD3SFQDAMW
+share_token CDC7SRTDZIMJSLC5AONUD3FIFYZGMFOHRAS7LLYV2ATJRT7RMTMQO2DG
+nav_oracle CCUUBP3RGOIZZL4DUGRL4FBOSQJZKBPNQ7VUWIN6UOOYBJYYKGNT5E52
+async_vault CB2KVM2WHLXDZRHGCYPTGE7PZM6OORXCNVBUMC3L7GY5KX4BA6NMADXE
 clients generated
 vault holds share_token manager role
+share_token bound to the vault, setup finished
 vault is allowlisted
 share_token bound to compliance
+compliance bound to the vault, setup finished
+nav_oracle bound to the vault, setup finished
+vault setup finished
+health {"addresses_distinct":true,"allowlisted":true,"compliance_bound":true,"custodian_set":true,"decimals_match":true,"feed_answers":true,"feed_valid":false,"freshness_covers_notice":true,"oracle_bound":true,"setup_open":false,"sole_token_manager":true,"token_bound":true,"vault_unfrozen":true}
 wrote deployed.local.json
 ```
 
@@ -159,8 +164,32 @@ integration suites against that deployment:
 ```sh
 npm run test:happy-path -w scripts/harness
 npm run test:guards -w scripts/harness
+CARGO_TARGET_DIR=target/short-wind-down stellar contract build --package async-vault --features short_wind_down
+npm run test:wind-down -w scripts/harness
 ```
 
+Deploy afresh before each run of the suites. The guards leave the vault's
+notice at 10 seconds, and lowering it back waits for the timelock, so a second
+run against the same deployment can fail wherever it prices an epoch right
+after closing it. `test:wind-down` ignores `deployed.local.json`: it deploys
+its own throwaway vault set, built from the `short_wind_down` wasm above, so
+it can reach an active wind-down without the real seven-day minimum.
+
+### Keeping a deployment alive
+
+Every contract extends its own storage when it is called, but a deployment
+nobody calls archives after 30 days. Restore and extend all of it with:
+
+```sh
+STELLAR_ACCOUNT=<identity or secret> npm run extend -w scripts/harness
+```
+
+It reads the testnet contracts from `environments.toml`, restores any
+archived instance or Wasm, and extends each by 30 days. Any funded account
+pays, since extending needs no authority. Use `--env <name>` for another
+environment, or `--config <record>` for a deployment record. The
+[TTL policy](./docs/kit-spec.md#5-storage-lifetime-ttl-policy) says what each
+contract extends on its own.
 
 ## Reference base
 

contracts/async-vault/Cargo.toml

@@ -11,11 +11,13 @@ doctest = false
 
 [dependencies]
 soroban-sdk = { workspace = true }
-storage = { path = "../../crates/storage" }
+strata-storage = { path = "../../crates/strata-storage" }
 stellar-access = { workspace = true }
 stellar-macros = { workspace = true }
 stellar-contract-utils = { workspace = true }
-bindings = { path = "../../crates/bindings" }
+stellar-tokens = { workspace = true }
+strata-bindings = { path = "../../crates/strata-bindings" }
+strata-timelock = { path = "../../crates/strata-timelock" }
 
 
 [dev-dependencies]
@@ -24,7 +26,9 @@ nav-oracle = { path = "../nav-oracle" }
 share-token = { path = "../share-token" }
 compliance = { path = "../compliance" }
 identity-verifier = { path = "../identity-verifier" }
-proptest = "1"
+proptest = "=1.11.0"
 
 [features]
 upgrade_wasm = []
+# Drops the wind-down minimum to zero for the local harness. Never deployed.
+short_wind_down = []