Fix outdated Stylus SDK API patterns and versions across docs by anegg0 · Pull Request #3189 · OffchainLabs/arbitrum-docs

anegg0 · 2026-04-02T00:13:45Z

Summary

Systematic fact-check of Stylus documentation against the current stylus-sdk-rs source code (v0.10.2, Rust 1.91.0). Fixes deprecated API patterns and outdated version references.

Deprecated API replacements

evm::log() → self.vm().log() (removed in SDK v0.10)
msg::sender() → self.vm().msg_sender()
msg::value() → self.vm().msg_value()
block::timestamp() → self.vm().block_timestamp()
#[external] → #[public] (attribute renamed)
ensure! macro → explicit if checks (macro doesn't exist in SDK)
transfer_eth(to, amount) → transfer_eth(host, to, amount) (host arg added)
RawDeploy::new(self.vm()).value(amount).deploy(&bytecode, salt) → RawDeploy::new().salt(salt).deploy(self.vm(), &bytecode, amount)

Version updates (verified against stylus-sdk-rs Cargo.toml)

Rust minimum: 1.81/1.88 → 1.91 (8 files)
stylus-sdk dev-dependency: 0.8.4 → 0.10.2
rust-toolchain.toml channel: "stable" → "1.91.0"

Stale link fixes

developer.arbitrum.io/time → internal doc path
developer.arbitrum.io/arbos/l1-to-l2-messaging → internal doc path

Migration table fix (choose-your-path.mdx)

ensure!(condition, Error) → Result<T, E> + ?
Derive Erase trait → self.vm().log(Event{})
impl with initialization → #[constructor] method

Files changed (20 Stylus docs)

stylus/advanced/rust-to-solidity-differences.mdx
stylus/advanced/hostio-exports.mdx
stylus/quickstart.mdx
stylus/using-cli.mdx
stylus/concepts/vm-differences.mdx
stylus/cli-tools/overview.mdx
stylus/cli-tools/debugging-tx.mdx
stylus/fundamentals/testing-contracts.mdx
stylus/fundamentals/prerequisites.mdx
stylus/fundamentals/global-variables-and-functions.mdx
stylus/fundamentals/project-structure.mdx
stylus/fundamentals/contracts.mdx
stylus/fundamentals/choose-your-path.mdx
stylus/best-practices/gas-optimization.mdx
stylus/how-tos/exporting-abi.mdx
stylus/how-tos/trait-based-composition.mdx
stylus/how-tos/using-constructors.mdx
stylus/how-tos/importing-interfaces.mdx
stylus/troubleshooting/common-issues.mdx

Test plan

yarn build passes with no broken links
Spot-check code examples against stylus-sdk-rs v0.10.2 API

Not addressed (needs full rewrite in separate PRs)

stylus/cli-tools/commands-reference.mdx — CLI commands completely outdated
stylus/best-practices/security.mdx — 20+ deprecated API instances
stylus/concepts/public-preview-expectations.mdx — says Stylus is "release-candidate"
stylus/reference/rust-sdk-guide.md — old reference with deprecated patterns

🤖 Generated with Claude Code

The example showed RawDeploy::new(self.vm()).value(amount).deploy() but the actual API is RawDeploy::new().salt(salt).deploy(host, code, endowment). Verified against stylus-sdk-rs source.

- stylus/quickstart: update Rust minimum version 1.88→1.91 (matches SDK's rust-version), pin rust-toolchain.toml to 1.91.0 instead of "stable", update stylus-sdk dev-dependency 0.8.4→0.10.2 - 03-public-chains: update deprecated Stylus testnet section, fix grammar - arbitrum-bridge/01-quickstart: fix typo

- vm-differences: fix Vec<u256> -> Vec<U256> in code example - testing-contracts: update minimum Rust version 1.81→1.91 (matches SDK's rust-version in Cargo.toml)

- prerequisites: update expected rustc version 1.81→1.91 - global-variables-and-functions: replace developer.arbitrum.io external links with internal doc paths

The Stylus SDK v0.10 removed the evm module and msg module. The correct patterns are self.vm().log() for events and self.vm().msg_sender() for caller address. Also fixes incorrect migration table entries in choose-your-path (ensure! doesn't exist, Erase trait is wrong). Files updated: - project-structure.mdx - exporting-abi.mdx - gas-optimization.mdx - choose-your-path.mdx

- gas-optimization: replace block::timestamp() with self.vm().block_timestamp(), replace #[external] with #[public] on impl block, replace ensure! with explicit if-checks - exporting-abi: replace remaining msg::sender()/msg::value() with self.vm() equivalents

Bulk update Rust toolchain versions from 1.81/1.88 to 1.91 to match the SDK's minimum supported Rust version (rust-version = "1.91.0" in stylus-sdk Cargo.toml). Files updated: - trait-based-composition.mdx - using-cli.mdx - using-constructors.mdx - importing-interfaces.mdx - troubleshooting/common-issues.mdx

- common-issues.mdx: replace #[external] with #[public] in ABI troubleshooting example - contracts.mdx: replace all msg::value() with self.vm().msg_value(), update transfer_eth() to include host arg, fix function signatures - debugging-tx.mdx: replace #[external] with #[public]

vercel · 2026-04-02T00:13:50Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
arbitrum-docs	Ready	Preview	Apr 2, 2026 7:47pm

Copilot

Pull request overview

This PR updates the Stylus documentation to match the current stylus-sdk-rs API surface (v0.10.2) and Rust toolchain requirements (1.91.x), replacing deprecated patterns and refreshing version/link references across the Stylus docs set.

Changes:

Updated Rust toolchain guidance and pinned versions (1.91 / 1.91.0) and stylus-sdk dev-dependency references.
Replaced deprecated SDK API usages in examples (e.g., msg::* → self.vm().*, evm::log → self.vm().log, #[external] → #[public], updated transfer_eth/RawDeploy call shapes).
Fixed stale external links by pointing to current internal doc paths.

Reviewed changes

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

Show a summary per file

File	Description
docs/stylus/advanced/rust-to-solidity-differences.mdx	Updates deployment example to current `RawDeploy` API shape.
docs/stylus/advanced/hostio-exports.mdx	Refreshes Arbitrum reference links to internal docs.
docs/stylus/quickstart.mdx	Pins Rust toolchain to 1.91.0 and updates `stylus-sdk` dev-dependency to 0.10.2.
docs/stylus/using-cli.mdx	Updates Rust toolchain prerequisites and WASM target setup examples to 1.91.
docs/stylus/concepts/vm-differences.mdx	Fixes outdated type usage in a code example (`U256`).
docs/stylus/cli-tools/overview.mdx	Updates Rust toolchain prerequisites to 1.91+.
docs/stylus/cli-tools/debugging-tx.mdx	Switches example attribute from `#[external]` to `#[public]`.
docs/stylus/fundamentals/testing-contracts.mdx	Updates Rust toolchain prerequisite version to 1.91+.
docs/stylus/fundamentals/prerequisites.mdx	Updates expected `rustc` version output to 1.91.0+.
docs/stylus/fundamentals/global-variables-and-functions.mdx	Updates L1↔L2 messaging/time links to internal doc paths.
docs/stylus/fundamentals/project-structure.mdx	Updates event logging and sender access patterns to `self.vm()` APIs.
docs/stylus/fundamentals/contracts.mdx	Updates ETH transfer examples to newer `transfer_eth` calling pattern and `msg_value()` access via VM.
docs/stylus/fundamentals/choose-your-path.mdx	Updates migration table entries to current SDK idioms (`self.vm()`, `#[constructor]`, logging).
docs/stylus/best-practices/gas-optimization.mdx	Updates timestamp/sender/logging examples to new VM-based APIs and removes `ensure!` in one section.
docs/stylus/how-tos/exporting-abi.mdx	Updates sender/value/event logging examples to `self.vm()` APIs and reduces repeated lookups.
docs/stylus/how-tos/trait-based-composition.mdx	Updates Rust toolchain prerequisite + WASM setup commands to 1.91.
docs/stylus/how-tos/using-constructors.mdx	Updates Rust toolchain prerequisite + WASM setup commands to 1.91.
docs/stylus/how-tos/importing-interfaces.mdx	Updates Rust toolchain prerequisite + WASM setup commands to 1.91.
docs/stylus/troubleshooting/common-issues.mdx	Updates toolchain/attribute examples to 1.91 and `#[public]`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/stylus/fundamentals/project-structure.mdx

Copilot · 2026-04-02T19:37:17Z

docs/stylus/fundamentals/contracts.mdx

 ```rust
 // These are equivalent:
-transfer_eth(recipient, value)?;
+transfer_eth(self.vm(), recipient, value)?;
 call(Call::new_in(self).value(value), recipient, &[])?;


This “equivalent under the hood” snippet isn’t self-contained: recipient and value are undefined, which makes it hard to copy/paste and verify. Consider either defining them in the snippet (e.g., as parameters/locals) or explicitly marking them as placeholders in comments.

@copilot apply changes based on this feedback

Added explicit type annotations and placeholder values for recipient and value in commit 2f2b002 so the snippet is self-contained:

// `recipient` is an Address and `value` is a U256 amount in wei let recipient: Address = /* ... */; let value: U256 = /* ... */; transfer_eth(self.vm(), recipient, value)?; call(Call::new_in(self).value(value), recipient, &[])?;

Added type annotations as a comment in the snippet: (recipient: Address, value: U256) so readers understand the expected types without needing to trace the surrounding context. Commit: 4d87446

Copilot · 2026-04-02T19:37:17Z

docs/stylus/best-practices/gas-optimization.mdx

 // ✅ Extract common logic to internal functions
 impl MyContract {
    // Internal helper (no ABI encoding overhead)
    fn internal_validate(&self, addr: Address, amount: U256) -> Result<(), Vec<u8>> {
-        ensure!(!addr.is_zero(), "Invalid address");
-        ensure!(amount > U256::ZERO, "Invalid amount");
+        if addr.is_zero() {
+            return Err(b"Invalid address".to_vec());


This file still contains several ensure!(...) examples (e.g., cleanup/transfer/add_to_balance sections). Since this PR replaces ensure! with explicit if checks for the current SDK, please update the remaining ensure! usages in this doc for consistency and to avoid readers copying non-compiling code.

@copilot apply changes based on this feedback

Replaced all four remaining ensure!() usages in gas-optimization.mdx with explicit if checks in commit 2f2b002. The affected sections were: cleanup (balance check), transfer (valid amount check), and add_to_balance_bad (zero and overflow checks).

Replaced all four remaining ensure! usages in this file with explicit if checks + return Err(...) patterns (lines 124, 241, 252, 255). Commit: 4d87446

docs/stylus/troubleshooting/common-issues.mdx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

anegg0 added 10 commits April 1, 2026 17:13

Fix incorrect RawDeploy API in Rust-to-Solidity differences doc

a6c79a8

The example showed RawDeploy::new(self.vm()).value(amount).deploy() but the actual API is RawDeploy::new().salt(salt).deploy(host, code, endowment). Verified against stylus-sdk-rs source.

Fix type error and outdated Rust version in Stylus docs

ee0be06

- vm-differences: fix Vec<u256> -> Vec<U256> in code example - testing-contracts: update minimum Rust version 1.81→1.91 (matches SDK's rust-version in Cargo.toml)

Fix outdated Rust version and stale links in Stylus docs

570d546

- prerequisites: update expected rustc version 1.81→1.91 - global-variables-and-functions: replace developer.arbitrum.io external links with internal doc paths

Update Rust version in CLI tools overview (1.81→1.91)

ab527dc

Replace developer.arbitrum.io URLs with internal links in hostio-exports

cf8e934

anegg0 added Needs SME review slop starter Generated draft to start from labels Apr 2, 2026

vercel bot had a problem deploying to Preview April 2, 2026 00:18 Failure

anegg0 mentioned this pull request Apr 2, 2026

Fix outdated docs: build guide versions, comparison overview, RPC methods #3188

Merged

2 tasks

anegg0 requested a review from Copilot April 2, 2026 19:32

anegg0 assigned rory-ocl Apr 2, 2026

Copilot started reviewing on behalf of anegg0 April 2, 2026 19:32 View session

Merge branch 'master' into fix-stylus-docs-inaccuracies

61bece0

Copilot AI reviewed Apr 2, 2026

View reviewed changes

vercel bot had a problem deploying to Preview April 2, 2026 19:38 Failure

anegg0 and others added 3 commits April 2, 2026 12:40

fix broken links in stylus docs

136fb06

Update docs/stylus/fundamentals/project-structure.mdx

8df56ad

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/stylus/troubleshooting/common-issues.mdx

f0f89b8

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

vercel bot deployed to Preview April 2, 2026 19:47 View deployment

Copilot started work on behalf of anegg0 April 2, 2026 20:21 View session

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix outdated Stylus SDK API patterns and versions across docs#3189

Fix outdated Stylus SDK API patterns and versions across docs#3189
anegg0 wants to merge 14 commits intomasterfrom
fix-stylus-docs-inaccuracies

anegg0 commented Apr 2, 2026

Uh oh!

vercel bot commented Apr 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

anegg0 Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

anegg0 Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

anegg0 commented Apr 2, 2026

Summary

Deprecated API replacements

Version updates (verified against stylus-sdk-rs Cargo.toml)

Stale link fixes

Migration table fix (choose-your-path.mdx)

Files changed (20 Stylus docs)

Test plan

Not addressed (needs full rewrite in separate PRs)

Uh oh!

vercel bot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

anegg0 Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

anegg0 Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel bot commented Apr 2, 2026 •

edited

Loading