solana_kit_addresses 0.2.0

Base58 address utilities for the Solana Kit Dart SDK.

solana_kit_addresses

Base58-encoded Solana address utilities for the Solana Kit Dart SDK -- a Dart port of @solana/addresses.

Installation

Add solana_kit_addresses to your pubspec.yaml:

dependencies:
  solana_kit_addresses:

Or, if you are using the umbrella package:

dependencies:
  solana_kit:

Documentation

• Package page: https://pub.dev/packages/solana_kit_addresses
• API reference: https://pub.dev/documentation/solana_kit_addresses/latest/

Usage

Creating and validating addresses

The Address type is a zero-overhead extension type wrapping a String. Use the address() factory function to create a validated address from an untrusted string, or the Address() constructor directly when you know the string is valid.

import 'package:solana_kit_addresses/solana_kit_addresses.dart';

void main() {
  // Create a validated address from an untrusted string.
  // Throws SolanaError if the string is not a valid base58-encoded 32-byte address.
  final myAddress = address('11111111111111111111111111111112');

  // For known-good strings you can use the constructor directly (no validation).
  const systemProgram = Address('11111111111111111111111111111111');

  // Check whether a string is a valid Solana address without throwing.
  final valid = isAddress('11111111111111111111111111111112'); // true
  final invalid = isAddress('not-a-valid-address'); // false

  // Assert validity -- throws SolanaError on failure.
  assertIsAddress('11111111111111111111111111111112');
}

Converting between addresses and public keys

Convert between a raw 32-byte Ed25519 public key (Uint8List) and a base58-encoded Address.

import 'dart:typed_data';

import 'package:solana_kit_addresses/solana_kit_addresses.dart';

void main() {
  // Suppose you have a 32-byte public key from an Ed25519 key pair.
  final publicKeyBytes = Uint8List(32); // replace with real bytes

  // Convert raw public key bytes to an Address.
  final addr = getAddressFromPublicKey(publicKeyBytes);
  print(addr.value); // base58-encoded string

  // Convert an Address back to raw 32-byte public key bytes.
  final bytesAgain = getPublicKeyFromAddress(addr);
  print(bytesAgain.length); // 32
}

Encoding and decoding addresses

The address codec encodes and decodes Address values as fixed-size 32-byte binary representations. This is useful for serializing addresses in on-chain data structures.

import 'dart:typed_data';

import 'package:solana_kit_addresses/solana_kit_addresses.dart';

void main() {
  final addr = address('11111111111111111111111111111112');

  // Get a fixed-size encoder (Address -> 32 bytes).
  final encoder = getAddressEncoder();
  final bytes = encoder.encode(addr);
  print(bytes.length); // 32

  // Get a fixed-size decoder (32 bytes -> Address).
  final decoder = getAddressDecoder();
  final decoded = decoder.decode(bytes);
  print(decoded.value); // '11111111111111111111111111111112'

  // Or use the combined codec.
  final codec = getAddressCodec();
  final roundTripped = codec.decode(codec.encode(addr));
  print(roundTripped.value == addr.value); // true
}

Comparing addresses

The getAddressComparator() function returns a comparator that sorts addresses using base58 collation rules, matching the ordering used by the Solana runtime.

import 'package:solana_kit_addresses/solana_kit_addresses.dart';

void main() {
  final addresses = [
    address('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'),
    address('11111111111111111111111111111111'),
    address('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL'),
  ];

  final comparator = getAddressComparator();
  addresses.sort(comparator);

  // Addresses are now in base58 collation order.
  for (final addr in addresses) {
    print(addr.value);
  }
}

Checking if an address is on/off the Ed25519 curve

Solana program-derived addresses (PDAs) must NOT fall on the Ed25519 curve. Use these utilities to verify curve membership.

import 'dart:typed_data';

import 'package:solana_kit_addresses/solana_kit_addresses.dart';

void main() {
  // Check raw compressed point bytes (32 bytes).
  final pointBytes = Uint8List(32); // replace with real bytes
  final onCurve = compressedPointBytesAreOnCurve(pointBytes);
  print('On curve: $onCurve');

  // Check an address directly.
  final addr = address('11111111111111111111111111111112');
  print('Is on curve: ${isOnCurveAddress(addr)}');
  print('Is off curve: ${isOffCurveAddress(addr)}');

  // Assert curve membership -- throws SolanaError on failure.
  assertIsOnCurveAddress(addr);

  // Assert off-curve (useful for validating PDAs).
  // assertIsOffCurveAddress(somePda);
}

