From 784c741f409ba5d6d2dddeda03a9120076c43698 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Fri, 1 Nov 2024 09:43:59 -0700 Subject: [PATCH 1/4] fix: delete former file name --- arbitrum-docs/stylus/stylus-quickstart.md | 313 ---------------------- 1 file changed, 313 deletions(-) delete mode 100644 arbitrum-docs/stylus/stylus-quickstart.md diff --git a/arbitrum-docs/stylus/stylus-quickstart.md b/arbitrum-docs/stylus/stylus-quickstart.md deleted file mode 100644 index 14bc81736..000000000 --- a/arbitrum-docs/stylus/stylus-quickstart.md +++ /dev/null @@ -1,313 +0,0 @@ ---- -title: 'Quickstart: write a smart contract in Rust using Stylus' -description: 'Leads a developer from 0 to 1 writing and deploying a smart contract in Rust using Stylus' -author: chrisco512, anegg0 -sme: chrisco512, anegg0 -sidebar_position: 2 -target_audience: Developers writing Stylus contracts in Rust using Stylus ---- - -import PublicPreviewBannerPartial from '../partials/_public-preview-banner-partial.mdx'; - - - -This guide will get you started with Stylus' basics. We'll cover the following steps: - -1. [Setting up your development environment](./stylus-quickstart#setting-up-your-development-environment) -2. [Creating a Stylus project with cargo stylus](./stylus-quickstart#creating-a-stylus-project-with-cargo-stylus) -3. [Checking the validity of your contract](./stylus-quickstart#checking-if-your-stylus-project-is-valid) -4. [Deploying your contract](./stylus-quickstart#deploying-your-contract) -5. [Exporting your contract's ABIs](./stylus-quickstart#exporting-solidity-abis) -6. [Calling your contract](./stylus-quickstart#calling-your-contract) -7. [Sending a transaction to your contract](./stylus-quickstart#sending-a-transaction-to-your-contract) - -## Setting up your development environment - -### Prerequisites - -#### Rust toolchain - -Follow the instructions on [Rust Lang’s installation page](https://www.rust-lang.org/tools/install) to install a complete Rust toolchain (v1.81 or older, v1.82 is currently not supported) on your system. After installation, ensure you can access the programs `rustup`, `rustc`, and `cargo` from your preferred terminal application. - -#### VS Code - -We recommend [VSCode](https://code.visualstudio.com/) as the IDE of choice for its excellent Rust support, but feel free to use another text editor or IDE if you’re comfortable with those. - -Some helpful VS Code extensions for Rust development: - -- [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer): Provides advanced features like smart code completion and on-the-fly error checks -- [Error Lens](https://marketplace.visualstudio.com/items?itemName=usernamehw.errorlens): Immediately highlights errors and warnings in your code -- [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml): Improves syntax highlighting and other features for TOML files, often used in Rust projects -- [Dependi](https://marketplace.visualstudio.com/items?itemName=fill-labs.dependi): Helps manage Rust crate versions directly from the editor - -#### Docker - -The testnode we will use as well as some `cargo stylus` commands require Docker to operate. - -You can download Docker from [Docker’s website](https://www.docker.com/products/docker-desktop). - -#### Foundry's Cast - -[Foundry's Cast](https://book.getfoundry.sh/cast/) is a command-line tool that allows you to interact with your EVM contracts. - -#### Nitro devnode - -Stylus is available on Arbitrum Sepolia, but we'll use nitro devnode which has a pre-funded wallet saving us the effort of wallet provisioning or running out of tokens to send transactions. - -```shell title="Install your devnode" -git clone https://github.com/OffchainLabs/nitro-devnode.git -cd nitro-devnode -``` - -```shell title="Launch your devnode" -./run-dev-node.sh -``` - -## Creating a Stylus project with cargo stylus - -[cargo stylus](https://github.com/OffchainLabs/cargo-stylus/blob/main/main/VALID_WASM.md) is a CLI toolkit built to facilitate the development of Stylus contracts. - -It is available as a plugin to the standard cargo tool used for developing Rust programs. - -### Installing cargo stylus - -In your terminal, run: - -```shell -cargo install --force cargo-stylus -``` - -Add WASM ([WebAssembly](https://webassembly.org/)) as a build target for the specific Rust toolchain you are using. The below example sets your default Rust toolchain to 1.80 as well as adding the WASM build target: - -```shell -rustup default 1.80 -rustup target add wasm32-unknown-unknown --toolchain 1.80 -``` - -You can verify that cargo stylus is installed by running `cargo stylus --help` in your terminal, which will return a list of helpful commands, we will use some of them in this guide: - -```shell title="cargo stylus --help returns:" -Cargo command for developing Stylus projects - -Usage: cargo stylus - -Commands: - new Create a new Stylus project - init Initializes a Stylus project in the current directory - export-abi Export a Solidity ABI - activate Activate an already deployed contract [aliases: a] - cache Cache a contract using the Stylus CacheManager for Arbitrum chains - check Check a contract [aliases: c] - deploy Deploy a contract [aliases: d] - verify Verify the deployment of a Stylus contract [aliases: v] - cgen Generate c code bindings for a Stylus contract - replay Replay a transaction in gdb [aliases: r] - trace Trace a transaction [aliases: t] - help Print this message or the help of the given command(s) - -Options: - -h, --help Print help - -V, --version Print version -``` - -### Creating a project - -Let's create our first Stylus project by running: - -```shell -cargo stylus new -``` - -`cargo stylus new` generates a starter template that implements a Rust version of the [Solidity `Counter` smart contract example](https://github.com/OffchainLabs/counter_contract/blob/master/contracts/Counter.sol). - -At this point, you can move on to the next step of this guide or develop your first Rust smart contract. Feel free to use the [Stylus Rust SDK reference section](./reference/overview) as a starting point; it offers many examples to help you quickly familiarize yourself with Stylus. - -## Checking if your Stylus project is valid - -By running `cargo stylus check` against your first contract, you can check if your program can be successfully **deployed and activated** onchain. - -**Important:** Ensure your Docker service runs so this command works correctly. - -```shell -cargo stylus check -``` - -`cargo stylus check` executes a dry run on your project by compiling your contract to WASM and verifying if it can be deployed and activated onchain. - -If the command above fails, you'll see detailed information about why your contract would be rejected: - -```shell -Reading WASM file at bad-export.wat -Compressed WASM size: 55 B -Stylus checks failed: program pre-deployment check failed when checking against -ARB_WASM_ADDRESS 0x0000…0071: (code: -32000, message: program activation failed: failed to parse program) - -Caused by: - binary exports reserved symbol stylus_ink_left - -Location: - prover/src/binary.rs:493:9, data: None -``` - -The contract can fail the check for various reasons (on compile, deployment, etc...). Reading the [Invalid Stylus WASM Contracts explainer](https://github.com/OffchainLabs/cargo-stylus/blob/main/main/VALID_WASM.md) can help you understand what makes a WASM contract valid or not. - -If your contract succeeds, you'll see something like this: - -```shell -Finished release [optimized] target(s) in 1.88s -Reading WASM file at hello-stylus/target/wasm32-unknown-unknown/release/hello-stylus.wasm -Compressed WASM size: 3 KB -Program succeeded Stylus onchain activation checks with Stylus version: 1 -``` - -Note that running `cargo stylus check` may take a few minutes, especially if you're verifying a contract for the first time. - -See `cargo stylus check --help` for more options. - -## Deploying your contract - -Once you're ready to deploy your contract onchain, `cargo stylus deploy` will help you with the deployment and its gas estimation. - -### Estimating gas - -Note: For every transaction, we'll use the testnode pre-funded wallet, you can use `0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659` as your private key. - -You can estimate the gas required to deploy your contract by running: - -```shell -cargo stylus deploy \ - --endpoint='http://localhost:8547' \ - --private-key="0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659" \ - --estimate-gas -``` - -The command should return something like this: - -```shell -deployment tx gas: 7123737 -gas price: "0.100000000" gwei -deployment tx total cost: "0.000712373700000000" ETH -``` - -### Deployment - -Let's move on to the contract's actual deployment. Two transactions will be sent onchain: the contract deployment and its [activation](stylus/stylus-gentle-introduction.md#activation). - -```shell -cargo stylus deploy \ - --endpoint='http://localhost:8547' \ - --private-key="0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659" -``` - -Once the deployment and activations are successful, you'll see an output similar to this: - -```shell -deployed code at address: 0x33f54de59419570a9442e788f5dd5cf635b3c7ac -deployment tx hash: 0xa55efc05c45efc63647dff5cc37ad328a47ba5555009d92ad4e297bf4864de36 -wasm already activated! -``` - -Make sure to save the contract's deployment address for future interactions! - -More options are available for sending and outputting your transaction data. See `cargo stylus deploy --help` for more details. - -## Exporting the Solidity ABI interface - -The cargo stylus tool makes it easy to export your contract's ABI using `cargo stylus export-abi`. - -This command returns the Solidity ABI interface of your smart contract. If you have been running `cargo stylus new` without modifying the output, `cargo stylus export-abi` will return: - -```shell -/** - * This file was automatically generated by Stylus and represents a Rust program. - * For more information, please see [The Stylus SDK](https://github.com/OffchainLabs/stylus-sdk-rs). - */ - -// SPDX-License-Identifier: MIT-OR-APACHE-2.0 -pragma solidity ^0.8.23; - -interface ICounter { - function number() external view returns (uint256); - - function setNumber(uint256 new_number) external; - - function mulNumber(uint256 new_number) external; - - function addNumber(uint256 new_number) external; - - function increment() external; -} -``` - -Ensure you save the console output to a file that you'll be able to use with your dApp. - -## Interacting with your Stylus contract - -Stylus contracts are EVM-compatible, you can interact with them with your tool of choice, such as [Hardhat](https://hardhat.org/), [Foundry's Cast](https://book.getfoundry.sh/cast/), or any other Ethereum-compatible tool. - -In this example, we'll use Foundry's Cast to send a call and then a transaction to our contract. - -### Calling your contract - -Our contract is a counter; in its initial state, it should store a counter value of `0`. -You can call your contract so it returns its current counter value by sending it the following command: - -```shell title="Call to the function: number()(uint256)" -cast call --rpc-url 'http://localhost:8547' --private-key 0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659 \ -[deployed-contract-address] "number()(uint256)" -``` - -Let's break down the command: - -- `cast call` command sends a call to your contract -- The `--rpc-url` option is the `RPC URL` endpoint of our testnode: http://localhost:8547 -- The `--private-key` option is the private key of our pre-funded development account. It corresponds to the address `0x3f1eae7d46d88f08fc2f8ed27fcb2ab183eb2d0e` -- The [deployed-contract-address] is the address we want to interact with, it's the address that was returned by `cargo stylus deploy` -- `number()(uint256)` is the function we want to call in Solidity-style signature. The function returns the counter's current value - -```shell title="Calling 'number()(uint256)' returns:" -0 -``` - -The `number()(uint256)` function returns a value of `0`, the contract's initial state. - -### Sending a transaction to your contract - -Let's increment the counter by sending a transaction to your contract's `increment()` function. -We'll use Cast's `send` command to send our transaction. - -```shell title="Sending a transaction to the function: increment()" -cast send --rpc-url 'http://localhost:8547' --private-key 0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659 \ -[deployed-contract-address] "increment()" -``` - -```shell title="Transaction returns:" -blockHash 0xfaa2cce3b9995f3f2e2a2f192dc50829784da9ca4b7a1ad21665a25b3b161f7c -blockNumber 20 -contractAddress -cumulativeGasUsed 97334 -effectiveGasPrice 100000000 -from 0x3f1Eae7D46d88F08fc2F8ed27FCb2AB183EB2d0E -gasUsed 97334 -logs [] -logsBloom 0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 -root -status 1 (success) -transactionHash 0x28c6ba8a0b9915ed3acc449cf6c645ecc406a4b19278ec1eb67f5a7091d18f6b -transactionIndex 1 -type 2 -blobGasPrice -blobGasUsed -authorizationList -to 0x11B57FE348584f042E436c6Bf7c3c3deF171de49 -gasUsedForL1 "0x0" -l1BlockNumber "0x1223" -``` - -Our transactions returned a status of `1`, indicating success, and the counter has been incremented (you can verify this by calling your contract's `number()(uint256)` function again). - -## Conclusion - -Congratulations! You've successfully initialized, deployed, and interacted with your first contract using Stylus and Rust. - -Feel free to explore the [Stylus Rust SDK reference](./reference/overview) for more information on using Stylus in your Arbitrum projects. From 1f0ba2ff7b1dfee578d4d52915af7e36d7691ab5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Fri, 1 Nov 2024 09:44:18 -0700 Subject: [PATCH 2/4] This is a squash of 14 commits. --- arbitrum-docs/stylus/reference/overview.md | 2 +- .../stylus/reference/rust-sdk-guide.md | 2 +- arbitrum-docs/stylus/stylus-quickstart.mdx | 314 ++++++++++++++++++ website/docusaurus.config.js | 9 + website/package.json | 3 +- website/src/css/custom.scss | 1 + website/src/css/partials/_collapsible.scss | 100 ++++++ website/yarn.lock | 25 +- 8 files changed, 451 insertions(+), 5 deletions(-) create mode 100644 arbitrum-docs/stylus/stylus-quickstart.mdx create mode 100644 website/src/css/partials/_collapsible.scss diff --git a/arbitrum-docs/stylus/reference/overview.md b/arbitrum-docs/stylus/reference/overview.md index 1b706a3b7..971221033 100644 --- a/arbitrum-docs/stylus/reference/overview.md +++ b/arbitrum-docs/stylus/reference/overview.md @@ -12,7 +12,7 @@ import PublicPreviewBannerPartial from '../../partials/_public-preview-banner-pa -This section provides an in-depth overview of the features provided by the [Stylus Rust SDK](https://github.com/OffchainLabs/stylus-sdk-rs). For information about deploying Rust smart contracts, see the `cargo stylus` [CLI Tool](https://github.com/OffchainLabs/cargo-stylus). For a conceptual introduction to Stylus, see [Stylus: A Gentle Introduction](../stylus-gentle-introduction.md). To deploy your first Stylus smart contract using Rust, refer to the [Quickstart](../stylus-quickstart.md). +This section provides an in-depth overview of the features provided by the [Stylus Rust SDK](https://github.com/OffchainLabs/stylus-sdk-rs). For information about deploying Rust smart contracts, see the `cargo stylus` [CLI Tool](https://github.com/OffchainLabs/cargo-stylus). For a conceptual introduction to Stylus, see [Stylus: A Gentle Introduction](../stylus-gentle-introduction.md). To deploy your first Stylus smart contract using Rust, refer to the [Quickstart](../stylus-quickstart.mdx). The Stylus Rust SDK is built on top of [Alloy](https://www.paradigm.xyz/2023/06/alloy), a collection of crates empowering the Rust Ethereum ecosystem. Because the SDK uses the same [Rust primitives for Ethereum types](https://docs.rs/alloy-primitives/latest/alloy_primitives/), Stylus is compatible with existing Rust libraries. diff --git a/arbitrum-docs/stylus/reference/rust-sdk-guide.md b/arbitrum-docs/stylus/reference/rust-sdk-guide.md index 08d394253..3f963fbf4 100644 --- a/arbitrum-docs/stylus/reference/rust-sdk-guide.md +++ b/arbitrum-docs/stylus/reference/rust-sdk-guide.md @@ -13,7 +13,7 @@ import StylusNoMultiInheritanceBannerPartial from '../partials/_stylus-no-multi- -This document provides information about advanced features included in the [Stylus Rust SDK](https://github.com/OffchainLabs/stylus-sdk-rs), that are not described in the previous pages. For information about deploying Rust smart contracts, see the `cargo stylus` [CLI Tool](https://github.com/OffchainLabs/cargo-stylus). For a conceptual introduction to Stylus, see [Stylus: A Gentle Introduction](../stylus-gentle-introduction.md). To deploy your first Stylus smart contract using Rust, refer to the [Quickstart](../stylus-quickstart.md). +This document provides information about advanced features included in the [Stylus Rust SDK](https://github.com/OffchainLabs/stylus-sdk-rs), that are not described in the previous pages. For information about deploying Rust smart contracts, see the `cargo stylus` [CLI Tool](https://github.com/OffchainLabs/cargo-stylus). For a conceptual introduction to Stylus, see [Stylus: A Gentle Introduction](../stylus-gentle-introduction.md). To deploy your first Stylus smart contract using Rust, refer to the [Quickstart](../stylus-quickstart.mdx). :::info diff --git a/arbitrum-docs/stylus/stylus-quickstart.mdx b/arbitrum-docs/stylus/stylus-quickstart.mdx new file mode 100644 index 000000000..c426215ca --- /dev/null +++ b/arbitrum-docs/stylus/stylus-quickstart.mdx @@ -0,0 +1,314 @@ +--- +title: 'Quickstart: write a smart contract in Rust using Stylus' +description: 'Leads a developer from 0 to 1 writing and deploying a smart contract in Rust using Stylus' +author: chrisco512, anegg0 +sme: chrisco512, anegg0 +sidebar_position: 2 +target_audience: Developers writing Stylus contracts in Rust using Stylus +--- +import Collapsible from 'react-collapsible'; +import PublicPreviewBannerPartial from '../partials/_public-preview-banner-partial.mdx'; + + + +This guide will get you started with Stylus' basics. We'll cover the following steps: + +1. [Setting up your development environment](./stylus-quickstart#setting-up-your-development-environment) +2. [Creating a Stylus project with cargo stylus](./stylus-quickstart#creating-a-stylus-project-with-cargo-stylus) +3. [Checking the validity of your contract](./stylus-quickstart#checking-if-your-stylus-project-is-valid) +4. [Deploying your contract](./stylus-quickstart#deploying-your-contract) +5. [Exporting your contract's ABIs](./stylus-quickstart#exporting-solidity-abis) +6. [Calling your contract](./stylus-quickstart#calling-your-contract) +7. [Sending a transaction to your contract](./stylus-quickstart#sending-a-transaction-to-your-contract) + +## Setting up your development environment + +### Prerequisites + + +Follow the instructions on [Rust Lang’s installation page](https://www.rust-lang.org/tools/install) to install a complete Rust toolchain (v1.81 or older, v1.82 is currently not supported) on your system. After installation, ensure you can access the programs `rustup`, `rustc`, and `cargo` from your preferred terminal application. + + + +We recommend [VSCode](https://code.visualstudio.com/) as the IDE of choice for its excellent Rust support, but feel free to use another text editor or IDE if you’re comfortable with those. + +Some helpful VS Code extensions for Rust development: + +- [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer): Provides advanced features like smart code completion and on-the-fly error checks +- [Error Lens](https://marketplace.visualstudio.com/items?itemName=usernamehw.errorlens): Immediately highlights errors and warnings in your code +- [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml): Improves syntax highlighting and other features for TOML files, often used in Rust projects +- [Dependi](https://marketplace.visualstudio.com/items?itemName=fill-labs.dependi): Helps manage Rust crate versions directly from the editor + + + + +The testnode we will use as well as some `cargo stylus` commands require Docker to operate. + +You can download Docker from [Docker’s website](https://www.docker.com/products/docker-desktop). + + + + +[Foundry's Cast](https://book.getfoundry.sh/cast/) is a command-line tool that allows you to interact with your EVM contracts. + + +Stylus is available on Arbitrum Sepolia, but we'll use nitro devnode which has a pre-funded wallet saving us the effort of wallet provisioning or running out of tokens to send transactions. + +```shell title="Install your devnode" +git clone https://github.com/OffchainLabs/nitro-devnode.git +cd nitro-devnode +``` + +```shell title="Launch your devnode" +./run-dev-node.sh +``` + + +## Creating a Stylus project with cargo stylus + +[cargo stylus](https://github.com/OffchainLabs/cargo-stylus/blob/main/main/VALID_WASM.md) is a CLI toolkit built to facilitate the development of Stylus contracts. + +It is available as a plugin to the standard cargo tool used for developing Rust programs. + +### Installing cargo stylus + +In your terminal, run: + +```shell +cargo install --force cargo-stylus +``` + +Add WASM ([WebAssembly](https://webassembly.org/)) as a build target for the specific Rust toolchain you are using. The below example sets your default Rust toolchain to 1.80 as well as adding the WASM build target: + +```shell +rustup default 1.80 +rustup target add wasm32-unknown-unknown --toolchain 1.80 +``` + +You can verify that cargo stylus is installed by running `cargo stylus --help` in your terminal, which will return a list of helpful commands, we will use some of them in this guide: + +```shell title="cargo stylus --help returns:" +Cargo command for developing Stylus projects + +Usage: cargo stylus + +Commands: + new Create a new Stylus project + init Initializes a Stylus project in the current directory + export-abi Export a Solidity ABI + activate Activate an already deployed contract [aliases: a] + cache Cache a contract using the Stylus CacheManager for Arbitrum chains + check Check a contract [aliases: c] + deploy Deploy a contract [aliases: d] + verify Verify the deployment of a Stylus contract [aliases: v] + cgen Generate c code bindings for a Stylus contract + replay Replay a transaction in gdb [aliases: r] + trace Trace a transaction [aliases: t] + help Print this message or the help of the given command(s) + +Options: + -h, --help Print help + -V, --version Print version +``` + +### Creating a project + +Let's create our first Stylus project by running: + +```shell +cargo stylus new +``` + +`cargo stylus new` generates a starter template that implements a Rust version of the [Solidity `Counter` smart contract example](https://github.com/OffchainLabs/counter_contract/blob/master/contracts/Counter.sol). + +At this point, you can move on to the next step of this guide or develop your first Rust smart contract. Feel free to use the [Stylus Rust SDK reference section](./reference/overview) as a starting point; it offers many examples to help you quickly familiarize yourself with Stylus. + +## Checking if your Stylus project is valid + +By running `cargo stylus check` against your first contract, you can check if your program can be successfully **deployed and activated** onchain. + +**Important:** Ensure your Docker service runs so this command works correctly. + +```shell +cargo stylus check +``` + +`cargo stylus check` executes a dry run on your project by compiling your contract to WASM and verifying if it can be deployed and activated onchain. + +If the command above fails, you'll see detailed information about why your contract would be rejected: + +```shell +Reading WASM file at bad-export.wat +Compressed WASM size: 55 B +Stylus checks failed: program pre-deployment check failed when checking against +ARB_WASM_ADDRESS 0x0000…0071: (code: -32000, message: program activation failed: failed to parse program) + +Caused by: + binary exports reserved symbol stylus_ink_left + +Location: + prover/src/binary.rs:493:9, data: None +``` + +The contract can fail the check for various reasons (on compile, deployment, etc...). Reading the [Invalid Stylus WASM Contracts explainer](https://github.com/OffchainLabs/cargo-stylus/blob/main/main/VALID_WASM.md) can help you understand what makes a WASM contract valid or not. + +If your contract succeeds, you'll see something like this: + +```shell +Finished release [optimized] target(s) in 1.88s +Reading WASM file at hello-stylus/target/wasm32-unknown-unknown/release/hello-stylus.wasm +Compressed WASM size: 3 KB +Program succeeded Stylus onchain activation checks with Stylus version: 1 +``` + +Note that running `cargo stylus check` may take a few minutes, especially if you're verifying a contract for the first time. + +See `cargo stylus check --help` for more options. + +## Deploying your contract + +Once you're ready to deploy your contract onchain, `cargo stylus deploy` will help you with the deployment and its gas estimation. + +### Estimating gas + +Note: For every transaction, we'll use the testnode pre-funded wallet, you can use `0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659` as your private key. + +You can estimate the gas required to deploy your contract by running: + +```shell +cargo stylus deploy \ + --endpoint='http://localhost:8547' \ + --private-key="0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659" \ + --estimate-gas +``` + +The command should return something like this: + +```shell +deployment tx gas: 7123737 +gas price: "0.100000000" gwei +deployment tx total cost: "0.000712373700000000" ETH +``` + +### Deployment + +Let's move on to the contract's actual deployment. Two transactions will be sent onchain: the contract deployment and its [activation](stylus/stylus-gentle-introduction.md#activation). + +```shell +cargo stylus deploy \ + --endpoint='http://localhost:8547' \ + --private-key="0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659" +``` + +Once the deployment and activations are successful, you'll see an output similar to this: + +```shell +deployed code at address: 0x33f54de59419570a9442e788f5dd5cf635b3c7ac +deployment tx hash: 0xa55efc05c45efc63647dff5cc37ad328a47ba5555009d92ad4e297bf4864de36 +wasm already activated! +``` + +Make sure to save the contract's deployment address for future interactions! + +More options are available for sending and outputting your transaction data. See `cargo stylus deploy --help` for more details. + +## Exporting the Solidity ABI interface + +The cargo stylus tool makes it easy to export your contract's ABI using `cargo stylus export-abi`. + +This command returns the Solidity ABI interface of your smart contract. If you have been running `cargo stylus new` without modifying the output, `cargo stylus export-abi` will return: + +```shell +/** + * This file was automatically generated by Stylus and represents a Rust program. + * For more information, please see [The Stylus SDK](https://github.com/OffchainLabs/stylus-sdk-rs). + */ + +// SPDX-License-Identifier: MIT-OR-APACHE-2.0 +pragma solidity ^0.8.23; + +interface ICounter { + function number() external view returns (uint256); + + function setNumber(uint256 new_number) external; + + function mulNumber(uint256 new_number) external; + + function addNumber(uint256 new_number) external; + + function increment() external; +} +``` + +Ensure you save the console output to a file that you'll be able to use with your dApp. + +## Interacting with your Stylus contract + +Stylus contracts are EVM-compatible, you can interact with them with your tool of choice, such as [Hardhat](https://hardhat.org/), [Foundry's Cast](https://book.getfoundry.sh/cast/), or any other Ethereum-compatible tool. + +In this example, we'll use Foundry's Cast to send a call and then a transaction to our contract. + +### Calling your contract + +Our contract is a counter; in its initial state, it should store a counter value of `0`. +You can call your contract so it returns its current counter value by sending it the following command: + +```shell title="Call to the function: number()(uint256)" +cast call --rpc-url 'http://localhost:8547' --private-key 0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659 \ +[deployed-contract-address] "number()(uint256)" +``` + +Let's break down the command: + +- `cast call` command sends a call to your contract +- The `--rpc-url` option is the `RPC URL` endpoint of our testnode: http://localhost:8547 +- The `--private-key` option is the private key of our pre-funded development account. It corresponds to the address `0x3f1eae7d46d88f08fc2f8ed27fcb2ab183eb2d0e` +- The [deployed-contract-address] is the address we want to interact with, it's the address that was returned by `cargo stylus deploy` +- `number()(uint256)` is the function we want to call in Solidity-style signature. The function returns the counter's current value + +```shell title="Calling 'number()(uint256)' returns:" +0 +``` + +The `number()(uint256)` function returns a value of `0`, the contract's initial state. + +### Sending a transaction to your contract + +Let's increment the counter by sending a transaction to your contract's `increment()` function. +We'll use Cast's `send` command to send our transaction. + +```shell title="Sending a transaction to the function: increment()" +cast send --rpc-url 'http://localhost:8547' --private-key 0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659 \ +[deployed-contract-address] "increment()" +``` + +```shell title="Transaction returns:" +blockHash 0xfaa2cce3b9995f3f2e2a2f192dc50829784da9ca4b7a1ad21665a25b3b161f7c +blockNumber 20 +contractAddress +cumulativeGasUsed 97334 +effectiveGasPrice 100000000 +from 0x3f1Eae7D46d88F08fc2F8ed27FCb2AB183EB2d0E +gasUsed 97334 +logs [] +logsBloom 0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 +root +status 1 (success) +transactionHash 0x28c6ba8a0b9915ed3acc449cf6c645ecc406a4b19278ec1eb67f5a7091d18f6b +transactionIndex 1 +type 2 +blobGasPrice +blobGasUsed +authorizationList +to 0x11B57FE348584f042E436c6Bf7c3c3deF171de49 +gasUsedForL1 "0x0" +l1BlockNumber "0x1223" +``` + +Our transactions returned a status of `1`, indicating success, and the counter has been incremented (you can verify this by calling your contract's `number()(uint256)` function again). + +## Conclusion + +Congratulations! You've successfully initialized, deployed, and interacted with your first contract using Stylus and Rust. + +Feel free to explore the [Stylus Rust SDK reference](./reference/overview) for more information on using Stylus in your Arbitrum projects. diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 6140f97d3..e6f55df72 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -14,6 +14,15 @@ const config = { onBrokenLinks: 'throw', onBrokenMarkdownLinks: 'throw', favicon: 'img/logo.svg', + headTags: [ + { + tagName: 'link', + attributes: { + rel: 'stylesheet', + href: 'https:use.fontawesome.com/releases/v5.0.1/css/all.css', + }, + }, + ], markdown: { mermaid: true, }, diff --git a/website/package.json b/website/package.json index c70278105..254b24438 100644 --- a/website/package.json +++ b/website/package.json @@ -39,6 +39,7 @@ "posthog-docusaurus": "^2.0.0", "prism-react-renderer": "^1.3.5", "react": "^18.2.0", + "react-collapsible": "^2.10.0", "react-dom": "^18.2.0", "sass": "^1.66.1", "tippy.js": "^6.3.7", @@ -48,11 +49,11 @@ "@docusaurus/module-type-aliases": "^3.3.2", "@offchainlabs/prettier-config": "0.2.1", "@tsconfig/docusaurus": "^2.0.3", + "docusaurus-plugin-typedoc": "^1.0.1", "markdown-link-extractor": "^3.1.0", "prettier": "^2.8.3", "ts-node": "^10.9.1", "typedoc": "^0.25.13", - "docusaurus-plugin-typedoc": "^1.0.1", "typedoc-plugin-frontmatter": "^1.0.0", "typedoc-plugin-markdown": "4.0.1", "typescript": "^5.1" diff --git a/website/src/css/custom.scss b/website/src/css/custom.scss index 202d680a3..381ece7ce 100644 --- a/website/src/css/custom.scss +++ b/website/src/css/custom.scss @@ -11,3 +11,4 @@ @use './partials/_sidebar.scss'; @use './partials/_footer.scss'; @use './partials/_navbar.scss'; +@use './partials/_collapsible.scss'; diff --git a/website/src/css/partials/_collapsible.scss b/website/src/css/partials/_collapsible.scss new file mode 100644 index 000000000..9064ba7b4 --- /dev/null +++ b/website/src/css/partials/_collapsible.scss @@ -0,0 +1,100 @@ +@use './_mixins.scss' as *; +// The main container element +.Collapsible { + background-color: unset; +} + +//The content within the collaspable area +.Collapsible__contentInner { + padding: 10px; + border: 1px solid lightGrey; + border-top: 0; + + p { + margin-bottom: 10px; + font-size: 14px; + line-height: 20px; + + &:last-child { + margin-bottom: 0; + } + } +} + +//The link which when clicked opens the collapsable area +.Collapsible__trigger { + display: block; + font-weight: 900; + text-decoration: none; + position: relative; + border: 1px solid white; + padding: 10px; + background: grey; + color: white; + + &:after { + font-family: 'Font Awesome\ 5 Free'; + content: '\f107'; + position: absolute; + right: 10px; + top: 10px; + display: block; + transition: transform 300ms; + } + + &.is-open { + &:after { + transform: rotateZ(180deg); + } + } + + &.is-disabled { + opacity: 0.5; + background-color: grey; + } +} + +.CustomTriggerCSS { + background-color: lightcoral; + transition: background-color 200ms ease; +} + +.CustomTriggerCSS--open { + background-color: darkslateblue; +} + +.Collapsible__custom-sibling { + padding: 5px; + font-size: 12px; + background-color: #cbb700; + color: black; +} + +[data-theme='dark'] { + .Collapsible__contentInner { + border: 1px solid #444; + } + + .Collapsible__trigger { + background: #333; + color: #ddd; + border: 1px solid #555; + + &.is-disabled { + background-color: #444; + } + } + + .CustomTriggerCSS { + background-color: #555; + } + + .CustomTriggerCSS--open { + background-color: #222; + } + + .Collapsible__custom-sibling { + background-color: #555; + color: #eee; + } +} diff --git a/website/yarn.lock b/website/yarn.lock index a68a71eb0..30e440f99 100644 --- a/website/yarn.lock +++ b/website/yarn.lock @@ -8672,6 +8672,11 @@ rc@1.2.8: minimist "^1.2.0" strip-json-comments "~2.0.1" +react-collapsible@^2.10.0: + version "2.10.0" + resolved "https://registry.yarnpkg.com/react-collapsible/-/react-collapsible-2.10.0.tgz#57330f9f4f968a41ece49c651b56cf30f9a06d19" + integrity sha512-kEVsmlFfXBMTCnU5gwIv19MdmPAhbIPzz5Er37TiJSzRKS0IHrqAKQyQeHEmtoGIQMTcVI46FzE4z3NlVTx77A== + react-dev-utils@^12.0.1: version "12.0.1" resolved "https://registry.yarnpkg.com/react-dev-utils/-/react-dev-utils-12.0.1.tgz#ba92edb4a1f379bd46ccd6bcd4e7bc398df33e73" @@ -9601,7 +9606,16 @@ std-env@^3.0.1: resolved "https://registry.yarnpkg.com/std-env/-/std-env-3.7.0.tgz#c9f7386ced6ecf13360b6c6c55b8aaa4ef7481d2" integrity sha512-JPbdCEQLj1w5GilpiHAx3qJvFndqybBysA3qUOnznweH4QbNYUsW/ea8QzSrnh0vNsezMMw5bcVool8lM0gwzg== -"string-width-cjs@npm:string-width@^4.2.0", "string-width@^1.0.2 || 2 || 3 || 4", string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.3: +"string-width-cjs@npm:string-width@^4.2.0": + version "4.2.3" + resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010" + integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g== + dependencies: + emoji-regex "^8.0.0" + is-fullwidth-code-point "^3.0.0" + strip-ansi "^6.0.1" + +"string-width@^1.0.2 || 2 || 3 || 4", string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.3: version "4.2.3" resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010" integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g== @@ -9650,7 +9664,14 @@ stringify-object@^3.3.0: is-obj "^1.0.1" is-regexp "^1.0.0" -"strip-ansi-cjs@npm:strip-ansi@^6.0.1", strip-ansi@^6.0.0, strip-ansi@^6.0.1: +"strip-ansi-cjs@npm:strip-ansi@^6.0.1": + version "6.0.1" + resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9" + integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A== + dependencies: + ansi-regex "^5.0.1" + +strip-ansi@^6.0.0, strip-ansi@^6.0.1: version "6.0.1" resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9" integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A== From d349c479a57bd3596e8264599c31064fb631a0c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Sun, 3 Nov 2024 13:36:43 -0800 Subject: [PATCH 3/4] feat: re-style collapsible css --- website/src/css/partials/_collapsible.scss | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/src/css/partials/_collapsible.scss b/website/src/css/partials/_collapsible.scss index 9064ba7b4..5720d6b5f 100644 --- a/website/src/css/partials/_collapsible.scss +++ b/website/src/css/partials/_collapsible.scss @@ -24,13 +24,13 @@ //The link which when clicked opens the collapsable area .Collapsible__trigger { display: block; - font-weight: 900; + font-weight: 600; text-decoration: none; position: relative; border: 1px solid white; - padding: 10px; - background: grey; - color: white; + padding: 8px; + background: rgb(207, 207, 207); + color: rgb(83, 82, 82); &:after { font-family: 'Font Awesome\ 5 Free'; From fe25b8676d7919f72ac3f05ce1812d893237afbe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Sun, 3 Nov 2024 14:38:30 -0800 Subject: [PATCH 4/4] fix: change font-weight --- website/src/css/partials/_collapsible.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/src/css/partials/_collapsible.scss b/website/src/css/partials/_collapsible.scss index 5720d6b5f..b8904544e 100644 --- a/website/src/css/partials/_collapsible.scss +++ b/website/src/css/partials/_collapsible.scss @@ -24,7 +24,7 @@ //The link which when clicked opens the collapsable area .Collapsible__trigger { display: block; - font-weight: 600; + font-weight: 700; text-decoration: none; position: relative; border: 1px solid white;