All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning (SemVer).
Note: Version 0 of Semantic Versioning is handled differently from version 1 and above. The minor version will be incremented upon a breaking change and the patch version will be incremented for features.
accounts_snapshots.rs (#141)fuzz to run and debug fuzz tests using honggfuzz-rs.--skip-fuzzer option for init subcommand to skip generation of fuzz test templates.fuzzing that enables optional dependencies related to fuzz testing.=1.16.6) and Anchor framework (=0.28.0) versions.async_rpc and async feature.accounts token.~1.10) and Anchor framework (~0.25) versions.program_client. User is able to import custom types and structures into program client. The import part of the code would not be re-generated.Trident.toml file to exist in the project's root directory - without this file the execution will fail. To solve this re-run trident init or just create an empty Trident.toml file in the project's root directory.All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning (SemVer).
Note: Version 0 of Semantic Versioning is handled differently from version 1 and above. The minor version will be incremented upon a breaking change and the patch version will be incremented for features.
accounts_snapshots.rs (#141)fuzz to run and debug fuzz tests using honggfuzz-rs.--skip-fuzzer option for init subcommand to skip generation of fuzz test templates.fuzzing that enables optional dependencies related to fuzz testing.=1.16.6) and Anchor framework (=0.28.0) versions.async_rpc and async feature.accounts token.~1.10) and Anchor framework (~0.25) versions.program_client. User is able to import custom types and structures into program client. The import part of the code would not be re-generated.Trident.toml file to exist in the project's root directory - without this file the execution will fail. To solve this re-run trident init or just create an empty Trident.toml file in the project's root directory.This section summarizes some known limitations in the current development stage. Further development will be focused on resolving these limitations.
This section summarizes some known limitations in the current development stage. Further development will be focused on resolving these limitations.
Fuzzing is a software testing technique that involves providing invalid, unexpected, or random data as inputs to a computer program. The aim is to uncover bugs and vulnerabilities that might not be detected with conventional testing strategies.
The Trident testing framework equips developers with tools to efficiently develop fuzz tests for Anchor-based programs. It streamlines the fuzz testing process through automation and comprehensive support:
Trident is built for customization, enabling developers to tailor their fuzz tests by adjusting:
This framework supports a detailed and methodical approach to fuzz testing, facilitating the identification and remediation of potential vulnerabilities in software applications.
Fuzzing is a software testing technique that involves providing invalid, unexpected, or random data as inputs to a computer program. The aim is to uncover bugs and vulnerabilities that might not be detected with conventional testing strategies.
The Trident testing framework equips developers with tools to efficiently develop fuzz tests for Anchor-based programs. It streamlines the fuzz testing process through automation and comprehensive support:
Trident is built for customization, enabling developers to tailor their fuzz tests by adjusting:
This framework supports a detailed and methodical approach to fuzz testing, facilitating the identification and remediation of potential vulnerabilities in software applications.
In the sequence diagram below you can see a simplified fuzz test lifecycle.
Some diagram states are labeled with emojis:
exit_upon_crash parameter was set.CTRL+C).pre_ixs), in the middle (ixs) and at the end (post_ixs) of each iteration. This can be useful for example if your program needs an initialization or you want to fuzz some specific program state.get_accounts() is called to collect necessary instruction accounts.get_data() is called to collect instruction data.check() is called to check accounts data and evaluate invariants.In the sequence diagram below you can see a simplified fuzz test lifecycle.
Some diagram states are labeled with emojis:
exit_upon_crash parameter was set.CTRL+C).pre_ixs), in the middle (ixs) and at the end (post_ixs) of each iteration. This can be useful for example if your program needs an initialization or you want to fuzz some specific program state.get_accounts() is called to collect necessary instruction accounts.get_data() is called to collect instruction data.check() is called to check accounts data and evaluate invariants.Once you have finished the implementation of the Fuzz Test, you can run the Test as follows:
# Replace <TARGET_NAME> with the name of particular
+ Run and Debug - Trident Run and Debug#
Run#
Once you have finished the implementation of the Fuzz Test, you can run the Test as follows:
# Replace <TARGET_NAME> with the name of particular
# fuzz test (for example: "fuzz_0")
trident fuzz run <TARGET_NAME>
Under the hood Trident uses honggfuzz-rs.
You can pass supported parameters via the Trident.toml configuration file:
\ No newline at end of file
+At the current development stage, there are some manual steps required to make your fuzz test compile:
trident-tests/fuzz_tests/Cargo.toml (such as anchor-spl etc.).use statements into trident-tests/fuzz_tests/<FUZZ_TEST_NAME>/accounts_snapshots.rs to import missing types.At the current development stage, there are some manual steps required to make your fuzz test compile:
trident-tests/fuzz_tests/Cargo.toml (such as anchor-spl etc.).use statements into trident-tests/fuzz_tests/<FUZZ_TEST_NAME>/accounts_snapshots.rs to import missing types.Trident fuzzer helps you to generate only a limited amount of pseudo-random accounts and reuse them in the instructions.
Always generating only random accounts would in most cases lead to a situation where the fuzzer would be stuck because the accounts would be almost every time rejected by your Anchor program. Therefore it is necessary to specify, what accounts should be used and also limit the number of newly created accounts to reduce the space complexity.
trident-tests/fuzz_tests/<FUZZ_TEST_NAME>/fuzz_instructions.rs file and complete the pre-generated FuzzAccounts structure. It contains all accounts used in your program. You have to determine if the account is a:Then use the corresponding AccountsStorage types such as:
pub struct FuzzAccounts {
+ Specify accounts to reuse - Trident Specify accounts to reuse#
Trident fuzzer helps you to generate only a limited amount of pseudo-random accounts and reuse them in the instructions.
Always generating only random accounts would in most cases lead to a situation where the fuzzer would be stuck because the accounts would be almost every time rejected by your Anchor program. Therefore it is necessary to specify, what accounts should be used and also limit the number of newly created accounts to reduce the space complexity.
- Go to the
trident-tests/fuzz_tests/<FUZZ_TEST_NAME>/fuzz_instructions.rs file and complete the pre-generated FuzzAccounts structure. It contains all accounts used in your program. You have to determine if the account is a: - Signer
- PDA
- Token Account
- Program account
Then use the corresponding AccountsStorage types such as:
\ No newline at end of file
+Trident fuzzer generates random instruction data for you.
Currently, it is however required, that you manually assign the random fuzzer data to the instruction data. It is done using the IxOps trait and its method get_data.
trident-tests/fuzz_tests/<FUZZ_TEST_NAME>/fuzz_instructions.rs file and complete the pre-generated get_data methods for each instruction such as:fn get_data(
+ Specify instruction data - Trident Specify instruction data#
Trident fuzzer generates random instruction data for you.
Currently, it is however required, that you manually assign the random fuzzer data to the instruction data. It is done using the IxOps trait and its method get_data.
- Go to the
trident-tests/fuzz_tests/<FUZZ_TEST_NAME>/fuzz_instructions.rs file and complete the pre-generated get_data methods for each instruction such as:
\ No newline at end of file
+Trident fuzzer generates random indexes of accounts to use in each instruction. Each created account is saved in the global FuzzAccounts structure which helps you to reuse already existing accounts across all instructions.
You are required to define, how these accounts should be created and which accounts should be passed to an instruction. It is done using the IxOps trait and its method get_accounts.
trident-tests/fuzz_tests/<FUZZ_TEST_NAME>/fuzz_instructions.rs file and complete the pre-generated get_accounts methods for each instruction such as:fn get_accounts(
+ Specify instruction accounts - Trident Specify instruction accounts#
Trident fuzzer generates random indexes of accounts to use in each instruction. Each created account is saved in the global FuzzAccounts structure which helps you to reuse already existing accounts across all instructions.
You are required to define, how these accounts should be created and which accounts should be passed to an instruction. It is done using the IxOps trait and its method get_accounts.
- Go to the
trident-tests/fuzz_tests/<FUZZ_TEST_NAME>/fuzz_instructions.rs file and complete the pre-generated get_accounts methods for each instruction such as:
\ No newline at end of file
+After each successful instruction execution, the check() method is called to check the account data invariants.
For each instruction, you can compare the account data before and after the instruction execution such as:
fn check(
+ Define invariants checks - Trident Define invariants checks#
After each successful instruction execution, the check() method is called to check the account data invariants.
For each instruction, you can compare the account data before and after the instruction execution such as:
\ No newline at end of file
+It is possible to customize how the instructions are generated and which instructions will be executed at the beginning (pre_ixs), in the middle (ixs) and at the end (post_ixs) of each fuzz iteration. This can be useful for example if your program needs an initialization or you want to fuzz some specific program state.
trident-tests/fuzz_tests/<FUZZ_TEST_NAME>/test_fuzz.rs and implement the corresponding optional method of the FuzzDataBuilder<FuzzInstruction> trait. For example, in order to always call the initialize instruction, modify the trait's implementation as follows:impl FuzzDataBuilder<FuzzInstruction> for MyFuzzData {
+ Customize instructions generation - Trident Customize instructions generation#
It is possible to customize how the instructions are generated and which instructions will be executed at the beginning (pre_ixs), in the middle (ixs) and at the end (post_ixs) of each fuzz iteration. This can be useful for example if your program needs an initialization or you want to fuzz some specific program state.
- Go to the
trident-tests/fuzz_tests/<FUZZ_TEST_NAME>/test_fuzz.rs and implement the corresponding optional method of the FuzzDataBuilder<FuzzInstruction> trait. For example, in order to always call the initialize instruction, modify the trait's implementation as follows:
\ No newline at end of file
+If you use Custom Types as Instruction data arguments, you may encounter a problem that the Custom Type does not implement
For example:
#[program]
+ How to use Custom Data Types - Trident How to use Custom Data Types#
If you use Custom Types as Instruction data arguments, you may encounter a problem that the Custom Type does not implement
For example:
#[program]
pub mod your_program {
pub fn init_vesting(
ctx: Context<InitVesting>,
@@ -101,4 +101,4 @@
}
...
}
-
Example#
For a practical example, please refer to the Examples section.
\ No newline at end of file
+For a practical example, please refer to the Examples section.
The Arbitrary crate in Rust is used for generating well-typed, structured instances of data from raw byte buffers, making it useful for fuzzing by producing random but structured data for tests.
By implementing the Arbitrary trait for Instruction Data structures, you can guide the fuzzing tool to generate meaningful instances of these structures, thus ensuring a more effective and targeted fuzzing process.
Let`s say your Solana program contains instruction, with a similar logic as the example below:
#[program]
+ How to use Arbitrary crate - Trident How to use Arbitrary crate#
The Arbitrary crate in Rust is used for generating well-typed, structured instances of data from raw byte buffers, making it useful for fuzzing by producing random but structured data for tests.
By implementing the Arbitrary trait for Instruction Data structures, you can guide the fuzzing tool to generate meaningful instances of these structures, thus ensuring a more effective and targeted fuzzing process.
Let`s say your Solana program contains instruction, with a similar logic as the example below:
#[program]
pub mod your_program {
pub fn init_vesting(
ctx: Context<InitVesting>,
@@ -127,4 +127,4 @@
}
}
...
-
Example#
For a practical example, please refer to the Examples section.
\ No newline at end of file
+For a practical example, please refer to the Examples section.
To initialize Trident and generate all-suite test templates, navigate to your project's root directory and run
trident init
+ All-Suite - Trident All-Suite#
To initialize Trident and generate all-suite test templates, navigate to your project's root directory and run
The command will generate the following folder structure:
\ No newline at end of file
+If you have already initialized Trident within your project, and you are interested in initializing a new fuzz test run.
trident fuzz add
+ Add new Fuzz Test - Trident Add new Fuzz Test#
If you have already initialized Trident within your project, and you are interested in initializing a new fuzz test run.
The command will generate a new fuzz test as follows:
\ No newline at end of file
+If you are interested only in generating templates for fuzz tests run
trident init fuzz
+ Fuzz test-only - Trident Fuzz test-only#
If you are interested only in generating templates for fuzz tests run
The command will generate the following folder structure:
\ No newline at end of file
+Check supported versions section for further details.
cargo install trident-cli
+ Installation - Trident Installation#
Dependencies#
Check supported versions section for further details.
- Install Rust
- Install Solana tool suite
- Install Anchor
- Install Honggfuzz-rs for fuzz testing
Installation#
Supported versions#
- We support
Anchor and Solana versions specified in the table below.
Trident CLI Anchor Solana Rust v0.6.0>=0.29.*1^1.17nightly v0.5.0~0.28.*=1.16.6 v0.4.0~0.27.*>=1.15 v0.3.0~0.25.*>=1.10 v0.2.0~0.24.*>=1.9
- To use Trident with Anchor 0.29.0, run the following commands from your project's root directory after Trident initialization:
\ No newline at end of file
+Trident is a Rust-based framework to fuzz and integration test Solana programs to help you ship secure code.
Automated Test Generation: Simplifies the testing process by automatically creating templates for fuzz and integration tests for programs written using the Anchor Framework.
Dynamic Data Generation: Increases test coverage with random instruction data and pseudo-random accounts for unpredictable fuzz test scenarios.
Custom Instruction Sequences: Provides the flexibility to design specific sequences of instructions to meet particular testing needs or to focus on particular aspects of program behavior during fuzz testing. Invariant Checks: Allows for custom invariants checks to spot vulnerabilities and unwanted behaviors.
Trident is a Rust-based framework to fuzz and integration test Solana programs to help you ship secure code.
Automated Test Generation: Simplifies the testing process by automatically creating templates for fuzz and integration tests for programs written using the Anchor Framework.
Dynamic Data Generation: Increases test coverage with random instruction data and pseudo-random accounts for unpredictable fuzz test scenarios.
Custom Instruction Sequences: Provides the flexibility to design specific sequences of instructions to meet particular testing needs or to focus on particular aspects of program behavior during fuzz testing. Invariant Checks: Allows for custom invariants checks to spot vulnerabilities and unwanted behaviors.
// <my_project>/trident-tests/poc_tests/tests/test.rs
+ Init Fixture - Trident Init Fixture#
// <my_project>/trident-tests/poc_tests/tests/test.rs
// TODO: do not forget to add all necessary dependencies to the generated `trident-tests/poc_tests/Cargo.toml`
use program_client::my_instruction;
use trident_client::*;
@@ -41,4 +41,4 @@
let state = fixture.get_state().await?;
assert_eq!(state.something_changed, "yes");
}
-
\ No newline at end of file
+Trident does not export anchor-spl and spl-associated-token-account, so you have to add it manually.# <my-project>/trident-tests/poc_tests/Cargo.toml
+ Testing programs with associated token accounts - Trident Testing programs with associated token accounts#
Trident does not export anchor-spl and spl-associated-token-account, so you have to add it manually.
\ No newline at end of file
+To initialize Trident and generate all-suite test templates, navigate to your project's root directory and run
trident init
+ All-Suite - Trident All-Suite#
To initialize Trident and generate all-suite test templates, navigate to your project's root directory and run
The command will generate the following folder structure:
\ No newline at end of file
+If you are interested only in generating templates for Integration Tests run
trident init poc
+ Integration test-only - Trident Integration test-only#
If you are interested only in generating templates for Integration Tests run
The command will generate the following folder structure:
\ No newline at end of file
+By default, Integration Tests initialization generates also a .program_client crate with all necessary implementation for Instructions.
If you are interested in updating the .program_client implementation due to an update inside your program, run
This command will also initialize .program_client if the crate does not exist yet.
By default, Integration Tests initialization generates also a .program_client crate with all necessary implementation for Instructions.
If you are interested in updating the .program_client implementation due to an update inside your program, run
This command will also initialize .program_client if the crate does not exist yet.
Trident supports writing Integration Tests in Rust.