Cargo extension for building Rust smart contracts on NEAR
npm install cargo-nearRelease notes and unreleased changes can be found in the CHANGELOG
* Quick start your project with the template repository generated by cargo near new command
* The associated template repository's README contains a Code > Codespaces > Create codespace on main screenshot.
* Clicking the button will result in using Github Codespaces devcontainer. The containers allow you to start building without the need to install any dependencies on your machine and provide the actual version.
Install prebuilt binaries via shell script (Linux, macOS)
``sh`
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/cargo-near/releases/latest/download/cargo-near-installer.sh | sh
Install prebuilt binaries via powershell script (Windows)
`sh`
irm https://github.com/near/cargo-near/releases/latest/download/cargo-near-installer.ps1 | iex
Install prebuilt binaries into your Node.js application
`sh`
npm install cargo-near
Compile and install from source code (Cargo)
`sh`
cargo install --locked cargo-near
or, install the most recent version from git repository:
`sh`
$ git clone https://github.com/near/cargo-near
$ cargo install --locked --path cargo-near
See cargo near --help for a complete list of available commands or run cargo near to dive into interactive mode. Help is also available for each individual command with a --help flag, e.g. cargo near build --help.
`console`
cargo near
Starts interactive mode that will allow to explore all the available commands.
---
Use --teach-me flag if you want to know "how it works".
`console`
cargo near --teach-me
Starts an interactive mode with an explanation of the execution of the selected command.
---
Additionally depends on Git binary being installed, besides cargo.
`console`
cargo near new
Initializes a new project skeleton to create a contract from a template.
Example of github workflows configuration, created by cargo near new.
---
`console`
cargo near build
Builds a NEAR smart contract along with its ABI (while in the directory containing contract's Cargo.toml).
Running the above command opens a menu with following variants:
Recommended variant for use during local development.
This is a regular build, which behaves much like and is a thin wrapper around a regular cargo build --target wasm32-unknown-unknown --release.
Additional flags for build configuration can be looked up if needed by:
`bash`
cargo near build non-reproducible-wasm -h # brief summary
cargo near build non-reproducible-wasm --help # detailed description of command
Recommended variant for the production releases.
This variant runs a reproducible build in a Docker container, which:
1. runs against source code version, committed to git, ignoring any uncommitted changes
2. requires that Cargo.lock of project is created (e.g. via cargo update) and added to git. --locked
- this enables build by downstream cargo command. [package.metadata.near.reproducible_build]
3. will use configuration in [](https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.template.toml#L14-L29) Cargo.toml
section of contract's and package.repository fieldCargo.toml
- default values for this section can also be found in of cargo near new
template project, generated by
What's a reproducible build in context of NEAR?
Why is it needed? Explanation of these points and a step-by-step tutorial is present at SourceScan/verification-guide.
Additional (optional) details on possible
[package.metadata.near.reproducible_build] configuration
1. available images can be found by this link https://hub.docker.com/r/sourcescan/cargo-near/tags
- image and image_digest are straightforward to configure:
!image_and_digest_pinpoint
2. flags of build command, run inside of docker container, can be configured, if needed, by changing container_build_command field
- base container_build_command for images starting with sourcescan/cargo-near:0.13.0-rust-1.83.0 and after it is ["cargo", "near", "build", "non-reproducible-wasm", "--locked"], where the --locked flag is requiredcontainer_build_command
- base for images prior to sourcescan/cargo-near:0.13.0-rust-1.83.0 is ["cargo", "near", "build"] cargo near build non-reproducible-wasm --help
- additional flags, if needed, can be looked up on
- for newer/latest images cargo near build --help
- for older ones docker run -it sourcescan/cargo-near:0.11.0-rust-1.82.0
- running (or another specific image) and checking the --help message of exact cargo-near in container may be helpful when in doubt cargo near
3. allows parameterizing build with values of environment variables, present at the time of the build and not present in a contract's source code,passed_env
by specifying their names in array
- supported by sourcescan/cargo-near:0.10.1-rust-1.82.0 image or later images
- SourceScan/Nearblocks does not support verifying such contracts with additional parameters present in their metadata yet
Additional flags for build configuration can be looked up if needed by:
`bash-h
cargo near build reproducible-wasm -h # replace with --help for more details`
#### Custom reproducible-wasm build using --variant flag
Beyond your [package.metadata.near.reproducible_build] configuration, you canCargo.toml
define named variants of build in your under:
`yaml`
[package.metadata.near.reproducible_build.variant.
It supports all the same fields as [package.metadata.near.reproducible_build]:image, image_digest, passed_env, and container_build_command.
**Note that every field is optional for variant build and will override
corresponding field in reproducible_build!**
For example, if you declare:
`yaml`
[package.metadata.near.reproducible_build.variant.testnet-features]
container_build_command = [
"cargo",
"near",
"build",
"non-reproducible-wasm",
"--locked",
"--features",
"testnet"
]
in Cargo.toml, and then:
`bash`
cargo near build reproducible-wasm --variant testnet-features
will use testnet-features version of container_build_command,[package.metadata.near.reproducible_build]
instead of one defined in .
---
`console`
cargo near abi
Generates NEAR smart contract's ABI (while in the directory containing contract's Cargo.toml).
Once contract is deployed, this will allow you to call a view function __contract_abi to retrieve a ZST-compressed ABI.
---
`console`
cargo near create-dev-account
Guides you through creation of a new NEAR account on testnet.
---
`console`
cargo near deploy
Builds the smart contract (equivalent to cargo near build) and guides you to deploy it to the blockchain.
Similar to build, running the above command opens a menu with following variants:
This forwards to non-reproducible-wasm variant of build command.
This forwards to reproducible-wasm variant of build command.
deploy command from Docker build requires that contract's source code:
1. doesn't have any modified tracked files, any staged changes or any untracked content.
2. has been pushed to remote repository, identified by
package.repository.
See cargo_near_build::extended module documentation on
how to write build.rs for subcontracts.
environment variablesBoth of the following are mentioned on https://doc.rust-lang.org/cargo/reference/config.html#buildrustflags
running e.g.
`bash`
RUSTFLAGS="your_custom_value" cargo near build non-reproducible-wasm"your_custom_value"
won't result in affecting the build.
RUSTFLAGS="-Awarnings" is always used for abi build stage, and RUSTFLAGS="-C link-arg=-s" for wasm build stage.
Logic for concatenating default values of this variable with values from env was removed in cargo-near-0.13.3/cargo-near-build-0.4.3, as it was seen as
an unnecessary complication.
There's still a way to override this parameter for wasm build stage, e.g.:
`lang`
cargo near build non-reproducible-wasm --env 'RUSTFLAGS=--verbose'
RUST_LOG=info cargo near build non-reproducible-wasm --env 'RUSTFLAGS=--verbose -C link-arg=-s'
This variable is always unset during build, so
`bash`
CARGO_ENCODED_RUSTFLAGS="your_custom_value" cargo near build non-reproducible-wasm"your_custom_value"` affecting the build.
won't result in
This is so to avoid weird issues like #287 when composing multiple builds via build scripts.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as below, without any additional terms or conditions.
Licensed under either of
* Apache License, Version 2.0
(LICENSE-APACHE or
* MIT license
(LICENSE-MIT or
at your option.