Rewrite README to be SEP-58-native, aligned with the architecture doc (STE-56)#8
Merged
yvesfracari merged 3 commits intoJun 12, 2026
Conversation
The Docker path never ran end to end: the official stellar-cli release binary links libdbus-1.so.3, which rust:1.91.1-bookworm doesn't ship, so the image failed to build; and with --network=none the in-container cargo could not fetch the dependency graph, so even a successful image couldn't compile anything. Install libdbus-1-3, and prefetch the fixture workspace's locked dependency graph into the image at build time (manifests + Cargo.lock only, stub lib.rs for target discovery) — the staged source-acquisition model from docs/ARCHITECTURE.md §8: dependencies arrive while the image is built, the compile runs with no network. Build context moves to the repo root so the lockfile is reachable; a whitelist .dockerignore keeps the context to the manifests. Verified: docker build + network-isolated docker run reproduce the on-chain hash 6fe7bd58…, and both 'verify --tarball --docker' and 'scripts/verify.sh --docker' return FULL_MATCH with exit 0.
A grant reviewer opening the repo now sees a project built around SEP-58 end to end, consistent with docs/ARCHITECTURE.md and the code shipped in STE-53/54/55: - Lead with SEP-58; field→pipeline mapping table for all six fields and a source-mode table matching reader/src/sep58.ts. SEP-46 stays documented as the meta transport, not the headline. - SEP-55 reframed as the complementary trust level (provenance question vs reproduction question), exposed distinctly — no inferior framing. - Build image story repositioned: SDF stellar-cli-docker images via bldimg + docker/allowlist.json as the primary path, this repo's pinned Dockerfile as the publicly-auditable fallback, with the eviction-downgrades semantics spelled out. - New capabilities documented with runnable examples: SEP-58 fields and source-mode inference in 'read', the imageTrust dimension on verify results, and the content-addressed tarball flow (digest gate first). - Roadmap replaced with the ARCHITECTURE.md §11 milestones including their done-when tests. - Kept: reproducibility caveats (extended with the fixture's no-SEP-58-metadata honesty note), live testnet fixture table, verdict model, quick start. Every command in the README was executed and passes; the tarball example returns FULL_MATCH with exit 0 against the live testnet fixture.
…shed The intro claimed rebuilds run in a digest-pinned image, but the repo's own image has no registry digest yet (allowlist digest: null, manifest baseImageDigest TODO). Soften the claim and restore the explicit caveat the rewrite had dropped: digest references are the requirement, and the digest is recorded in the manifest and allowlist once the image is published.
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
1 participant
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.
What
Rewrites the README so a grant reviewer opening the repo sees a project natively built around SEP-58, consistent with docs/ARCHITECTURE.md and reflecting the code shipped in STE-53/54/55. Also fixes the pinned Docker image, which had never actually worked end to end (required to make every README command runnable).
README changes
bldimg,bldopt,source_repo,source_rev,tarball_url,tarball_sha256) with honest MVP/roadmap status per step, plus a source-mode table matchingreader/src/sep58.tsexactly (public-repo,hosted-tarball,hosted-tarball-unpinned,content-addressed,none). SEP-46 stays documented as the meta transport, not the headline.stellar-cli-dockerimages viabldimg+docker/allowlist.jsonare the primary path (sdf-trusted); this repo's pinned Dockerfile is the interim/fallback (publicly-auditable). Eviction-downgrades-never-deletes semantics documented.read, theimageTrustdimension on verify results, and the content-addressed tarball flow (digest gate first,--dockerrebuild).Docker image fixes (prerequisite for "all commands run")
The documented Docker path was broken in two ways:
libdbus-1.so.3, absent fromrust:1.91.1-bookworm→ installlibdbus-1-3.--network=nonemade every in-container build fail: cargo had no registry and couldn't fetch. Fixed with the staged source-acquisition model from ARCHITECTURE.md §8 — the fixture's locked dependency graph is prefetched into the image at build time (manifests +Cargo.lockonly; no contract code compiled into the image). Build context moves to the repo root (docker build -f docker/Dockerfile … .) with a whitelist.dockerignore.Verification (every README command executed)
cargo test --locked/stellar contract build --locked6fe7bd58…pnpm install && pnpm test && pnpm run buildread --id CDVSGPL…noneverify --id … --wasm …FULL_MATCH, exit 0verify --id … --tarball … --tarball-sha256 … --dockerFULL_MATCH, exit 0docker build -f docker/Dockerfile …+docker run --network=none …6fe7bd58…scripts/verify.sh …(plain and--docker, and tarball form)FULL_MATCH, exit 0SOROSCAN_INTEGRATION=1 … integration.testnet.test.tsOne caveat surfaced and documented in the quick start: tarball mode without
--dockerrebuilds in a temp dir, where directory-scoped version managers (asdf/direnv) don't see.tool-versions— so the pinned rust must be the active toolchain outside the repo tree.Closes STE-56