branchia 0.0.1

A Rust implementation of the solana gill library
Documentation

Implementation of the gill library in Rust

Installation

cargo add branchia

Quick start

You can find some system specific helpers here

You can find transaction builders for common tasks, including:

For troubleshooting and debugging your Solana transactions, see Debug mode below.

You can also consult the documentation for Anza's JavaScript client library for more information and helpful resources.

Using the modular crates from Anza

Generating Keypairs and Signers

For most "signing" transactions, you'll need a Keypair instance, which can be used to sign transactions and messages.

use branchia::{Keypair, Signer};

let signer = Keypair::new();

Ensure you import the Signer trait as it contains necessary methods to facilitate signing

Create a Solana RPC connection

Create a Solana rpc client for any RPC URL or standard Solana network moniker (i.e. devnet, localnet, mainnet etc) with a default commitment level of confirmed

use branchia::SolanaClient;

let client = SolanaClient::new("devnet");

Using the Solana moniker will connect to the public RPC endpoints. These are subject to rate limits and should not be used in production applications. Applications should find their own RPC provider and the URL provided from them.

To create an RPC client with another commitment level:

use branchia::{SolanaClient, CommitmentConfig};

let client = SolanaClient::new_with_commitment("localnet", CommitmentConfig::processed);

To create an RPC client for an custom RPC provider or service:

use branchia::SolanaClient;

let client = SolanaClient::new("https://private-solana-rpc-provider.com");

Making Solana RPC calls

After you have a Solana rpc connection, you can make all the JSON RPC method calls directly off of it.

use branchia::SolanaClient;

let client = SolanaClient::new("devnet");

//get slot
let slot = client.rpc.getSlot();

//get the latest blockhash
let latest_blockhash = client.rpc.get_latest_blockhash();

Create a transaction

Legacy

Quickly create a Solana transaction:

use branchia::TxBuilder;

let tx = TxBuilder::new(
  fee_payer,
  instructions,
  // the compute budget values are HIGHLY recommend to be set in order to maximize your transaction landing rate
  compute_unit_limit, //optional
  compute_unit_price //optional
  );

Versioned Transaction

COMING SOON!

Signing Transactions


use branchia::TxBuilder;

let tx = TxBuilder::new(...);
let signed_tx = tx.sign(signers, latest_blockhash);

Simulating transactions

To simulate a transaction on the blockchain, you can use the simulate_transaction method on the initialized SolanaClient

use branchia::{...};

let client = SolanaClient::new("devnet");
let tx = TxBuilder::new(...);
let signed_tx = tx.sign(...);

let simulation = client.rpc.simulate_transaction(signed_tx);

Simulation with Custom Config: COMING SOON!

Sending and confirming transactions

To send and confirm a transaction to the blockchain, you can use the sendAndConfirmTransaction method from the initialized SolanaClient. The default commitment level is processed, to set another level check out - COMING SOON!

use branchia::{...};

let client = SolanaClient::new("devnet");
let tx = TxBuilder::new(...);
let signed_tx = tx.sign(...);

let signature = client.rpc.send_and_confirmed_transaction(signed_tx);

Set custom config

COMING SOON!

Get the signature from a signed transaction

After you have a transaction signed by the feePayer (either a partially or fully signed transaction), you can get the transaction signature as follows:

use branchia::TxBuilder;

let tx = TxBuilder::new(...);
let signed_tx = tx.sign(...);

let signature = signed_tx.signatures[0];

Note: After a transaction has been signed by the fee payer, it will have a transaction signature (aka transaction id). This is due to Solana transaction ids are the first item in the transaction's signatures array. Therefore, client applications can potentially know the signature before it is even sent to the network for confirmation.

Get a Solana Explorer link for transactions, accounts, or blocks

Craft a Solana Explorer link for transactions, accounts, or blocks on any cluster.

Get a Solana Explorer link for a transaction

To get an explorer link for a transaction's signature (aka transaction id):

use branchia::TxBuilder;

let url = TxBuilder::get_explorer_link_transaction(cluster, signature);

The cluster parameter accepts custom urls and the known monikers(i.e devnet, mainnet, localnet)

If you have a partially or fully signed transaction, you can get the Explorer link before even sending the transaction to the network:

See Get Signature from a Signed Transaction for better understanding.

use branchia::TxBuilder;

