phink 0.1.4

Phink is a blazing-fast⚡, property-based, coverage-guided fuzzer for ink! smart contracts. It enables developers to embed inviolable properties into their smart contract testing workflows, equipping them with automatic tools to detect vulnerabilities and ensure contract reliability before deployment. Please, read the documentation in order to properly use Phink.

⚠️ This project is actively under development with new features and improvements being made regularly. Contributions and feedback are welcome!

For documentation, visit our documentation site here. If you have any question, feedback, features suggestion, join our Discord.

Install

Building from source

Requirements

Install the requirements, configure AFL++ plugins and adapt the system configs

cargo install --force ziggy cargo-afl honggfuzz grcov cargo-contract --locked 
cargo afl config --build --plugins --verbose --force # don't use `--plugins` if you're on macOS
sudo cargo-afl afl system-config

Install Phink

cargo install --git https://github.com/srlabs/phink
phink --help

If you prefer to install Phink manually, follow these steps:

git clone https://github.com/kevin-valerio/phink
cd phink/ && cargo build --release
./target/release/phink --help

Install Phink via Docker

Alternatively, you can use Docker to set up and run Phink without needing to manually install dependencies. Detailed instructions are available in README.Docker.md. To build the Docker image:

docker build -t phink .

Usage

Via normal installation

phink instrument path/to/ink_contract
phink generate-seed path/to/ink_contract #optional 
phink fuzz  

If installed via Docker

To use Phink via Docker, you can run:

docker run --rm phink

For instrumenting a contract:

docker run --rm phink instrument path/to/ink_contract

Refer to README.Docker.md for more detailed instructions on using Phink with Docker.

Example

Adding some invariants

Below are some invariants created for the dns contract.

1. Add the phink feature to your Cargo.toml

[features]
phink = []

2. Create your invariants as below:

#[cfg(feature = "phink")]
#[ink(impl)]
impl DomainNameService {
    // This invariant ensures that `domains` doesn't contain the forbidden domain that nobody should regsiter 
    #[ink(message)]
    #[cfg(feature = "phink")]
    pub fn phink_assert_hash42_cant_be_registered(&self) {
        for i in 0..self.domains.len() {
            if let Some(domain) = self.domains.get(i) {
                // Invariant triggered! We caught an invalid domain in the storage...
                assert_ne!(domain.clone().as_mut(), FORBIDDEN_DOMAIN);
            }
        }
    }

    // This invariant ensures that nobody registed the forbidden number
    #[ink(message)]
    #[cfg(feature = "phink")]
    pub fn phink_assert_dangerous_number(&self) {
        let forbidden_number = 42;
        assert_ne!(self.dangerous_number, forbidden_number);
    }
}

Catching an invariant

phink execute output/phink/crashes/<timestamp>/<id:000x:seed>  

Below, the trace after executing the crash:

🚀 Now fuzzing `/tmp/ink_fuzzed_XqUCn/target/ink/transfer.json` (5H31F11yQUkqugbgC7ur4rT2WLKSkZKAZUfcmHkKoLkaRaZ4)!
🤯 An invariant got caught! Let's dive into it
🫵  This was caused by `phink_assert_cannot_transfer_1337`
🎉 Find below the trace that caused that invariant
🌱 Executing new seed

+---------+-------------------------------------------------------------------+
| Message | Details                                                           |
+---------+-------------------------------------------------------------------+
| pay_me  |  ⛽️ Gas required : Weight(ref_time: 591391866, proof_size: 28781) |
|         | 🔥 Gas consumed : Weight(ref_time: 582570121, proof_size: 12443)  |
|         | 💾 Storage deposit : StorageDeposit::Charge(0)                    |
|         | 💸 Message was payable, and 1809739 units were transferred        |
+---------+-------------------------------------------------------------------+

List of samples

You can find various sample ink! smart-contracts in the sample/ directory. For detailed descriptions of these samples and instructions on how to instrument them for testing with Phink, please refer to the sample's README file.

Features and upcoming ideas

• Integration of a custom runtime, using a generic one by default
• Invariants-based fuzzing
• Detection of incorrect arithmetic, reentrancy, and panic handlers
• Handling of ink! specific encoding and constructors
• Automatic contract instantiation
• Crafting multiple messages in a single transaction
• Visualization of ink! contract coverage
• Proper binary usage
• Enabling multi-contract fuzzing and cross-contract interactions
• Seed extraction out of unit and end-to-end tests
• Development of a custom fuzzing dashboard (default options: Ziggy/AFL++/Honggfuzz dashboard)
• Creation of default invariants common to every contract (research needed)
• Implementation of a snapshot-based fuzzing approach (research needed)