Deriving program-derived addresses (PDAs)

Program-derived addresses are deterministic addresses derived from a program address and a set of seeds. The runtime guarantees that no private key exists for a PDA.

import 'dart:typed_data';

import 'package:solana_kit_addresses/solana_kit_addresses.dart';

Future<void> main() async {
  const programAddress = Address('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');

  // Derive a PDA with string and byte seeds.
  // Seeds can be String values (UTF-8 encoded) or Uint8List byte arrays.
  // Maximum 16 seeds, each at most 32 bytes.
  final (pda, bump) = await getProgramDerivedAddress(
    programAddress: programAddress,
    seeds: ['metadata', Uint8List.fromList([1, 2, 3])],
  );

  print('PDA: ${pda.value}');
  print('Bump seed: $bump'); // 0-255

  // The PDA is guaranteed to be off the Ed25519 curve.
  print('Off curve: ${isOffCurveAddress(pda)}'); // true
}

Creating addresses with a seed (SHA-256 based)

This is the older createAccountWithSeed style derivation, which differs from PDA derivation. It concatenates the base address, seed, and program address and takes their SHA-256 hash.

import 'package:solana_kit_addresses/solana_kit_addresses.dart';

Future<void> main() async {
  const baseAddress = Address('11111111111111111111111111111111');
  const programAddress = Address('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA');

  // Create an address derived from a base address, seed, and program address.
  // The seed can be a String (UTF-8 encoded) or Uint8List, at most 32 bytes.
  final derived = await createAddressWithSeed(
    baseAddress: baseAddress,
    programAddress: programAddress,
    seed: 'my-seed',
  );

  print('Derived address: ${derived.value}');
}

API Reference

Types

Export	Description
Address	Extension type wrapping String -- a validated base58-encoded 32-byte Solana address. Zero runtime overhead.
ProgramDerivedAddress	Type alias for (Address pda, int bump) -- a derived address paired with its bump seed.

Address creation and validation

Function	Description
address(String)	Creates a validated Address from an untrusted string. Throws on invalid input.
assertIsAddress(String)	Asserts that a string is a valid base58 Solana address. Throws SolanaError on failure.
isAddress(String)	Returns true if the string is a valid base58 Solana address.

Public key conversion

Function	Description
getAddressFromPublicKey(Uint8List)	Converts a 32-byte Ed25519 public key to an Address.
getPublicKeyFromAddress(Address)	Converts an Address to its 32-byte Ed25519 public key.

Codecs

Function	Description
getAddressEncoder()	Returns a FixedSizeEncoder<Address> that encodes an address into exactly 32 bytes.
getAddressDecoder()	Returns a FixedSizeDecoder<Address> that decodes exactly 32 bytes into an address.
getAddressCodec()	Returns a FixedSizeCodec<Address, Address> combining encoder and decoder.

Comparator

Function	Description
getAddressComparator()	Returns a Comparator<Address> using base58 collation rules.

Curve checks

Function	Description
compressedPointBytesAreOnCurve(Uint8List)	Returns true if the 32-byte compressed point is on the Ed25519 curve.
isOnCurveAddress(Address)	Returns true if the address decodes to a point on the Ed25519 curve.
isOffCurveAddress(Address)	Returns true if the address is NOT on the Ed25519 curve.
assertIsOnCurveAddress(Address)	Asserts the address is on curve. Throws SolanaError on failure.
assertIsOffCurveAddress(Address)	Asserts the address is off curve. Throws SolanaError on failure.

Program-derived addresses

Function	Description
getProgramDerivedAddress({required Address programAddress, required List<Object> seeds})	Derives a PDA by searching for a valid bump seed (255 down to 0). Returns Future<ProgramDerivedAddress>.
createAddressWithSeed({required Address baseAddress, required Address programAddress, required Object seed})	Creates a SHA-256-based derived address. Returns Future<Address>.

Example

Use example/main.dart as a runnable starting point for solana_kit_addresses.

• Import path: package:solana_kit_addresses/solana_kit_addresses.dart
• This section is centrally maintained with mdt to keep package guidance aligned.
• After updating shared docs templates, run docs:update from the repo root.

Maintenance

• Validate docs in CI and locally with docs:check.
• Keep examples focused on one workflow and reference package README sections for deeper API details.