Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: change stylus programs to stylus contracts #1787

Merged
merged 2 commits into from
Nov 5, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion arbitrum-docs/stylus/concepts/stylus-gas.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Stylus introduces new pricing models for WASM programs. Intended for high-comput
There are, however, minor overheads to using Stylus that may matter to your application:

- The first time a WASM is deployed, it must be _activated_. This is generally a few million gas, though to avoid testnet DoS, we've set it to a fixed 14 million. Note that you do not have to activate future copies of the same program. For example, the same NFT template can be deployed many times without paying this cost more than once. We will soon make the fees paid depend on the program, so that the gas used is based on the complexity of the WASM instead of this very conservative, worst-case estimate.
- Calling a Stylus program costs 128-2048 gas. We're working with Wasmer to improve setup costs, but there will likely always be some amount of gas one pays to jump into WASM execution. This means that if a contract does next to nothing, it may be cheaper in Solidity. However if a contract starts doing interesting work, the dynamic fees will quickly make up for this fixed-cost overhead.
- Calling a Stylus contract costs 128-2048 gas. We're working with Wasmer to improve setup costs, but there will likely always be some amount of gas one pays to jump into WASM execution. This means that if a contract does next to nothing, it may be cheaper in Solidity. However if a contract starts doing interesting work, the dynamic fees will quickly make up for this fixed-cost overhead.

Though conservative bounds have been chosen for testnet, all of this is subject to change as pricing models mature and further optimizations are made. Since gas numbers will vary across updates, it may make more sense to clock the time it takes to perform an operation rather than going solely by the numbers reported in receipts.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import PublicPreviewBannerPartial from '../../partials/_public-preview-banner-pa

[Arbitrum Stylus](../stylus-gentle-introduction.md) is a new technology developed for Arbitrum chains which gives smart contract developers superpowers. With Stylus, developers can write EVM-compatible smart contracts in many different programming languages, and reap massive performance gains. Stylus slashes fees, with performance gains ranging from 10-70x, and memory efficiency gains as high as 100-500x.

