Repository navigation
Conversation
Each kit contract owns a block of error codes, and a failure inside a called contract reaches the caller with that contract's code. The blocks live in strata-bindings with a check that they never overlap, and error_enum! declares an error enum whose build fails when a variant's code leaves its contract's block.
The oracle, vault, share token and compliance enums go through error_enum!, so a variant outside 3000-3999, 6000-6999, 7000-7999 or 8000-8999 fails the build. Every variant now says when it happens: InvalidConfig and NoRecord get a doc, and AmountTooLarge, AccountingMismatch, InvalidAmount, WindDownActive, NotInitialized and the oracle's AdminRequired describe what the code checks. Each enum's doc names its range.
Every oracle entrypoint and the trait methods it overrides carry a doc in the contract spec: a summary, the arguments with units, the errors, the events and who signs.
Every entrypoint of the compliance and identity verifier stubs, and each trait method they override, carries a doc in the contract spec.
Every share token entrypoint, and each OpenZeppelin method it overrides, carries a doc in the contract spec, including the library errors a call can return.
Every vault entrypoint, view and overridden trait method carries a doc in the contract spec. Amounts are in asset base units, shares in share base units, prices in WAD and times in seconds. Each doc lists the errors the call can return in a consistent state, its events and who signs.
The kit spec lists each contract's error block and the codes in use, and says how the entrypoint docs name units, errors and signers. AGENTS.md points new error enums at error_enum!.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
The contract spec keeps the first 1,024 bytes of a doc and drops the rest without a warning, so an over-long doc loses its end, where the `# Authorization` section sits. The test joins every function, enum and variant doc of the five contracts the way soroban-sdk-macros does and fails on any doc over the limit.
A valid report accepted after the close refuses a cancellation even while the notice runs, so PriceAvailable says that instead of "can be priced now". The constructor reads compliance only for the distinctness check and never reads attester. Payouts name the asset's own error when the holder cannot receive, legal_transfer lists TokensUnfrozen, and the ReserveCommittedToExits and WindDownActive docs and the kit spec's note on shared OpenZeppelin codes say what the code does.
hpmaxi
marked this pull request as ready for review
October 20, 2026 08:11
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #328
Most contract entrypoints had no doc, so the spec stored in each Wasm, which generated clients and block explorers read, said nothing about what a call does, its units, its errors or who signs. Two oracle errors had no doc, and two vault error docs described less than the code checks. Error codes followed no published range, although a failure inside a called contract reaches the caller with that contract's code.
Every entrypoint the kit defines or overrides, in all five contracts, now carries a short doc in OpenZeppelin's style that travels into the spec. Each contract's error codes sit in a published block, and the build fails if a code leaves it.
Changes
error_enum!; a code outside its block, or two overlapping blocks, fails the build.Deviations
strata-bindings, which all four contracts already use; a second check makes sure the blocks never overlap.NotInitializedandAccountingMismatchmean they are not, so they are not listed per call; the kit spec says so.# Eventsor# Authorizationsection.InvalidAmount,WindDownActive, the vault'sNotInitializedand the oracle'sAdminRequired.AGENTS.mdgained one sentence pointing new error enums aterror_enum!.Acceptance criteria
docs/kit-spec.mdlists the ranges: oracle 3000–3999, vault 6000–6999, token 7000–7999, compliance 8000–8999Test plan
Automated tests
SOROBAN_SDK_BUILD_SYSTEM_SUPPORTS_SPEC_SHAKING_V2=1 cargo test --locked: 707 passed, including two doctests onerror_enum!(an in-range enum compiles; an out-of-range one fails withE0080) andevery_contract_doc_fits_the_spec, which fails when a doc is longer than 1,024 bytes.cargo clippy --locked --all-targets -- -D warningson every touched crate, also withshort_wind_downandupgrade_probe: clean.--features upgrade_wasm with_wasm): vault 5, oracle 2, passed.Manual verification
stellar contract build, thenstellar contract info interface --wasm target/wasm32v1-none/release/async_vault.wasm: each function shows its doc.InvalidCustodian = 7075incontracts/async-vault/src/error.rsand runcargo check -p async-vault: it fails withVaultError::InvalidCustodian is outside its contract's error range.Built size (bytes) against the 131,072-byte limit:
async_vaultshare_tokennav_oraclecomplianceidentity_verifierBreaking changes
None. Signatures, types, events and error codes are unchanged; only the docs in each spec differ, so every Wasm hash changes.
Checklist
Screenshots
None.