docs: replace the stale m1 docs with the current architecture - #80
Open
luchobonatti wants to merge 8 commits into
Open
docs: replace the stale m1 docs with the current architecture#80luchobonatti wants to merge 8 commits into
luchobonatti wants to merge 8 commits into
Conversation
roadmap-m1.md and m1-brief.md describe a synchronous 1:1 vault that the current architecture replaced. Both were still cited as authoritative by CLAUDE.md and AGENTS.md, so an agent reading either was pointed at a design that no longer holds. Version pins are read from Cargo.toml, rust-toolchain.toml and flake.nix instead. The architecture is maintained outside the repository.
AGENTS.md still described a synchronous OZ vault: deposit and withdraw priced at call time, shares 1:1, exit via withdraw/redeem. It also called the repo bootstrap-only, which stopped being true when the contract crates landed, and pointed at a cargo test -p vault crate that does not exist. Drops three gotchas that no longer apply: the SEP-56 vault wiring and its require_auth caveat, a motion dependency the app does not have, and the uncommitted-Cargo.lock note.
luchobonatti
added
documentation
There was a problem hiding this comment.
🟡 Changes recommended
AGENTS.md’s introduction says it avoids restating dependency versions, but later still includes version-specific dependency guidance, making the document internally inconsistent.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR removes milestone documents that describe a superseded “priced-at-call-time” vault model and updates the repository’s contributor-facing guidance to reflect the request lifecycle model and current repo contents.
Changes:
- Deleted
docs/roadmap-m1.mdanddocs/m1-brief.mdand removed any references to them. - Updated
AGENTS.mdto describe the pending/priced/claimed request lifecycle, current workspace layout, and corrected build/test guidance. - Updated
CLAUDE.mdto point dependency/version readers to manifests/toolchain files rather than removed docs.
File summaries
| File | Description |
|---|---|
| docs/roadmap-m1.md | Removed superseded milestone roadmap document. |
| docs/m1-brief.md | Removed superseded M1 technical brief document. |
| CLAUDE.md | Removed pointer to deleted roadmap; clarified where to find version/toolchain info. |
| AGENTS.md | Reframed repo guidance around request lifecycle and current workspace structure; updated build/test notes and gotchas. |
Review details
- Files reviewed: 4/4 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+6
to
+8
| It deliberately does **not** restate dependency versions — those are pinned in | ||
| `Cargo.toml`, `rust-toolchain.toml` and `flake.nix`, and a second copy would go | ||
| stale. The architecture is maintained outside this repository. Work items live in |
The superseded m1 docs left the repo with no design document, so CLAUDE.md and AGENTS.md had nothing to point at. Adds the current architecture and points both files at it.
luchobonatti
changed the title
6 tasks
CI runs prettier . --check and the new file failed it.
WIP project: exact versions and crate lists rot faster than the file is read. Points at the manifests and the workspace instead, and resolves the review note about the intro promising no versions while the gotchas carried one.
The doc-wins-always rule was contradicted the same day it was written: docs/architecture.md moved to match the nav-oracle contract, not the reverse. It now wins on the what and requires an explicit resolution on the how, so a better mechanism in a contracts PR is not wrong by definition. Also retitles the second invariant to what it actually guarantees, and uses investor rather than holder to match the architecture.
hpmaxi
reviewed
Sep 7, 2026
Reviewer note: naming a Nix file as where to read versions reads as requiring Nix. Cargo.toml and rust-toolchain.toml cover it without that.
hpmaxi
approved these changes
Sep 8, 2026
Comment on lines
+15
to
+16
| you claim the result. A priced claim is never re-priced, and a covered cash | ||
| claim cannot be blocked by a pause or by losing your allowlist place. |
Contributor
There was a problem hiding this comment.
Maybe this edge cases should be in another section, not as the brief description
| contract, and a Playwright e2e harness. Read the workspace `Cargo.toml` for the | ||
| current members rather than trusting a list here. | ||
|
|
||
| The vault contract itself is not written yet, so the request lifecycle above has |
Contributor
There was a problem hiding this comment.
This section is going to be updated on each PR merged? Maybe is better to just remove it
| test USDC from Circle's faucet (pick Stellar) after establishing the | ||
| trustline. | ||
| - A SEP-56 vault is **not** the base here: its interface assumes the price | ||
| exists at call time, which a request lifecycle cannot express. Only OZ's |
Contributor
There was a problem hiding this comment.
I would remove the OZ comment, maybe mention that the base is RWA for the share-token module, but not sure. Mentioning that SEP-56 is not the base is good to avoid going to the sync path
| 4. **Attested NAV.** The reporter attests the share price itself, computed | ||
| off-chain from the deployed value and the vault's public figures under a | ||
| documented methodology. The contract validates, stores and exposes it. Every | ||
| on-chain operation preserves that price by construction: a priced deposit |
Contributor
There was a problem hiding this comment.
a priced deposit ...
that sentence is a bit strange. On deposit only assets are moved.
hpmaxi
requested changes
Sep 8, 2026
| ```text | ||
| share_price = (deployed_value + onchain_reserve - committed) / share_supply | ||
| ``` | ||
|
|
Contributor
There was a problem hiding this comment.
We don't know how is calculated off-chain, is possible that include a fee, that the onchain_reserve is not part because can be deployed on demand, etc.
| | Surface | Authority | Cadence | Operations | | ||
| | ------------- | ------------------------------------- | ------------------- | --------------------------------------------------------------------------- | | ||
| | Cycle | attestation, treasury; anyone settles | Continuous | Attestations, funding, transfers to and from the custodian, settlement | | ||
| | Compliance | compliance | Continuous | Allowlist, freeze/unfreeze, forced transfer, recovery via Manager | |
Contributor
There was a problem hiding this comment.
If we use a thirdparty for the compliance (providing an address); we are not going to be able to change eg. freeze/unfreeze
| | Phase | Deliverables | Evidence of completion | | ||
| | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | **1: Attested valuation and request pricing** | Valuation oracle with guardrails, freshness and pause; request lifecycle with escrow, cancellation and pricing-time mint and burn; public kit spec | Accounting property tests green in CI (price preserved by deposits, redemptions and custodian transfers; cancellation; rounding); multisig signing of privileged operations verified end to end through the coordinator | | ||
| | **2: Split accounting and redemption** | Shortfall exposure; FIFO redemption coverage; exit-only cash path; SEP-57 integration (compliance module, delisted-investor path); threat model and monitoring plan | Settlement cost measured at 1, 10, 100 and 1,000 pending requests; SEP-57 path demonstrated end to end on testnet | |
Contributor
There was a problem hiding this comment.
settlement cost measured? Is some type of e2e test
6 tasks
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 #71
The repository taught a design it had already replaced.
docs/roadmap-m1.mdanddocs/m1-brief.mddescribe a synchronous 1:1 vault priced at call time, and both were cited as authoritativeCLAUDE.mdnamed the roadmap as where decisions live,AGENTS.mdlinked both.AGENTS.mdthen taught the same old model in its own body, called the repo bootstrap-only after the contract crates had landed, and documented a test command against a crate that does not exist.This replaces all of it with the current architecture, so there is one design document and every pointer resolves to it.
Changes
docs/architecture.mdis the design source of truth; where code disagrees with it, the document winsAGENTS.mddescribes the request lifecycle — pending, priced, claimed — and the five authoritiesAGENTS.mdstates what the repo actually contains, including that the vault contract is not written yetAcceptance criteria
docs/roadmap-m1.mdanddocs/m1-brief.mdare removedAGENTS.mddescribes the request lifecycle: pending, priced, claimedAGENTS.mdstates the real repo contents and that the vault contract is not written yetBreaking changes
None.
Checklist
Screenshots
None.