diff --git a/docs/src/.vuepress/config.js b/docs/src/.vuepress/config.js index 46d6be73f..1f1cdea24 100755 --- a/docs/src/.vuepress/config.js +++ b/docs/src/.vuepress/config.js @@ -74,6 +74,14 @@ module.exports = { "/cli/commands", ], }, + { + collapsable: false, + title: "Source Verification", + children: [ + "/getting-started/verification", + "/getting-started/publishing", + ], + }, ], nav: [ diff --git a/docs/src/getting-started/publishing.md b/docs/src/getting-started/publishing.md new file mode 100644 index 000000000..85db2ac5d --- /dev/null +++ b/docs/src/getting-started/publishing.md @@ -0,0 +1,85 @@ +# Publishing Source + +The Anchor Program Registry at [anchor.projectserum.com](https://anchor.projectserum.com) +hosts a catalog of verified programs on Solana both written with and without Anchor. It is recommended +that authors of smart contracts publish their source to promote best +practices for security and transparency. + +::: tip note +The Anchor Program Registry is currently in alpha testing. For access to publishing +please ask on [Discord](https://discord.gg/rg5ZZPmmTm). +::: + +## Getting Started + +The process for publishing is mostly identical to `crates.io`. + +* Signup for an account [here](https://anchor.projectserum.com/signup). +* Confirm your email by clicking the link sent to your address. +* Navigate to your Username -> Account Settings on the top navbar. +* Click "New Token" in the **API Access** section. +* Run `anchor login ` at the command line. + +And you're ready to interact with the registry. + +## Configuring a Build + +Whether your program is written in Anchor or not, all source being published must +have an `Anchor.toml` to define the build. + +An example `Anchor.toml` config looks as follows, + +```toml +anchor_version = "0.13.0" + +[workspace] +members = ["programs/multisig"] + +[provider] +cluster = "mainnet" +wallet = "~/.config/solana/id.json" + +[programs.mainnet] +multisig = { address = "A9HAbnCwoD6f2NkZobKFf6buJoN9gUVVvX5PoUnDHS6u", path = "./target/deploy/multisig.so", idl = "./target/idl/multisig.json" } +``` + +Here there are four sections. + +1. `anchor_version` (optional) - sets the anchor docker image to use. By default, the builder will use the latest version of Anchor. +2. `[workspace]` (optional) - sets the paths--relative to the `Anchor.toml`-- + to all programs in the local + workspace, i.e., the path to the `Cargo.toml` manifest associated with each + program that can be compiled by the `anchor` CLI. For programs using the + standard Anchor workflow, this can be ommitted. For programs not written in Anchor + but still want to publish, this should be added. +3. `[provider]` - configures the wallet and cluster settings. Here, `mainnet` is used because the registry only supports `mainnet` binary verification at the moment. +3. `[programs.mainnet]` - configures each program in the workpace. Here the + `address` of the program to verify and the `path` to it's binary build artifact. For Anchor programs with an **IDL**, an `idl = ""` field should also be provided. + +::: tip +When defining program in `[programs.mainnet]`, make sure the name provided +matches the **lib** name for your program, which is defined +by your program's Cargo.toml. +::: + +### Examples + +#### Anchor Program + +An example of a toml file for an Anchor program can be found [here](https://anchor.projectserum.com/build/2). + +#### Non Anchor Program + +An example of a toml file for a non-anchor program can be found [here](https://anchor.projectserum.com/build/1). + +## Publishing + +To publish to the Anchor Program Registry, change directories to the `Anchor.toml` +defined root and run + +```bash +anchor publish +``` + +where `` is as defined in `[programs.mainnet]`, i.e., `multisig` +in the example above. diff --git a/docs/src/getting-started/verification.md b/docs/src/getting-started/verification.md new file mode 100644 index 000000000..952a45894 --- /dev/null +++ b/docs/src/getting-started/verification.md @@ -0,0 +1,50 @@ +# Verifiable Builds + +Building programs with the Solana CLI may embed machine specfic +code into the resulting binary. As a result, building the same program +on different machines may produce different executables. To get around this +problem, one can build inside a docker image with pinned dependencies to produce +a verifiable build. + +Anchor makes this easy by providing CLI commands to build take care of +docker for you. To get started, first make sure you +[install](https://docs.docker.com/get-docker/) docker on your local machine. + +## Building + +To produce a verifiable build, run + +```bash +anchor build --verifiable +``` + +## Verifying + +To verify a build against a program deployed on mainnet, run + +```bash +anchor verify +``` + +If the program has an IDL, it will also check the IDL deployed on chain matches. + +## Images + +A docker image for each version of Anchor is published on [Docker Hub](https://hub.docker.com/r/projectserum/build). They are tagged in the form `projectserum/build:`. For example, to get the image for Anchor `v0.13.0` one can run + +``` +docker pull projectserum/build:v0.13.0 +``` + +## Removing an Image + In the event you run a verifiable build from the CLI and exit prematurely, + it's possible the docker image may still be building in the background. + +To remove, run + +``` +docker rm -f anchor-program +``` + +where `anchor-program` is the name of the image created by default from within +the Anchor CLI.