solana_kit_codecs_core #

The Encoder, Decoder, and Codec interfaces at the base of every Solana Kit codec, plus the helpers that adapt, wrap, and combine them.

Use this package when you are building a custom codec or need to transform an existing one. Most applications reach codecs through solana_kit_codecs or the solana_kit umbrella.

Installation #

Install the package directly:

dependencies:
  "solana_kit_codecs_core": ^0.9.3

If your app uses several Solana Kit packages together, you can also depend on the umbrella package instead:

dart pub add solana_kit

Inside this monorepo, Dart workspace resolution uses the local package automatically.

Documentation #

• Package page: https://pub.flutter-io.cn/packages/solana_kit_codecs_core
• API reference: https://pub.flutter-io.cn/documentation/solana_kit_codecs_core/latest/
• Workspace docs: https://openbudgetfun.github.io/solana_kit/
• Package catalog entry: https://openbudgetfun.github.io/solana_kit/reference/package-catalog#solana_kit_codecs_core
• Source code: https://github.com/openbudgetfun/solana_kit/tree/main/packages/solana_kit_codecs_core

For architecture notes, getting-started guides, and cross-package examples, start with the workspace docs site and then drill down into the package README and API reference.

Compose core codecs #

Use solana_kit_codecs_core when you need to adapt, wrap, or combine lower- level encoders and decoders.

import 'dart:typed_data';

import 'package:solana_kit_codecs_core/solana_kit_codecs_core.dart';
import 'package:solana_kit_codecs_numbers/solana_kit_codecs_numbers.dart';

void main() {
  final codec = addCodecSentinel(getU8Codec(), Uint8List.fromList([255]));

  final encoded = codec.encode(42);
  final decoded = codec.decode(encoded);

  print(encoded);
  print(decoded);
}

These helpers are the glue layer between simple primitive codecs and the more specialized Solana-facing structures built on top of them.

Usage #

Fixed-size and variable-size codecs #

A codec is either fixed-size (always consumes the same number of bytes) or variable-size. The concrete classes FixedSizeCodec, VariableSizeCodec, and their encoder/decoder counterparts expose fixedSize and maxSize so callers can plan buffer layouts.

import 'package:solana_kit_codecs_numbers/solana_kit_codecs_numbers.dart';
import 'package:solana_kit_codecs_strings/solana_kit_codecs_strings.dart';

void main() {
  final u32Codec = getU32Codec();
  print(u32Codec.fixedSize); // 4

  final utf8Codec = getUtf8Codec();
  print(utf8Codec.maxSize); // null (unbounded)
}

Combining encoders and decoders #

combineCodec pairs an encoder and a decoder into a single Codec. fixCodecSize and addCodecSizePrefix adjust how a codec's length is represented on the wire.

Size-prefixed decoders require a finite, nonnegative integer byte count that fits within the remaining input. Negative, fractional, non-finite, and oversized prefixes throw a SolanaError before the content decoder runs.

import 'package:solana_kit_codecs_core/solana_kit_codecs_core.dart';
import 'package:solana_kit_codecs_numbers/solana_kit_codecs_numbers.dart';

void main() {
  final codec = combineCodec(getU16Encoder(), getU16Decoder());
  final bytes = codec.encode(258);
  print(bytes); // [2, 1] little-endian
  print(codec.decode(bytes)); // 258
}

Transforming values #

transformEncoder, transformDecoder, and transformCodec map between a codec's wire type and a domain type.

import 'package:solana_kit_codecs_core/solana_kit_codecs_core.dart';
import 'package:solana_kit_codecs_numbers/solana_kit_codecs_numbers.dart';

void main() {
  final codec = transformCodec(
    getU8Codec(),
    (int value) => value + 1,
    (int value, bytes, offset) => value - 1,
  );

  final bytes = codec.encode(41);
  print(codec.decode(bytes)); // 41
}

Key APIs #

• Encoder<T>, Decoder<T>, Codec<T, TFrom>: the three core interfaces.
• FixedSizeEncoder/Decoder/Codec and VariableSizeEncoder/Decoder/Codec: concrete implementations with size metadata.
• combineCodec, fixCodecSize, addCodecSizePrefix, addCodecSentinel, transformEncoder/Decoder/Codec, getEncodedSize, assertIsFixedSize, assertIsVariableSize.

Example #

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

• Import path: package:solana_kit_codecs_core/solana_kit_codecs_core.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.