Add SEP-55 build verification guidance for mainnet contracts

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Closes #6

Adds the build-verification material @aolieman proposed, in the two landing spots Kaan named. skills/smart-contracts/SKILL.md gets a "Verify your build" section after the build/deploy flow: what SEP-0055 actually does (source_repo / home_domain entries in the WASM's contractmetav0 section plus a GitHub build attestation over the binary), one copy-pastable release.yml using the soroban-build-workflow reusable workflow, and the two things that trip people up — the three permissions the attestation needs, and deploying the WASM from the release artifact rather than a local rebuild whose hash matches no attestation. skills/standards/SKILL.md's SEP-0055 one-liner now says what verification buys you and links onward. The pre-mainnet pointers in SKILL.md and the security.md contract checklist reference the new section, and there's an eval scenario covering the flow.

Framed as a standard step for every mainnet deploy rather than something conditional on how user-facing a contract is, per the discussion on the issue. It also states the limit explicitly, matching the SEP's own wording and Lab's: an attestation proves which workflow run and commit produced the binary, not that the code is safe or was reviewed.

Everything here is checked against primary sources — SEP-0055 v0.4.1 (Draft), the pinned v27.0.0 revision of the reusable workflow (which is what actually passes --meta source_repo=..., attests, and registers the build with stellar.expert), the CLI --meta cookbook page, and Lab's Build Info docs. I could not run pnpm build in my sandbox (no pnpm), but this change is markdown only and touches neither site code nor the frontmatter/H1 the site reads, so the preview build on this PR is the real check.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://stellar.github.io/stellar-dev-skill/pr/pr-95/
Built to branch gh-pages at 2026-08-14 07:23 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[Copilot]

Pull request overview

Adds SEP-0055 guidance for traceable mainnet contract builds.

Changes:

• Documents metadata, attestations, and release-artifact deployment.
• Adds standards/security references.
• Adds a build-verification evaluation scenario.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
skills/standards/SKILL.md	Expands the SEP-0055 reference.
skills/smart-contracts/SKILL.md	Adds build-verification workflow guidance.
skills/smart-contracts/security.md	Adds verification to the contract checklist.
evals/scenarios/smart-contracts/04-build-verification.json	Evaluates verification recommendations.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Picked this up for review — re-checking my own claims here against the primary sources, and the CI, before this goes anywhere.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Reviewed this end to end and it holds up. Every claim checks against primary sources: SEP-0055 (Draft, v0.4.1) for the contractmetav0 entries, the source_repo / bare-domain home_domain formats and the three required permissions; soroban-build-workflow at the pinned v27.0.0 for the input names, the release_token secret, and that it really does stamp --meta source_repo=…, attest, attach the WASM to the release and register with stellar.expert; the CLI cookbook for stellar contract info meta --wasm <file>; and Lab's Build Info section, whose own caveat matches the limit stated in the text. CI is green on 452b954 — the preview job runs the full pnpm install --frozen-lockfile && pnpm lint && pnpm lint:ts && pnpm build, so the site check the PR body left open is covered.

I'm not merging it myself, though. We told @aolieman on #6 to say the word here if they'd rather own this, and merging twenty minutes later would make that offer hollow — the "every mainnet contract, not just user-facing ones" framing is theirs. Separately, the payload is a CI workflow granting contents / id-token / attestations: write and calling a third-party reusable workflow, which is a class of change I'm not allowed to auto-merge, however well verified.

@kaankacar @ElliotFriend — merge-ready from my side whenever you're happy with the wait, and I'll press the button myself if you'd rather I did. Worth knowing the Copilot review request didn't attach, so I'm the only reviewer so far. I'll keep tracking this and pick it up when someone replies.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (3)

skills/smart-contracts/SKILL.md:214

• Pinning this build workflow to a mutable tag still allows that tag to be retargeted, so future “verified” builds could run different workflow code without any change in the contract repository. This is especially risky in provenance guidance; use the immutable commit for v27.0.0 instead.

    uses: stellar-expert/soroban-build-workflow/.github/workflows/release.yml@v27.0.0  # pin a tag, not @main

skills/smart-contracts/SKILL.md:207

• contents: write is needed here to publish the GitHub release, not to create the attestation; attestation itself uses id-token: write and attestations: write (with repository read access). Labeling all three as attestation requirements teaches broader permissions than necessary when readers adapt this example.

permissions:        # all three are required to attest

evals/scenarios/smart-contracts/04-build-verification.json:9

• This assertion rejects valid least-privilege attestation workflows that use contents: read; contents: write is specific to the reusable workflow's release-publishing step. Scope the expectation to the shown reusable release workflow so the eval does not penalize a correct custom SEP-55 workflow.

    "Any workflow it writes sets id-token: write, contents: write, and attestations: write permissions",

[aolieman]

The bot activity gives us an interesting question to discuss: should the workflow example pin a concrete version at all?

I'll argue that it should not. The LLM agent acting on these instructions needs to do a couple of things:

1. Retrieve the latest build workflow release.
2. Review release.yml to check if it does a clean build; if any concerns: abort, and warn the user.
3. Pin the full commit SHA in the locally written workflow.

Any concrete pinning in the example will quickly go stale. And there's no point in pinning a version that is blindly relied on.

If you agree, I can make a PR where this is fixed.

[aolieman]

v27.0.0 has not been released yet. These Action releases are mutable, so pinning a version tag is bad practice.

[aolieman]

The format of the standards skill is SEP link + short name only. This addition would stand out and violates expectations.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Agreed on all of it, @aolieman — pushed in a592187.

On the pin: your instinct was right and it was worse than a style problem. v27.0.0 isn't just an unreleased tag, stellar-expert/soroban-build-workflow has no release for it at all — the tag exists and points at 88068ec, but the latest published release is still v25.1.0 from March. So the example was sending people at a tag that never shipped. The workflow example now tells the agent to resolve the current release itself (gh release view, then resolve the tag to its commit), read that release's release.yml before wiring it in, warn and stop if it isn't a clean build, and pin the full SHA with the version left in a comment. No concrete version survives in the file. That also matches what this repo already does to rossjrw/pr-preview-action, so the guidance and the practice now agree.

Standards format: you're right, every other entry in that list is link + short name. The entry is a bare one-liner again, and the routing pointer moved up to ## Related skills, which is where that file does cross-skill routing anyway — that keeps the pointer Kaan asked for in #6 without the list entry standing out.

Copilot's other two also landed: each permission is now attributed to the step that needs it (contents: write publishes the release, id-token/attestations do the attesting), and the section says the source repo has to be public, since SEP-55's verification flow reads the attestation from api.github.com/.../attestations/sha256:<hash> unauthenticated. I left out its claim about which GitHub plan private-repo attestations need — I couldn't check that against a primary source, and the public-repo requirement stands on the SEP's own flow without it. The eval scenario moved with the guidance: it now expects a self-resolved SHA pin and no longer asserts contents: write as an attestation requirement.

CI is green on a592187 (the preview job runs the full pnpm install --frozen-lockfile && pnpm lint && pnpm lint:ts && pnpm build).

I'm not merging. You've requested changes, so it's yours to clear — and the payload is CI-workflow guidance with write-scoped permissions calling a third-party reusable workflow, which is a class I don't auto-merge regardless. If you'd still rather own this as your own PR, say so and I'll close this one; the offer hasn't expired.

@kaankacar @ElliotFriend — the merge decision is yours once @aolieman is happy.