let tx = TxBuilder::new(...);
let signed_tx = tx.sign(...);
let url = TxBuilder::get_explorer_link_transaction("localnet", &signed_tx.signatures[0].to_string())

COMING SOON!

Get a Solana Explorer link for an account

To get an explorer link for an account on Solana's devnet:

use branchia::TxBuilder;

let url = TxBuilder::get_explorer_link_account("devnet", "Bf8PxxWt7UTvNGcrDyNwQiERSwNroa4pEo1pxwKo17Uh");

Get a Solana Explorer link for a block

To get an explorer link for a block:

use branchia::TxBuilder;

let url = TxBuilder::get_explorer_link_block("localnet", 2345);

Calculate minimum rent for an account

To calculate the minimum rent balance for an account (aka data storage deposit fee):

For default rent

use branchia::Rent;

let rent = Rent::default().minimum_balance(0);
// Expected value: 890880

Rent for specified number of bytes

use branchia::Rent;

let rent = Rent::default().minimum_balance(50);
// Expected value: 1238880

Loading a keypair from a file

use branchia::{Keypair, KeypairExt};

let signer = Keypair::from_default_file();

Ensure you import the KeypairExt trait as it contains extended functionality on the Keypair component

Load a Keypair from a filesystem wallet json file, like those output from the Solana CLI (i.e. a JSON array of numbers).

By default, the keypair file loaded is the Solana CLI's default keypair: ~/.config/solana/id.json

To load a Signer from a specific filepath:

use branchia::Keypair;

let signer = Keypair::from_default_file(path);

Saving a keypair to a file

Save a Keypair to a local json file(e.g keypair.json)

use branchia::Keypair;

let signer = Keypair::new();
signer.write_to_file(path);

Transaction Builders

Create a token with metadata

Build a transaction that can create a token with metadata, either using the original token or token extensions (token22) program. - COMING SOON!

  • Tokens created with the original token program (TOKEN_PROGRAM_ADDRESS, default) will use Metaplex's Token Metadata program for onchain metadata
  • Tokens created with the token extensions program (TOKEN_2022_PROGRAM_ADDRESS) will use the metadata pointer extensions - COMING SOON! INSTRUCTION BUILDERS - COMING SOON!
use branchia:{TxBuilder, MetadataArgs};

let create_token_tx = TxBuilder::create_token_transaction(
  fee_payer,
  latest_blockhash,
  mint,
  MetadataArgs{
    name
    symbol
    uri
    is_mutable // if the `updateAuthority` can change this metadata in the future
  },
  decimals,
  tokenProgram //just the regular token program, no token 2022 support yet
)

// ADD DEFAULT VALUES FOR CERTAIN FIELDS HERE? - TBD!

Mint tokens to destination wallet

Build a transaction that mints new tokens to the destination wallet address (raising the token's overall supply).

  • ensure you set the correct tokenProgram used by the mint itself
  • if the destination owner does not have an associated token account (ata) created for the mint, one will be auto-created for them
  • ensure you take into account the decimals for the mint when setting the amount in this transaction
use branchia::TxBuilder;

let mint_tokens_tx = TxBuilder::mint_token_transaction(
  fee_payer,
  latest_blockhash,
  mint,
  mint_authority,
  amount,// note: be sure to consider the mint's `decimals` value
  // if decimals=2 => this will mint 10.00 tokens
  // if decimals=4 => this will mint 0.100 tokens
  destination, // use the correct token program for the `mint`
  token_program //just the regular token program, no token 2022 support yet
)

Transfer tokens to a destination wallet

Build a transaction that transfers tokens to the destination wallet address from the source (aka from sourceAta to destinationAta).

  • ensure you set the correct tokenProgram used by the mint itself
  • if the destination owner does not have an associated token account (ata) created for the mint, one will be auto-created for them
  • ensure you take into account the decimals for the mint when setting the amount in this transaction
use branchia::{TxBuilder}

let transfer_tokens_tx = TxBuilder::transfer_token_transaction(
  fee_payer,
  latest_blockhash,
  mint,
  authority,
  amount: 900, // note: be sure to consider the mint's `decimals` value
  // if decimals=2 => this will transfer 9.00 tokens
  // if decimals=4 => this will transfer 0.090 tokens
  destination,   // use the correct token program for the `mint`
  token_program
)