diff --git a/docs/advanced/confirmation.md b/docs/advanced/confirmation.md index a4d1ae3bc..3d11b4975 100644 --- a/docs/advanced/confirmation.md +++ b/docs/advanced/confirmation.md @@ -194,7 +194,7 @@ decreased, users don't have enough time to submit their transaction. Currently, Solana clusters require that transactions use blockhashes that are no more than 151 blocks old. -> This [Github issue](https://github.com/solana-labs/solana/issues/23582) +> This [GitHub issue](https://github.com/solana-labs/solana/issues/23582) > contains some calculations that estimate that mainnet-beta validators need > about 150MB of memory to track transactions. This could be slimmed down in the > future if necessary without decreasing expiration time as are detailed in that diff --git a/docs/advanced/index.md b/docs/advanced/index.md index 11ae9d7f4..82a978635 100644 --- a/docs/advanced/index.md +++ b/docs/advanced/index.md @@ -1,5 +1,5 @@ --- metaOnly: true title: Advanced Topics -sidebarSortOrder: 3 +sidebarSortOrder: 5 --- diff --git a/docs/core/transactions.md b/docs/core/transactions.md index 68bcc3109..be799bdef 100644 --- a/docs/core/transactions.md +++ b/docs/core/transactions.md @@ -155,7 +155,8 @@ specifies the privileges of accounts included in the transaction's account address array. It is comprised of three bytes, each containing a u8 integer, which collectively specify: -1. The number of required signatures for the transaction and message version number. +1. The number of required signatures for the transaction and message version + number. 2. The number of read-only account addresses that require signatures. 3. The number of read-only account addresses that do not require signatures. diff --git a/docs/programs/index.md b/docs/programs/index.md index 4189752bd..2fe2648e0 100644 --- a/docs/programs/index.md +++ b/docs/programs/index.md @@ -1,5 +1,5 @@ --- title: Developing Programs -sidebarSortOrder: 2 +sidebarSortOrder: 4 metaOnly: true --- diff --git a/docs/toolkit/best-practices.md b/docs/toolkit/best-practices.md new file mode 100644 index 000000000..28c16507a --- /dev/null +++ b/docs/toolkit/best-practices.md @@ -0,0 +1,119 @@ +--- +title: Solana Smart Contract Best Practices +sidebarSortOrder: 3 +sidebarLabel: Best Practices +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +## Optimize Compute Usage + +To prevent abuse of computational resources, each transaction is allocated a +"compute budget". This budget specifies details about +[compute units](https://solana.com/docs/core/fees#compute-units) and includes: + +- the compute costs associated with different types of operations the + transaction may perform (compute units consumed per operation), +- the maximum number of compute units that a transaction can consume (compute + unit limit), +- and the operational bounds the transaction must adhere to (like account data + size limits) + +When the transaction consumes its entire compute budget (compute budget +exhaustion), or exceeds a bound such as attempting to exceed the +[max call stack depth](https://github.com/anza-xyz/agave/blob/b7bbe36918f23d98e2e73502e3c4cba78d395ba9/program-runtime/src/compute_budget.rs#L138) +or +[max loaded account](https://solana.com/docs/core/fees#accounts-data-size-limit) +data size limit, the runtime halts the transaction processing and returns an +error. Resulting in a failed transaction and no state changes (aside from the +transaction fee being +[collected](https://solana.com/docs/core/fees#fee-collection)). + +### Additional References + +- [How to Optimize Compute](https://solana.com/developers/guides/advanced/how-to-optimize-compute). +- [How to Request Optimal Compute](https://solana.com/developers/guides/advanced/how-to-request-optimal-compute) + +## Saving Bumps + +> Program Derived Address (PDAs) are addresses that PDAs are addresses that are +> deterministically derived and look like standard public keys, but have no +> associated private keys. These PDAs are derived using a numerical value, +> called a "bump", to guarantee that the PDA is off-curve and cannot have an +> associated private key. It "bumps" the address off the cryptographic curve. + +Saving the bump to your Solana smart contract account state ensures +deterministic address generation, efficiency in address reconstruction, reduced +transaction failure, and consistency across invocations. + +### Additional References + +- [How to derive a PDA](/docs/core/pda.md#how-to-derive-a-pda) +- [PDA Bumps Core Concepts](/docs/core/pda.md#canonical-bump) +- [Bump Seed Canonicalization Lesson](https://solana.com/developers/courses/program-security/bump-seed-canonicalization) + +## Payer-Authority Pattern + +The Payer-Authority pattern is an elegant way to handle situations where the +account’s funder (payer) differs from the account’s owner or manager +(authority). By requiring separate signers and validating them in your onchain +logic, you can maintain clear, robust, and flexible ownership semantics in your +program. + +### Shank Example + +```rust +// Create a new account. +#[account(0, writable, signer, name="account", desc = "The address of the new account")] +#[account(1, writable, signer, name="payer", desc = "The account paying for the storage fees")] +#[account(2, optional, signer, name="authority", desc = "The authority signing for the account creation")] +#[account(3, name="system_program", desc = "The system program")] +CreateAccountV1(CreateAccountV1Args), +``` + +### Anchor Example + +```rust +#[derive(Accounts)] +pub struct CreateAccount<'info> { + /// The address of the new account + #[account(init, payer = payer_one, space = 8 + NewAccount::MAXIMUM_SIZE)] + pub account: Account<'info, NewAccount>, + + /// The account paying for the storage fees + #[account(mut)] + pub payer: Signer<'info>, + + /// The authority signing for the account creation + pub authority: Option>, + + // The system program + pub system_program: Program<'info, System> +} +``` + +### Additional References + +- [Metaplex Guide on Payer-Authority Pattern](https://developers.metaplex.com/guides/general/payer-authority-pattern) +- [Helium Program Library using the Payer-Authority Pattern](https://github.com/helium/helium-program-library/blob/master/programs/data-credits/src/instructions/change_delegated_sub_dao_v0.rs#L18) + +## Invariants + +Implement invariants, which are functions that you can call at the end of your +instruction to assert specific properties because they help ensure the +correctness and reliability of programs. + +```rust +require!(amount > 0, ErrorCode::InvalidAmount); +``` + +### Additional References + +- [Complete Project Code Example](https://github.com/solana-developers/developer-bootcamp-2024/blob/main/project-9-token-lottery/programs/token-lottery/src/lib.rs#L291) + +## Optimize Indexing + +You can make indexing easier by placing static size fields at the beginning and +variable size fields at the end of your onchain structures. diff --git a/docs/toolkit/getting-started.md b/docs/toolkit/getting-started.md new file mode 100644 index 000000000..9d8d1275a --- /dev/null +++ b/docs/toolkit/getting-started.md @@ -0,0 +1,91 @@ +--- +sidebarSortOrder: 1 +sidebarLabel: Getting Started +title: Getting Started with the Solana Toolkit +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +The Solana Program development toolkit is publish as the +[`mucho` npm package](https://www.npmjs.com/package/mucho). The `mucho` command +will be used to run most of the Solana program development tools within the +toolkit - _mucho tools, one cli_. + +## Installation + +To get started, install The Solana Toolkit: + +```shell +npx -y mucho@latest install +``` + +This will install the latest versions of the following: + +- [Solana CLI / Agave Tool Suite](https://docs.anza.xyz/cli/): A command line + tool that allows developers to interact with the Solana blockchain, manage + accounts, send transactions, and deploy programs. +- [Mucho CLI](https://github.com/solana-developers/mucho) - a superset of + popular developer tools within the Solana ecosystem used to simplify the + development and testing of Solana blockchain programs. +- [Rust](https://doc.rust-lang.org/book/): The programming language that Solana + Smart Contracts are written in. +- [Anchor](https://www.anchor-lang.com/): A framework for writing Solana + programs that abstracts many complexities to speed up smart contract + development. +- [Fuzz Tester](https://ackee.xyz/trident/docs/latest/): Rust-based fuzzing + framework for Solana programs to help you ship secure code. +- [Code Coverage Tool](https://github.com/LimeChain/zest?tab=readme-ov-file): A + code coverage CLI tool for Solana programs. + +## Generate a keypair + +For a fresh installation of the [Solana CLI](https://docs.anza.xyz/cli/), you're +required to generate a new keypair. + +```shell +solana-keygen new +``` + +_This will store the your new keypair at the Solana CLI's default path +(`~/.config/solana/id.json`) and print the pubkey that was generated._ + +## Get your keypair's public key + +```shell +solana address +``` + +## Fund your keypair + +```shell +solana airdrop 10 --url localhost +``` + +## Set your network configuration + +Check your current config: + +```shell +solana config get +``` + +To use this toolkit, update your config to connect to localhost: + +```shell +solana config set --url localhost +``` + +To test locally, you must also spin up a local node to run on your localhost: + +```shell +mucho validator +``` + +For a more information, read the +[Local Testing Guide](/docs/toolkit/local-validator.md). + +## Next Steps + +Now let's [Create a Solana Project](/docs/toolkit/projects/overview.md)! diff --git a/docs/toolkit/index.md b/docs/toolkit/index.md new file mode 100644 index 000000000..44f166f22 --- /dev/null +++ b/docs/toolkit/index.md @@ -0,0 +1,18 @@ +--- +title: The Solana Toolkit +sidebarSortOrder: 3 +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +The Solana Program development toolkit is published as the +[`mucho` npm package](https://www.npmjs.com/package/mucho). The `mucho` command +will be used to run most of the Solana program development tools - _mucho tools, +one cli_. + +You can contribute to this +[Toolkit book on GitHub](https://github.com/solana-foundation/developer-content/tree/main/docs/toolkit). + +Now let's [Get Started](/docs/toolkit/getting-started.md)! diff --git a/docs/toolkit/local-validator.md b/docs/toolkit/local-validator.md new file mode 100644 index 000000000..c21323f2b --- /dev/null +++ b/docs/toolkit/local-validator.md @@ -0,0 +1,294 @@ +--- +title: Running a Local Solana Validator Network +sidebarSortOrder: 4 +sidebarLabel: Local Validator +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +The Solana test validator is a local emulator for the Solana blockchain, +designed to provide developers with a private and controlled environment for +building and testing Solana programs without the need to connect to a public +testnet or mainnet. It also includes full support of the standard +[Solana RPC standard](/docs/rpc/http/index.mdx). + +If you have the Solana CLI tool suite already installed, you can run the test +validator with the following command: + +```shell +mucho validator --help +``` + +> Install the [Solana Toolkit](/docs/toolkit/getting-started#installation) by +> running the following command: +> +> ```shell +> npx -y mucho@latest install +> ``` + +## Advantages + +- Ability to reset the blockchain state at any moment +- Ability to simulate different network conditions +- No RPC rate-limits +- No airdrop limits +- Direct onchain program deployment +- Ability to clone accounts and programs from a public cluster (i.e. devnet, + mainnet, etc) +- Ability to load accounts and programs from files +- Configurable transaction history retention +- Configurable epoch length + +## Starting the Test Validator + +To start your local validator, simply run: + +```shell +mucho validator +``` + +This command initializes a new ledger and starts the local validator running at +`http://localhost:8899`, which can be used as your Solana RPC connection url. + +## Connecting to the Test Validator + +To connect to the local test validator with the Solana CLI: + +```shell +solana config set --url localhost +``` + +This will ensure all your Solana CLI commands will be directed to your local +test validator. + +## Checking the Status of the Test Validator + +Before interacting with the test validator, it's useful to confirm its status +and ensure it is running correctly. + +```shell +solana ping +``` + +This command pings the local test validator and returns the current blockhash +and latency, verifying that it is active. + +## Deploying and Managing Programs Locally + +To deploy a compiled program (BPF) to the test validator: + +```shell +solana program deploy +``` + +This uploads and deploys a program to the blockchain. + +To check the details of a deployed program: + +```shell +solana program show +``` + +## Sending Transactions + +To transfer SOL from one account to another: + +```shell +solana transfer --from /path/to/keypair.json +``` + +This sends `AMOUNT` of SOL from the source account to the `RECIPIENT_ADDRESS`. + +## Simulating and Confirming Transactions + +Before actually sending a transaction, you can simulate it to see if it would +likely succeed: + +```shell +solana transfer --from /path/to/keypair.json \ + --simulate +``` + +To confirm the details and status of a transaction: + +```shell +solana confirm +``` + +## Viewing Recent Block Production + +To see information about recent block production, which can be useful for +debugging performance issues: + +```shell +solana block-production +``` + +## Validator Logs + +For debugging, you might want more detailed logs: + +```shell +solana logs +``` + +This streams log messages from the validator. + +### Tips for Logging + +- Increase log verbosity with the `-v` flag if you need more detailed output for + debugging. +- Use the `--rpc-port` and `--rpc-bind-address` options to customize the RPC + server settings. +- Adjust the number of CPU cores used by the validator with the `--gossip-host` + option to simulate network conditions more realistically. + +## Configuration + +View all the configuration options available for the Solana test validator: + +```shell +mucho validator --help +``` + +## Local Ledger + +By default, the ledger data is stored in a directory named `test-ledger` in your +current working directory. + +### Specifying Ledger Location + +When starting the test validator, you can specify a different directory for the +ledger data using the `--ledger` option: + +```shell +mucho validator --ledger /path/to/custom/ledger +``` + +## Resetting the Ledger + +By default the validator will resume an existing ledger, if one is found. To +reset the ledger, you can either manually delete the ledger directory or restart +the validator with the `--reset` flag: + +```shell +mucho validator --reset +``` + +If the ledger exists, this command will reset the ledger to genesis, which +resets the state by deleting all existing accounts/programs and starting fresh. + +## Cloning Programs + +To add existing onchain programs to your local environment, you can clone the +program with a new ledger. This is useful for testing interactions with other +programs that already exist on any other cluster. + +To clone an account from another cluster: + +```shell +mucho validator --reset \ + --url CLUSTER_PROGRAM_IS_DEPLOYED_TO \ + --clone PROGRAM_ADDRESS +``` + +To clone an upgradeable program and its executable data from another cluster: + +```shell +mucho validator --reset \ + --url CLUSTER_PROGRAM_IS_DEPLOYED_TO \ + --clone-upgradeable-program PROGRAM_ADDRESS +``` + +> If a ledger already exists in your working directory, you must reset the +> ledger to be able to clone a program or account. + +## Cloning Accounts + +To add existing onchain accounts to your local environment, you can clone the +account with a new ledger from any other network cluster. + +To clone an account from the cluster when a ledger already exists: + +```shell +mucho validator --reset \ + --url CLUSTER_PROGRAM_IS_DEPLOYED_TO \ + --clone ACCOUNT_ADDRESS +``` + +## Reset to Specific Account Data + +To reset the state of specific accounts every time you start the validator, you +can use a combination of account snapshots and the `--account` flag. + +First, save the desired state of an account as a JSON file: + +```shell +solana account ACCOUNT_ADDRESS --output json --output-file account_state.json +``` + +Then load this state each time you reset the validator: + +```shell +mucho validator --reset \ + --account ACCOUNT_ADDRESS account_state.json +``` + +## Runtime Features + +Solana has a feature set mechanism that allows you to enable or disable certain +blockchain features when running the test validator. By default, the test +validator runs with all runtime features activated. + +To see all the runtime features available and their statuses: + +```shell +solana feature status +``` + +To query a specific runtime feature's status: + +```shell +solana feature status
+``` + +To deactivate specific features in genesis: + +> This must be done on a fresh ledger, so if a ledger already exists in your +> working directory you must add the `--reset` flag to reset to genesis. + +```shell +mucho validator --reset \ + --deactivate-feature +``` + +To deactivate multiple features in genesis: + +```shell +mucho validator --reset \ + --deactivate-feature +``` + +## Changing Versions + +To check your current `solana-test-validator` version: + +```shell +mucho validator --version +``` + +Your test validator runs on the same version as the Solana CLI installed and +configured for use. + +To test your programs against different versions of the Solana runtime, you can +install multiple versions of the Solana CLI and switch between them using the +following command: + +```shell +solana-install init +``` + +Make sure to reset your Solana test validator's ledger after changing versions +to ensure it runs a valid ledger without corruption. diff --git a/docs/toolkit/projects/anchor-init.md b/docs/toolkit/projects/anchor-init.md new file mode 100644 index 000000000..d14d19fba --- /dev/null +++ b/docs/toolkit/projects/anchor-init.md @@ -0,0 +1,75 @@ +--- +title: Basic Anchor Smart Contracts +sidebarSortOrder: 2 +sidebarLabel: Basic Anchor +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +```shell +anchor init +``` + +## Overview + +This initializes a simplistic workspace set up for Anchor smart contract +development, with the following structure: + +- `Anchor.toml`: Anchor configuration file. +- `Cargo.toml`: Rust workspace configuration file. +- `package.json`: JavaScript dependencies file. +- `programs/`: Directory for Solana program crates. +- `app/`: Directory for your application frontend. +- `tests/`: Directory for JavaScript integration tests. +- `migrations/deploy.js`: Deploy script. + +The Anchor framework abstracts away many complexities enabling fast program +development. + +## Build and Test + +To test out this project before making any modifications, just build and test: + +```shell +anchor build +``` + +```shell +anchor test +``` + +To start writing your own Anchor smart contract, navigate to +`programs/src/lib.rs`. + +## File Structure Template + +For more complex programs, using a more structured project template would be the +best practice. This can be generated with: + +```shell +anchor init --template multiple +``` + +Which creates the following layout inside of `programs/src`: + +```shell +├── constants.rs +├── error.rs +├── instructions +│ ├── initialize.rs +│ └── mod.rs +├── lib.rs +└── state + └── mod.rs +``` + +For project file structure best practices, review this +[document](/docs/toolkit/projects/project-layout.md). + +## Additional Resources + +- [Anchor book](https://www.anchor-lang.com/) +- [Getting Started with Anchor](/docs/programs/anchor/index.md) +- [Program Examples](https://github.com/solana-developers/program-examples) diff --git a/docs/toolkit/projects/existing-project.md b/docs/toolkit/projects/existing-project.md new file mode 100644 index 000000000..6f7ccde8d --- /dev/null +++ b/docs/toolkit/projects/existing-project.md @@ -0,0 +1,67 @@ +--- +title: Update an Existing Project +sidebarSortOrder: 7 +sidebarLabel: Existing Projects +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +If you have an existing Anchor program and want to use the +[`create-solana-program`](https://github.com/solana-program/create-solana-program) +tool, you can easily replace the generated program with your existing one: + + + +### Verify correct versions + +Ensure the installed Solana and Anchor versions are the same as the ones your +existing program requires. + +### Run create-solana-program + +Scaffold a new Solana program using Anchor by running: + +```shell +npx create-solana-program --anchor +``` + +### Migrate your program source code + +Replace the `program` folder with your existing program directory (not the +workspace directory). If you have more than one program, add more folders to the +root directory and update the `members` attribute of the top-level `Cargo.toml` +accordingly. + +### Update each program's Cargo.toml + +Ensure your program’s `Cargo.toml` contains the following metadata: + +```toml filename="Cargo.toml" +[package.metadata.solana] +program-id = "YOUR_PROGRAM_ADDRESS" +program-dependencies = [] +``` + +### Build your program and clients + +Run the following commands to build your programs and generate the clients: + +```shell +npm install +npm run programs:build +npm run generate +``` + +### Update the ID alias + +If you have a generated Rust client, update the `clients/rust/src/lib.rs` file +so the `ID` alias points to the correct generated constant. + +### Update any client tests + +If you have any generated clients, update the scaffolded tests so they work with +your existing program. + + diff --git a/docs/toolkit/projects/index.md b/docs/toolkit/projects/index.md new file mode 100644 index 000000000..a6df26408 --- /dev/null +++ b/docs/toolkit/projects/index.md @@ -0,0 +1,5 @@ +--- +title: Creating a Project +sidebarSortOrder: 2 +metaOnly: true +--- diff --git a/docs/toolkit/projects/mobile-app.md b/docs/toolkit/projects/mobile-app.md new file mode 100644 index 000000000..91eaac778 --- /dev/null +++ b/docs/toolkit/projects/mobile-app.md @@ -0,0 +1,42 @@ +--- +title: Mobile App with a Smart Contract Connection +sidebarSortOrder: 6 +sidebarLabel: Mobile App +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +```shell +yarn create expo-app --template @solana-mobile/solana-mobile-expo-template +``` + +## Overview + +This will initialize a new project using the [Expo](https://expo.dev) framework +that is specifically designed for creating mobile applications that interact +with the Solana blockchain. + +Follow this template's guide for +"[Running the app](https://docs.solanamobile.com/react-native/expo#running-the-app)" +in order to launch the template as a custom development build and get it running +on your Android emulator. Once you have built the program and are running a dev +client with Expo, the emulator will automatically update every time you save +your code. + +## Prerequisites + +To use this template, you will also need to set up the following: + +- [Android Studio and Emulator](https://docs.solanamobile.com/getting-started/development-setup) +- [React Native](https://reactnative.dev/docs/environment-setup?platform=android) +- [EAS CLI and Account](https://docs.expo.dev/build/setup/) + +## Additional Resources + +- [Solana Mobile Development](https://docs.solanamobile.com/getting-started/intro) +- [Mobile App Example - Cash App Clone](/content/guides/dapps/cash-app.md) +- [Anchor book](https://www.anchor-lang.com/) +- [Getting Started with Anchor](/docs/programs/anchor/index.md) +- [Program Examples](https://github.com/solana-developers/program-examples) diff --git a/docs/toolkit/projects/overview.md b/docs/toolkit/projects/overview.md new file mode 100644 index 000000000..32b5b8e14 --- /dev/null +++ b/docs/toolkit/projects/overview.md @@ -0,0 +1,77 @@ +--- +title: Smart Contract Project Templates +sidebarSortOrder: 1 +sidebarLabel: Overview +altRoutes: + - /docs/toolkit/projects +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +Choose from one of the below scaffolds to generate a new project workspace: + +- [Anchor](#anchor) - A popular Rust-based framework for creating Solana smart + contracts. +- [`create-solana-program`](#create-solana-program) - In-depth workspace + generator for either Anchor smart contract development or Native smart + contract, including JavaScript and Rust clients. +- [Web App Templates](#web-app-template) - Generator for new projects that + connects a Solana smart contract to various frontend stacks, includes wallet + connector setup. + +## Anchor + +```shell +anchor init +``` + +This generates a basic workspace to be able to write an Anchor rust smart +contracts, build, test, and deploy. For more information, read the +[`anchor init` doc](/docs/toolkit/projects/anchor-init.md). + +## Create Solana Program + +```shell +npx create-solana-program +``` + +This generates an in-depth workspace for either Anchor smart contract +development or Native smart contract development with either a Javascript +Client, Rust Client, or both. For more information, read the +[`create-solana-program` doc](/docs/toolkit/projects/solana-program.md). + +## Web App Template + +```shell +npx create-solana-dapp +``` + +This initializes a new project that connects a Solana smart contract to a +typescript frontend with a wallet connector. For more information, read the +[web app template doc](/docs/toolkit/projects/web-app.md). + +## Mobile App Template + +```shell +yarn create expo-app --template @solana-mobile/solana-mobile-expo-template +``` + +This is initializing a new project using the Expo framework that is specifically +designed for creating mobile applications that interact with the Solana +blockchain. + +## Update an Existing Project + +```shell +npx create-solana-program +``` + +You can add the Solana program scaffold to an existing project by following this +[guide](/docs/toolkit/projects/existing-project.md). + +## Standard Project Layouts + +For best practices on smart contract file structure, read this +[guide](/docs/toolkit/projects/project-layout.md). diff --git a/docs/toolkit/projects/project-layout.md b/docs/toolkit/projects/project-layout.md new file mode 100644 index 000000000..4c6cf631f --- /dev/null +++ b/docs/toolkit/projects/project-layout.md @@ -0,0 +1,74 @@ +--- +title: Smart Contract Repo File Structure +sidebarSortOrder: 8 +sidebarLabel: Project layout +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +Typically Solana smart contracts (aka [programs](/docs/core/programs.md)) +workspaces will be have the following file structure: + +```shell +. +├── app +├── migrations +├── node_modules +├── programs +├── target +└── tests +``` + +The main smart contract is the `lib.rs` file, which lives insides the `programs` +directory, as shown below: + +```shell +. +├── app +├── migrations +├── node_modules +├── programs + ├── src + ├── lib.rs +├── target +└── tests +``` + +As the smart contract gets more cumbersome, you'll typically want to separate +the logic into multiple files, as shown below: + +```shell +├── programs + ├── src + ├── state.rs + ├── instructions + ├── instruction_1.rs + ├── instruction_2.rs + ├── instruction_3.rs + ├── lib.rs + ├── constants.rs + ├── error.rs + ├── mod.rs +``` + +For [native rust smart contract development](/docs/programs/rust/index.md), you +need to explicitly write out the entrypoint and processor for the program, so +you'll need a few more files: + +```shell +├── program.rs +│ ├── src.rs +│ │ ├──assertions.rs +│ │ ├──entrypoint.rs +│ │ ├──error.rs +│ │ ├──instruction.rs +│ │ ├──lib.rs +│ │ ├──processor.rs +│ │ ├──state.rs +│ │ ├──utils.rs +│ ├── Cargo.toml +│ ├── keypair.json +│ ├── README.md +``` diff --git a/docs/toolkit/projects/solana-program.md b/docs/toolkit/projects/solana-program.md new file mode 100644 index 000000000..f31290980 --- /dev/null +++ b/docs/toolkit/projects/solana-program.md @@ -0,0 +1,103 @@ +--- +title: Solana Program Scaffold +sidebarSortOrder: 3 +sidebarLabel: Solana Programs +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +```shell +npx create-solana-program +``` + +[`create-solana-program`](https://github.com/solana-program/create-solana-program) +initializes an in-depth workspace with everything you need for general Solana +smart contract development. This scaffold allows you to write either native rust +smart contracts or Anchor smart contracts. + +## Program Frameworks + +After running this command, you'll have the option to choose between Shank and +Anchor for the program framework: + +- **Shank** creates a vanilla Solana smart contract with Shank macros to + generate IDLs. For more information on Shank, read its + [README](https://github.com/metaplex-foundation/shank). + +- **Anchor** creates a smart contract using the Anchor framework, which + abstracts away many complexities enabling fast program development. For more + information on the Anchor framework, read the + [Anchor book](https://www.anchor-lang.com/). + +### Anchor framework + +For **Anchor rust development**, chose Anchor when asked which program framework +to use. This will create a basic Anchor counter program with the following +project structure for your program: + +```shell +├── program.rs +│ ├── src.rs +│ │ ├── lib.rs +│ ├── Cargo.toml +│ ├── keypair.json +│ ├── README.md +``` + +### Native rust + +For **native rust development**, make sure you chose Shank when asked which +program framework to use. This will create a basic counter program with the +following project structure for your program: + +```shell +├── program.rs +│ ├── src.rs +│ │ ├── assertions.rs +│ │ ├──entrypoint.rs +│ │ ├──error.rs +│ │ ├──instruction.rs +│ │ ├──lib.rs +│ │ ├──processor.rs +│ │ ├──state.rs +│ │ ├──utils.rs +│ ├── Cargo.toml +│ ├── keypair.json +│ ├── README.md +``` + +## Generated Clients + +Next, you'll have the option to choose between a JavaScript client, a Rust +Client, or both. + +- **JavaScript Client** creates a typescript library compatible with + [web3.js](https://solana-labs.github.io/solana-web3.js/). + +- **Rust Client** creates a rust crate allowing consumers to interact with the + smart contract. + +For further workspace customization and additional information, check out the +`create-solana-program` +[README](https://github.com/solana-program/create-solana-program?tab=readme-ov-file). + +## Build + +After answering the above prompts, the workspace will be generated. To get +started, build your program and clients by running: + +```shell +cd +npm install +npm run generate +``` + +To update an existing Anchor project to have this scaffold, read this +[guide](/docs/toolkit/projects/existing-project.md). + +## Additional Resources + +- [Developing Rust Programs](/docs/programs/rust/index.md) +- [Program Examples](https://github.com/solana-developers/program-examples) diff --git a/docs/toolkit/projects/web-app.md b/docs/toolkit/projects/web-app.md new file mode 100644 index 000000000..8a3f5e521 --- /dev/null +++ b/docs/toolkit/projects/web-app.md @@ -0,0 +1,69 @@ +--- +title: Web App with a Smart Contract Connection +sidebarSortOrder: 5 +sidebarLabel: Web App +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +```shell +npx create-solana-dapp +``` + +This command generates a new project that connects a Solana smart contract to a +frontend with a wallet connector. It has options for multiple popular frontend +stacks and UI libraries, including: NextJS, React, Tailwind, and more. + +## Build and Test + +To test out this project before making any modifications, follow these steps: + + + +### Build the smart contract + +```shell +npm run anchor-build +``` + +### Start the local validator + +```shell +npm run anchor-localnet +``` + +### Run tests + +```shell +npm run anchor-test +``` + +### Deploy to the local validator + +```shell +npm run anchor deploy --provider.cluster localnet +``` + +### Build the web app + +```shell +npm run build +``` + +### Run the web app + +```shell +npm run dev +``` + + + +## Additional Resources + +- [`create-solana-dapp` README](https://github.com/solana-developers/create-solana-dapp) +- [CRUD App Example](/content/guides/dapps/journal.md) +- [Anchor book](https://www.anchor-lang.com/) +- [Getting Started with Anchor](/docs/programs/anchor/index.md) +- [Program Examples](https://github.com/solana-developers/program-examples) diff --git a/docs/toolkit/test-suite/basics.md b/docs/toolkit/test-suite/basics.md new file mode 100644 index 000000000..fab6522ab --- /dev/null +++ b/docs/toolkit/test-suite/basics.md @@ -0,0 +1,52 @@ +--- +sidebarLabel: Testing Basics +title: Solana Testing Basics +sidebarSortOrder: 2 +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +## Installation + +Install the Solana Toolkit by running the following command: + +```shell +npx -y mucho@latest install +``` + +## Build + +```shell +mucho build +``` + +## Start Localnet + +```shell +mucho validator +``` + +## Run Tests + +Anchor Programs: + +```shell +anchor test +``` + +Native Programs: + +```shell +cargo test +``` + +## Deploy + +```shell +mucho deploy +``` + +For more information on local validator customization and commands, read the +[Solana Test Validator Guide](/content/guides/getstarted/solana-test-validator.md). diff --git a/docs/toolkit/test-suite/code-coverage.md b/docs/toolkit/test-suite/code-coverage.md new file mode 100644 index 000000000..c02e70a4c --- /dev/null +++ b/docs/toolkit/test-suite/code-coverage.md @@ -0,0 +1,26 @@ +--- +title: Solana Code Coverage Tool +sidebarSortOrder: 3 +sidebarLabel: Code Coverage +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +```shell +mucho coverage +``` + +## Overview + +This command will run a code coverage test on all of your Rust tests and then +generates a report as an HTML page providing metrics on where additional tests +may be needed to improve your current code coverage. + +> Currently, this tool only works on tests written in Rust and is not compatible +> with a JavaScript test suite. + +## Additional Resources + +- [Source Code](https://github.com/LimeChain/zest?tab=readme-ov-file) diff --git a/docs/toolkit/test-suite/fuzz-tester.md b/docs/toolkit/test-suite/fuzz-tester.md new file mode 100644 index 000000000..20eeba331 --- /dev/null +++ b/docs/toolkit/test-suite/fuzz-tester.md @@ -0,0 +1,76 @@ +--- +title: Solana Fuzz Tester +sidebarSortOrder: 4 +sidebarLabel: Fuzz Tester +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +> The Trident fuzz tester is still a WIP and currently only Anchor compatible +> may require some manual work to complete tests. + +## Initialize Fuzz Tests + +Navigate to an Anchor based workspace and run: + +```shell +trident init +``` + +This command does the following: + +- Builds the Anchor-based project. +- Reads the generated IDL. +- Based on the IDL creates the fuzzing template. + +## Define Fuzz Accounts + +Define `AccountsStorage` type for each `Account` you would like to use: + +```rust +#[doc = r" Use AccountsStorage where T can be one of:"] +#[doc = r" Keypair, PdaStore, TokenStore, MintStore, ProgramStore"] +#[derive(Default)] +pub struct FuzzAccounts { + author: AccountsStorage, + hello_world_account: AccountsStorage, + // No need to fuzz system_program + // system_program: AccountsStorage, +} +``` + +## Implement Fuzz Instructions + +Each Instruction in the fuzz test has to have defined the following functions: + +- `get_program_id()` specifies which program the instruction belongs to. This + function is automatically defined and should not need any updates. Its + important to use especially if you have multiple programs in your workspace, + allowing Trident to generate instruction sequences corresponding to different + programs. +- `get_data()` specifies what instruction inputs are sent to the program + instructions. +- `get_accounts()` specifies what accounts are sent to the program instructions. + +## Execute Fuzz Tests + +```shell +# Replace with the name of the +# fuzz test (for example: "fuzz_0") +trident fuzz run-hfuzz +``` + +## Debug Fuzz Tests + +```shell +# fuzzer will run the with the specified +trident fuzz debug-hfuzz +``` + +For additional documentation go [here](https://ackee.xyz/trident/docs/latest/). + +## Additional Resources + +- [Fuzz Tester Source Code](https://github.com/Ackee-Blockchain/trident). diff --git a/docs/toolkit/test-suite/index.md b/docs/toolkit/test-suite/index.md new file mode 100644 index 000000000..7b6ee1048 --- /dev/null +++ b/docs/toolkit/test-suite/index.md @@ -0,0 +1,5 @@ +--- +title: Test Suite +sidebarSortOrder: 5 +metaOnly: true +--- diff --git a/docs/toolkit/test-suite/js-test.md b/docs/toolkit/test-suite/js-test.md new file mode 100644 index 000000000..ea341d0ff --- /dev/null +++ b/docs/toolkit/test-suite/js-test.md @@ -0,0 +1,70 @@ +--- +title: JavaScript Testing Framework for Solana +sidebarSortOrder: 6 +sidebarLabel: JavaScript Tests +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +## Add Dependency + +Navigate to your smart contract directory and run: + +```shell +npm install solana-bankrun +``` + +## Bankrun Overview + +[Bankrun](https://github.com/kevinheavey/solana-bankrun) is a fast and +lightweight framework for testing Solana programs in NodeJS. + +It uses the +[`solana-program-test`](https://crates.io/crates/solana-program-test) crate +under the hood and allows you to do things that are not possible with +`solana-test-validator`, such as jumping back and forth in time or dynamically +setting account data. + +Bankrun works by spinning up a lightweight `BanksServer` that's like an RPC node +but much faster, and creating a `BanksClient` to talk to the server. This runs +the Solana +[Banks](https://github.com/solana-labs/solana/blob/master/runtime/src/bank.rs). + +## Minimal Example + +```javascript +import { start } from "solana-bankrun"; +import { PublicKey, Transaction, SystemProgram } from "@solana/web3.js"; + +test("one transfer", async () => { + const context = await start([], []); + const client = context.banksClient; + const payer = context.payer; + const receiver = PublicKey.unique(); + const blockhash = context.lastBlockhash; + const transferLamports = 1_000_000n; + const ixs = [ + SystemProgram.transfer({ + fromPubkey: payer.publicKey, + toPubkey: receiver, + lamports: transferLamports, + }), + ]; + const tx = new Transaction(); + tx.recentBlockhash = blockhash; + tx.add(...ixs); + tx.sign(payer); + await client.processTransaction(tx); + const balanceAfter = await client.getBalance(receiver); + expect(balanceAfter).toEqual(transferLamports); +}); +``` + +## Additional Resources + +- [Bankrun Docs](https://kevinheavey.github.io/solana-bankrun/) +- [Bankrun Source Code](https://github.com/kevinheavey/solana-bankrun) +- [Official Bankrun Tutorials](https://kevinheavey.github.io/solana-bankrun/tutorial/) +- [Complete Project Example](https://github.com/solana-developers/developer-bootcamp-2024/tree/main/project-2-voting/anchor/tests) diff --git a/docs/toolkit/test-suite/overview.md b/docs/toolkit/test-suite/overview.md new file mode 100644 index 000000000..1063aac6c --- /dev/null +++ b/docs/toolkit/test-suite/overview.md @@ -0,0 +1,24 @@ +--- +title: Solana Test Suite Overview +sidebarLabel: Overview +sidebarSortOrder: 1 +altRoutes: + - /docs/toolkit/test-suite +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +Within the Solana Toolkit, there are several resources for testing Solana Smart +Contracts, including: + +- A fuzz tester. +- A code coverage tool. +- A framework for testing Solana programs in NodeJS that spins up a lightweight + `BanksServer` that's like an RPC node but much faster and creates a + `BanksClient` to talk to the server. +- A fast and lightweight library for testing Solana programs in Rust, which + works by creating an in-process Solana VM optimized for program developers. +- A tool to scan your repo for common security vulnerabilities and provide + suggestions for fixes. diff --git a/docs/toolkit/test-suite/rust-tests.md b/docs/toolkit/test-suite/rust-tests.md new file mode 100644 index 000000000..670ac63a6 --- /dev/null +++ b/docs/toolkit/test-suite/rust-tests.md @@ -0,0 +1,63 @@ +--- +title: Rust Testing Framework for Solana +sidebarSortOrder: 7 +sidebarLabel: Rust Tests +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +## Add Dependency + +Navigate to your smart contract directory and run: + +```shell +cargo add --dev litesvm +``` + +## LiteSVM Overview + +[LiteSVM](https://github.com/LiteSVM/litesvm) is a fast and lightweight library +for testing Solana programs. It works by creating an in-process Solana VM +optimized for program developers. This makes it much faster to run and compile +than alternatives like +[`solana-program-test`](/docs/toolkit/test-suite/basics.md) and +[`solana-test-validator`](/docs/toolkit/local-validator.md). In a further break +from tradition, it has an ergonomic API with sane defaults and extensive +configurability for those who want it. + +## Minimal Example + +```rust +use litesvm::LiteSVM; +use solana_program::{message::Message, pubkey::Pubkey, system_instruction::transfer}; +use solana_sdk::{signature::Keypair, signer::Signer, transaction::Transaction}; + +let from_keypair = Keypair::new(); +let from = from_keypair.pubkey(); +let to = Pubkey::new_unique(); + +let mut svm = LiteSVM::new(); +svm.airdrop(&from, 10_000).unwrap(); + +let instruction = transfer(&from, &to, 64); +let tx = Transaction::new( + &[&from_keypair], + Message::new(&[instruction], Some(&from)), + svm.latest_blockhash(), +); +let tx_res = svm.send_transaction(tx).unwrap(); + +let from_account = svm.get_account(&from); +let to_account = svm.get_account(&to); +assert_eq!(from_account.unwrap().lamports, 4936); +assert_eq!(to_account.unwrap().lamports, 64); + +``` + +## Additional Resources + +- [Source Code](https://github.com/LiteSVM/litesvm) +- [Complete Project Example](https://github.com/cavemanloverboy/nawnce/blob/main/src/lib.rs) +- [More Complex Project Example](https://github.com/pyth-network/per) diff --git a/docs/toolkit/test-suite/security-scanner.md b/docs/toolkit/test-suite/security-scanner.md new file mode 100644 index 000000000..dce86340e --- /dev/null +++ b/docs/toolkit/test-suite/security-scanner.md @@ -0,0 +1,27 @@ +--- +title: Security Vulnerability Scanner +sidebarSortOrder: 5 +sidebarLabel: Security Scanner +--- + +> This is a beta version of the [Solana Toolkit](/docs/toolkit/index.md), and is +> still a WIP. Please post all feedback as a GitHub issue +> [here](https://github.com/solana-foundation/developer-content/issues/new?title=%5Btoolkit%5D%20). + +## Static Analysis Tools + +[Radar](https://github.com/Auditware/radar?tab=readme-ov-file) is static +analysis tool for Anchor rust programs. It allows you to write, share, and +utilize templates to identify security issues in rust-based smart contracts +using a powerful python based rule engine that enables automating detection of +vulnerable code patterns through logical expressions. + +[Xray](https://github.com/sec3-product/x-ray) is an open-source, cross-platform +command-line interface (CLI) tool designed for static analysis of Solana +programs and smart contracts written in Rust. + +## Common Security Exploits and Protections + +Read [Sealevel Attacks](https://github.com/coral-xyz/sealevel-attacks) for +examples of common exploits unique to the Solana programming model and +recommended idioms for avoiding these attacks using the Anchor framework. diff --git a/docs/toolkit/troubleshooting.md b/docs/toolkit/troubleshooting.md new file mode 100644 index 000000000..d1b781c04 --- /dev/null +++ b/docs/toolkit/troubleshooting.md @@ -0,0 +1,18 @@ +--- +title: Troubleshooting Solana Programs +sidebarSortOrder: 6 +sidebarLabel: Troubleshooting +--- + +When diagnosing problems with Solana development, you can easily gather loads of +troubleshooting information with the following command: + +```shell +npx mucho info +``` + +## Solana Stack Exchange + +The [Solana stack exchange](https://solana.stackexchange.com/) is the best place +for conversations around Solana development. If you ever get stuck, ask your +question [here](https://solana.stackexchange.com/questions/ask).