This is possible thanks to [WebAssembly](https://www.infoworld.com/article/3291780/what-is-webassembly-the-next-generation-web-platform-explained.html) technology, which all Stylus programs compile to. Stylus smart contracts live under the **same Ethereum state trie** in Arbitrum nodes, and can fully interoperate with Solidity or Vyper EVM smart contracts. With Stylus, developers can write smart contracts in Rust that talk to Solidity and vice versa without any limitations.
This is possible thanks to [WebAssembly](https://www.infoworld.com/article/3291780/what-is-webassembly-the-next-generation-web-platform-explained.html) technology, which all Stylus contracts compile to. Stylus smart contracts live under the **same Ethereum state trie** in Arbitrum nodes, and can fully interoperate with Solidity or Vyper EVM smart contracts. With Stylus, developers can write smart contracts in Rust that talk to Solidity and vice versa without any limitations.

Today, the Stylus testnet also comes with 2 officially supported [SDKs](../reference/stylus-sdk.md) for developers to write contracts in the [Rust](../reference/rust-sdk-guide.md) or [C](https://github.com/OffchainLabs/stylus-sdk-c) programming languages.

Expand Down Expand Up @@ -110,7 +110,7 @@ Calling the contract via RPC should simply return the value `0` as we programmed

### Reading input and writing output data

Smart contracts on Ethereum, at the bare minimum, can take in data and output data as bytes. Stylus programs are no different, and to do anything useful, we need to be able to read from user input also write our output to the caller. To do this, the Stylus runtime provides all Stylus programs with two additional, useful host-ios:
Smart contracts on Ethereum, at the bare minimum, can take in data and output data as bytes. Stylus contracts are no different, and to do anything useful, we need to be able to read from user input also write our output to the caller. To do this, the Stylus runtime provides all Stylus contracts with two additional, useful host-ios:

```c
pub extern "vm_hooks" fn read_args(dest: *u8) void;
Expand Down Expand Up @@ -277,7 +277,7 @@ Our uncompressed size is big because of that giant array of booleans, but the pr

An instance of this program has been deployed to the Stylus testnet at address `0x0c503Bb757b1CaaD0140e8a2700333C0C9962FE4`

## Interacting With Stylus Programs Using Ethers-rs
## Interacting With Stylus contracts Using Ethers-rs

An example is included in this repo under `rust-example` which uses the popular [ethers-rs](https://github.com/gakonst/ethers-rs) library to interact with our prime sieve contract on the Stylus testnet. To run it, do:

Expand Down
8 changes: 4 additions & 4 deletions arbitrum-docs/stylus/how-tos/verifying-contracts.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: 'How to verify contracts for stylus programs'
title: 'How to verify contracts for Stylus contracts'
sidebar_label: 'Verify contracts'
description: 'Learn how to verify stylus contracts'
author: rauljordan
Expand All @@ -16,7 +16,7 @@ This page will walk you through how to verify your Stylus contracts locally. Sty

## Background

Stylus programs written in Rust and deployed onchain can be verified against a local codebase by using the `cargo stylus` tool.
Stylus contracts written in Rust and deployed onchain can be verified against a local codebase by using the `cargo stylus` tool.

## Goals

Expand Down Expand Up @@ -80,7 +80,7 @@ This command will run the verification pipeline through a Docker environment, re

## How it works

On deployment, a `keccak256` hash is created from the contents of all Rust source files in the project, sorted by file path, along with a rust-toolchain.toml, Cargo.toml and Cargo.lock files by default. This hash is injected in as a custom section of the user wasm's code. This means all data in the source files will be used for reproducible verification of a Stylus program, including code comments.
On deployment, a `keccak256` hash is created from the contents of all Rust source files in the project, sorted by file path, along with a rust-toolchain.toml, Cargo.toml and Cargo.lock files by default. This hash is injected in as a custom section of the user wasm's code. This means all data in the source files will be used for reproducible verification of a Stylus contract, including code comments.

This means the `codehash` onchain of the program will change due to this deployment metadata hash.

Expand All @@ -107,4 +107,4 @@ For instance, **a future toolchain can be used** despite the base image being 1.

**The build toolchain**

All verifiable Stylus programs in Rust _must_ have a standard [rust-toolchain.toml](https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file) file which specifies the channel for their deployment. It **cannot** be `stable`, `nightly`, or `beta` by itself, as a specific version must be added. For instance, you can specify `nightly-YYYY-MM-DD` or `major.minor.patch` for your channel. This is so that deployments have a very specific version to prevent potential mismatches from being more generic.
All verifiable Stylus contracts in Rust _must_ have a standard [rust-toolchain.toml](https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file) file which specifies the channel for their deployment. It **cannot** be `stable`, `nightly`, or `beta` by itself, as a specific version must be added. For instance, you can specify `nightly-YYYY-MM-DD` or `major.minor.patch` for your channel. This is so that deployments have a very specific version to prevent potential mismatches from being more generic.
2 changes: 1 addition & 1 deletion arbitrum-docs/stylus/reference/rust-sdk-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,7 @@ The above will make the public methods of `Contract` the first to consider durin

### Reentrancy

If a contract calls another that then calls the first, it is said to be reentrant. By default, all Stylus programs revert when this happens. However, you can opt out of this behavior by enabling the `reentrant` feature flag.
If a contract calls another that then calls the first, it is said to be reentrant. By default, all Stylus contracts revert when this happens. However, you can opt out of this behavior by enabling the `reentrant` feature flag.

```rust
stylus-sdk = { version = "0.6.0", features = ["reentrant"] }
Expand Down
4 changes: 2 additions & 2 deletions arbitrum-docs/stylus/reference/stylus-sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@ title: 'Stylus SDK repositories'
description: A table with links and minimal information about the different SDKs
author: rachel-bousfield
sme: rachel-bousfield
target_audience: Developers writing and deploying Stylus programs
target_audience: Developers writing and deploying Stylus contracts
sidebar_position: 2
---

import PublicPreviewBannerPartial from '../../partials/_public-preview-banner-partial.mdx';

<PublicPreviewBannerPartial />

If you are looking to write and deploy Stylus programs, please see the following SDKs.
If you are looking to write and deploy Stylus contracts, please see the following SDKs.

| Repo | Use cases | License |
| :----------------------------- | :-------------------------- | :---------------- |
Expand Down
8 changes: 4 additions & 4 deletions arbitrum-docs/stylus/stylus-gentle-introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Solidity programs and WASM programs are completely composable. If working in Sol

### How does it work?

There are four main steps for bringing a Stylus program to life: coding, activation, execution, and proving.
There are four main steps for bringing a Stylus contract to life: coding, activation, execution, and proving.

#### Coding

Expand All @@ -84,15 +84,15 @@ The Stylus SDK for Rust contains the smart contract development framework and la

#### Activation

Stylus programs are compiled to WASM and then lowered to assembly. Starting from a high-level language (such as Rust, C, or C++), the first compilation stage happens either using the CLI provided in the Stylus SDK for Rust or any other compiler, such as Clang for C and C++. Once compiled, the WASM is posted onchain. Then, in a process called activation, WASM gets lowered to a node's native machine code (such as ARM or x86).
Stylus contracts are compiled to WASM and then lowered to assembly. Starting from a high-level language (such as Rust, C, or C++), the first compilation stage happens either using the CLI provided in the Stylus SDK for Rust or any other compiler, such as Clang for C and C++. Once compiled, the WASM is posted onchain. Then, in a process called activation, WASM gets lowered to a node's native machine code (such as ARM or x86).

Activating a Stylus program requires a new precompile, ArbWasm. This precompile produces efficient binary code tailored to a node's native assembly. During this step, a series of middlewares ensure user programs can be safely executed and deterministically fraud-proven. Instrumentation includes gas metering, depth-checking, memory charging, and more to guarantee all WASM programs are safe for the chain to execute. Stylus contracts can be called only after they've been activated.
Activating a Stylus contract requires a new precompile, ArbWasm. This precompile produces efficient binary code tailored to a node's native assembly. During this step, a series of middlewares ensure user programs can be safely executed and deterministically fraud-proven. Instrumentation includes gas metering, depth-checking, memory charging, and more to guarantee all WASM programs are safe for the chain to execute. Stylus contracts can be called only after they've been activated.

Gas metering is essential for certifying that computational resources are paid for. In Stylus, the unit for measuring cost is called “ink,” similar to Ethereum's gas but thousands of times smaller. There are two reasons why a new measurement is used: First, WASM execution is so much faster than the EVM that thousands of WASM opcodes could be executed in the same time it takes the EVM to execute one. Second, the conversion rate of ink to gas can change based on future hardware or VM improvements. For a conceptual introduction to Stylus gas and ink, see [gas and ink (Stylus)](https://docs.arbitrum.io/stylus/concepts/stylus-gas).

#### Execution

Stylus programs are executed in a fork of [Wasmer](https://wasmer.io/), the leading WebAssembly runtime, with minimal changes to optimize their codebase for blockchain-specific use cases. Wasmer executes native code much faster than <a data-quicklook-from="geth">Geth</a> executes EVM bytecode, contributing to the significant gas savings that Stylus provides.
Stylus contracts are executed in a fork of [Wasmer](https://wasmer.io/), the leading WebAssembly runtime, with minimal changes to optimize their codebase for blockchain-specific use cases. Wasmer executes native code much faster than <a data-quicklook-from="geth">Geth</a> executes EVM bytecode, contributing to the significant gas savings that Stylus provides.

EVM contracts continue to execute the same way they did before Stylus. When a contract is called, the difference between an EVM contract and a WASM program can be seen via an [EOF](https://notes.ethereum.org/@ipsilon/evm-object-format-overview)-inspired contract header. From there, the contract is executed using its corresponding runtime. Contracts written in Solidity and WASM languages can make cross-contract calls to each other, meaning a developer never has to consider what language the contract was written in. Everything is interoperable.

Expand Down
Loading