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.10.0

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.