@metaplex-foundation/beet-solana

What is @metaplex-foundation/beet-solana?

@metaplex-foundation/beet-solana is a library designed to facilitate serialization and deserialization of data structures in the Solana blockchain ecosystem. It provides utilities to define and work with complex data types, making it easier to interact with Solana programs.

What are @metaplex-foundation/beet-solana's main functionalities?

Serialization and Deserialization

This feature allows users to define data structures and serialize/deserialize them to/from buffers. The code sample demonstrates how to define a simple struct with two fields and serialize/deserialize it using the library.

const { u8, struct } = require('@metaplex-foundation/beet-solana');

const MyStruct = struct([
  ['field1', u8],
  ['field2', u8]
]);

const buffer = Buffer.alloc(MyStruct.byteSize);
MyStruct.write(buffer, 0, { field1: 1, field2: 2 });

const result = MyStruct.read(buffer, 0);
console.log(result); // { field1: 1, field2: 2 }

Complex Data Types

This feature supports complex data types, such as arrays within structs. The code sample shows how to define a struct with an array field and serialize/deserialize it.

const { u8, array, struct } = require('@metaplex-foundation/beet-solana');

const ComplexStruct = struct([
  ['field1', u8],
  ['field2', array(u8, 3)]
]);

const buffer = Buffer.alloc(ComplexStruct.byteSize);
ComplexStruct.write(buffer, 0, { field1: 1, field2: [2, 3, 4] });

const result = ComplexStruct.read(buffer, 0);
console.log(result); // { field1: 1, field2: [2, 3, 4] }

Other packages similar to @metaplex-foundation/beet-solana

borsh

Borsh is a binary serialization format designed for speed and efficiency, commonly used in the Solana ecosystem. It provides similar functionality to @metaplex-foundation/beet-solana in terms of serialization and deserialization of data structures, but with a focus on performance and simplicity.

buffer-layout

Buffer-layout is a library for describing and serializing binary data structures. It is used in the Solana ecosystem for defining data layouts in a flexible manner. Compared to @metaplex-foundation/beet-solana, buffer-layout offers a more low-level approach to defining data structures.

README

@metaplex-foundation/beet-solana

Solana specific extension for beet, the borsh compatible de/serializer

API

Please find the API docs here.

GPA Builders

solana-beet uses beets knowledge about account layouts to provide GpaBuilders for them which allow to filter by account data size and content.

1. Create a GPA Builder via const gpaBuilder = GpaBuilder.fromStruct(programId, accountStruct)
2. add filters via gpaBuilder.dataSize, gpaBuilder.addFilter or gpaBuilder.addInnerFilter
3. execute gpaBuilder.run(connection) which will return all accounts matching the specified filters

Examples

Simple struct with primitives

export type ResultsArgs = Pick<Results, 'win' | 'totalWin' | 'losses'>
export class Results {
  constructor(
    readonly win: number,
    readonly totalWin: number,
    readonly losses: number
  ) {}

  static readonly struct = new BeetStruct<Results, ResultsArgs>(
    [
      ['win', u8],
      ['totalWin', u16],
      ['losses', i32],
    ],
    (args: ResultsArgs) => new Results(args.win!, args.totalWin!, args.losses!),
    'Results'
  )
}

const gpaBuilder = GpaBuilder.fromStruct(PROGRAM_ID, Results.struct)
const accounts = await gpaBuilder
  .addFilter('totalWin', 8)
  .addFilter('losses', -7)
  .run()

Matching on Complete Nested Struct

Using Results struct from above

export type TraderArgs = Pick<Trader, 'name' | 'results' | 'age'>
export class Trader {
  constructor(
    readonly name: string,
    readonly results: Results,
    readonly age: number
  ) {}

  static readonly struct = new BeetStruct<Trader, TraderArgs>(
    [
      ['name', fixedSizeUtf8String(4)],
      ['results', Results.struct],
      ['age', u8],
    ],
    (args) => new Trader(args.name!, args.results!, args.age!),
    'Trader'
  )
}

const gpaBuilder = GpaBuilder.fromStruct<Trader>(
  PROGRAM_ID,
  Trader.struct
)

const results = {
  win: 3,
  totalWin: 4,
  losses: -100,
}

const accounts = await gpaBuilder.addFilter('results', results).run()

Matching on Part of Nested Struct

Using Trader struct from above

const gpaBuilder = GpaBuilder.fromStruct<Trader>(
  PROGRAM_ID,
  Trader.struct
)

const account = await gpaBuilder
  .addInnerFilter('results.totalWin', 8)
  .addInnerFilter('results.win', 2)
  .run()

PublicKey

solana-beet provides a de/serializer for solana public keys. They can either be used directly or as part of a struct.

Examples

Using PublicKey Directly

import { publicKey } from '@metaplex-foundation/beet-solana'

const generatedKey  = Keypair.generate().publicKey
const buf = Buffer.alloc(publicKey.byteSize)
beet.write(buf, 0, generatedKey)
beet.read(buf, 0) // same as generatedKey

PublicKey as part of a Struct Configuration

import * as web3 from '@solana/web3.js'
import * as beet from '@metaplex-foundation/beet'
import * as beetSolana from '@metaplex-foundation/beet-solana'

type InstructionArgs = {
  authority: web3.PublicKey
}

const createStruct = new beet.BeetArgsStruct<InstructionArgs>(
  [
    ['authority', beetSolana.publicKey]
  ],
  'InstructionArgs'
)

LICENSE

Apache-2.0