Skip to content

Document that the network rejects contracts built for a newer protocol - #3149

Open
stellar-doxie[bot] wants to merge 2 commits into
mainfrom
docs-agent/3145-newer-protocol-rejection
Open

stellar-doxie[bot] wants to merge 2 commits into
mainfrom
docs-agent/3145-newer-protocol-rejection

Conversation

@stellar-doxie

@stellar-doxie stellar-doxie Bot commented Nov 14, 2026

Copy link
Copy Markdown
Contributor

🤖 Automated message from the Stellar Triage Bot.

Closes #3145

Working this because it is a Raven-filed issue (raven label, finding sd-107). The Environment Meta sections said the interface version "should match" the host. This PR states the rule the host enforces and the error a reader sees.

Why this matters

Protocol 30 is on Testnet and Mainnet still runs 29. A contract built with a Protocol 30 SDK uploads on Testnet and fails on Mainnet with an error no page explains.

Changes

  • docs/learn/fundamentals/contract-development/overview.mdx: the rule, the error, the Testnet-first case, and a link to Software Versions.
  • docs/tools/sdks/build-your-own.mdx: the full rule for SDK authors, including the pre-release number checks.
  • docs/networks/software-versions.mdx: one paragraph in the intro warning. It names no version, so it does not go stale.
  • Also on build-your-own.mdx: the Contract Spec section said "To view the Contract Meta". Fixed to "Contract Spec". Fixed two typos ("proceeding", "mappins").

Sweep

  • Searched docs/, snippets/, openapi/, openrpc/ and .mintlify/skills/ for: "interface version", "should match the version", "newer than host", "newer protocol", "pre-release", "protocol number", "contractenvmetav0", "env-meta", "built for a newer/older".
  • Only the two "should match" sentences state the claim. Both are fixed.
  • docs/tools/cli/stellar-cli.mdx:766 describes env-meta. It is a committed copy of the CLI help and makes no claim about the rule. Left as is.
  • .mintlify/skills/: no hit.

Verified

Verified against stellar-cli 30.0.1 and rs-soroban-env v30.0.0 (newest releases). The issue cited rs-soroban-env main at 5fdf6e6. The pages pin no version.

  • Host rule: stellar/rs-soroban-env@v30.0.0 soroban-env-host/src/vm/parsed_module.rs:308-387 (check_contract_interface_version). Older protocol needs pre-release 0. Current protocol needs a matching pre-release. Newer protocol fails with "contract protocol number is newer than host".
  • The check runs on upload: soroban-env-host/src/host/lifecycle.rs:338-351 builds a throwaway VM, which parses the env meta.
  • The rule in the source comment: soroban-env-common/src/meta.rs:16-20 ("a host will only run contracts built for same-or-older protocol versions").
  • Live reproduction. Mainnet getLatestLedger returned protocolVersion: 29. I built the stellar contract init hello-world contract with soroban-sdk =30.0.0-rc.1 (stellar contract info env-meta shows Protocol v30). stellar contract upload --build-only --ignore-checks | stellar tx simulate on Mainnet failed with Error(WasmVm, InvalidInput) and the diagnostic "contract protocol number is newer than host", 30.
  • Control: the same contract built with soroban-sdk 29 (Protocol v29) simulated an upload on Mainnet with no error.
  • pnpm install --frozen-lockfile, pnpm format:mdx, pnpm check (includes check:links): all passed. The OpenAPI warnings in the output are pre-existing.

Not verified

  • I did not run the build-your-own pre-release cases on a network. They are verified from source only.
  • stellar-cli 30.0.1 also refuses a release-candidate SDK build on Mainnet unless you pass --ignore-checks. The pages do not mention that check. I left it out because it covers only release candidates.

Overlaps

Raven handoff (after merge)

  • Finding: sd-107.
  • Pages to recheck: /docs/learn/fundamentals/contract-development/overview, /docs/tools/sdks/build-your-own, /docs/networks/software-versions.
  • A recheck should find contract protocol number is newer than host on the first two pages, and "Mainnet upgrades to a new protocol after Testnet" on Software Versions.

The Environment Meta sections said the interface version "should match" the host. State the rule the host enforces and the error a reader sees, and point readers at Software Versions for the SDK that matches their network.
@mintlify

mintlify Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
stellar-docs 🟢 Ready View Preview Nov 14, 2026, 4:20 PM

@stellar-doxie stellar-doxie Bot added the bot:ready-to-merge Bot verified and approved; waiting for a maintainer to merge label Nov 14, 2026
@stellar-doxie

stellar-doxie Bot commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Automated message from the Stellar Triage Bot.

Reviewing because this is my own PR for #3145.

Verified: the host rule and the error text match rs-soroban-env v30.0.0, and the preview renders all three pages. Ready to merge.
Checked against rs-soroban-env v30.0.0 and soroban-sdk 29.0.1. The issue cited rs-soroban-env main at 5fdf6e6. The pages pin none.

What I checked
  • Added in review: split a comma splice on build-your-own.mdx:32, a line this PR already edits (b4f436f).
  • Not in the PR body: the check also runs at execution, not only on upload. rs-soroban-env@v30.0.0 soroban-env-host/src/vm/module_cache.rs:178 calls ParsedModule::new with the ledger protocol. This backs "when it runs" on build-your-own.mdx.
  • Not in the PR body: rs-soroban-sdk@v29.0.1 soroban-sdk/src/lib.rs:162-163 writes the env meta::XDR into contractenvmetav0. soroban-sdk 29.0.1 pins env 29.0.1, whose current protocol is 29 (meta.rs:62).
  • Live state on 2026-11-14: Horizon reports Mainnet on protocol 29 and Testnet on 30.
  • The live Mainnet upload reproduction in the PR body was not repeated in this review. The page claims rest on the source lines above.
  • SWEEP repeated from scratch: no other copy of the "should match" claim.
  • Add Protocol 30 (Bell) testnet versions #3138 also edits software-versions.mdx, in a separate hunk. Either merge order works.
  • Checks at b4f436f: all pass.

This branch was successfully deployed

1 active deployment
staging — b4f436f0 Deployed Nov 14, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bot:ready-to-merge Bot verified and approved; waiting for a maintainer to merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs do not say that the network rejects a contract built for a newer protocol

0 participants