Table of Contents

• sbpf
  • Installation
  • Usage
  • Command Details
    • Initialize a Project
      • Examples
        • Create a new project with Rust tests (default)
        • Create a new project with TypeScript tests
    • Disassembler
    • Debugger
  • Advanced Usage
  • License
  • Contributing

sbpf

A simple scaffold to bootstrap sBPF Assembly programs.

Installation

cargo install --git https://github.com/blueshift-gg/sbpf.git

Usage

To view all the commands you can run, type sbpf help. Here are the available commands:

• init: Create a new project scaffold.
• build: Compile into a Solana program executable.
• deploy: Build and deploy the program.
• test: Test the deployed program.
• e2e: Build, deploy, and test a program.
• clean: Clean up build and deploy artifacts.
• disassemble: Disassemble a Solana program executable.
• debug: Debug an sBPF assembly program.
• help: Print this message or the help of the given subcommand(s).

Usage: sbpf <COMMAND>

Commands:
  init         Create a new project scaffold
  build        Compile into a Solana program executable
  deploy       Build and deploy the program
  test         Test deployed program
  e2e          Build, deploy and test a program
  clean        Clean up build and deploy artifacts
  disassemble  Disassemble a Solana program executable
  debug        Debug an sBPF assembly program
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Command Details

Initialize a Project

To create a new project, use the sbpf init command. By default, it initializes a project with Rust tests using Mollusk. You can also initialize a project with TypeScript tests using the --ts-tests option.

sbpf init --help
Create a new project scaffold

Usage: sbpf init [OPTIONS] [NAME]

Arguments:
  [NAME]  The name of the project to create

Options:
  -t, --ts-tests  Initialize with TypeScript tests instead of Mollusk Rust tests
  -h, --help      Print help information
  -V, --version   Print version information

Examples

Create a new project with Rust tests (default)

sbpf init my-project

Create a new project with TypeScript tests

sbpf init my-project --ts-tests

After initializing the project, you can navigate into the project directory and use other commands to build, deploy, and test your program.

Disassembler

The disassembler converts a Solana program executable (ELF) into human-readable sBPF assembly.

sbpf disassemble <FILENAME>

Debugger

The debugger provides an interactive REPL for stepping through sBPF assembly programs.

Debug an assembly file:

sbpf debug --asm <FILENAME>

Debug an ELF file:

sbpf debug --elf <FILENAME>

Input:

To debug programs that require input, the debugger accepts a JSON file (or JSON string) containing the instruction being executed and the accounts involved. Pass it using the --input flag:

sbpf debug --asm src/my-program/my-program.s --input input.json

The JSON should contain the following information:

• instruction: The instruction to execute, including the program ID, account metas, and instruction data.
• accounts: The account states. The data field in each account and instruction should be base58 encoded.

Example:

{
  "instruction": {
    "program_id": "78ycAjmvvq2Xjz6mBgGTsuHHNVADZ75NWgXKPY8wvF2s",
    "accounts": [
      {
        "pubkey": "3JF3sEqM796hk5WFqA6EtmEwJQ9quALszsfJyvXNQKy3",
        "is_signer": true,
        "is_writable": false
      },
      {
        "pubkey": "11157t3sqMV725NVRLrVQbAu98Jjfk1uCKehJnXXQs",
        "is_signer": false,
        "is_writable": true
      }
    ],
    "data": "8AQGAut7N95oMfV99bhRZ"
  },
  "accounts": [
    {
      "pubkey": "3JF3sEqM796hk5WFqA6EtmEwJQ9quALszsfJyvXNQKy3",
      "owner": "11111111111111111111111111111111",
      "lamports": 1000000000,
      "data": "",
      "executable": false
    },
    {
      "pubkey": "11157t3sqMV725NVRLrVQbAu98Jjfk1uCKehJnXXQs",
      "owner": "11111111111111111111111111111111",
      "lamports": 1000000000,
      "data": "",
      "executable": false
    }
  ]
}

Advanced Usage

You can override the default linker with a custom linker file by including it in the src directory with the same name as your program. For example:

src/example/example.s
src/example/example.ld

WebAssembly

The assembler is also available as a WebAssembly package for Node.js, browsers, and bundlers. See npm/README.md.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

PRs welcome!