solana_kit_rpc_transformers 0.2.0

Request and response transformers for the Solana Kit Dart SDK.

solana_kit_rpc_transformers

Request and response transformers for the Solana Kit Dart SDK.

This is the Dart port of @solana/rpc-transformers from the Solana TypeScript SDK.

Installation

Install with:

dart pub add solana_kit_rpc_transformers

If you are working within the solana_kit monorepo, the package resolves through the Dart workspace. Otherwise, specify a version or path as needed.

Documentation

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

Usage

This package provides helpers for transforming Solana JSON-RPC requests and responses in various ways. The default transformers handle BigInt conversion, integer overflow detection, default commitment injection, error throwing, and result extraction.

Default request transformer

The getDefaultRequestTransformerForSolanaRpc function composes three request transformers into one:

1. Integer overflow check -- Detects BigInt values that exceed the safe JavaScript integer range.
2. BigInt downcast -- Converts all BigInt values to int for JSON encoding compatibility.
3. Default commitment -- Injects a default commitment level when none is provided.

import 'package:solana_kit_rpc_spec_types/solana_kit_rpc_spec_types.dart';
import 'package:solana_kit_rpc_transformers/solana_kit_rpc_transformers.dart';
import 'package:solana_kit_rpc_types/solana_kit_rpc_types.dart';

final transformer = getDefaultRequestTransformerForSolanaRpc(
  RequestTransformerConfig(
    defaultCommitment: Commitment.confirmed,
    onIntegerOverflow: (request, keyPath, value) {
      print('Overflow in ${request.methodName} at $keyPath: $value');
    },
  ),
);

final request = RpcRequest<Object?>(
  methodName: 'getBalance',
  params: ['address123', {'commitment': null}],
);

final transformed = transformer(request);
// The commitment will be set to 'confirmed' and BigInt values downcast.

Default response transformer

The getDefaultResponseTransformerForSolanaRpc function composes three response transformers:

1. Throw on error -- Throws a SolanaError if the response body contains an error.
2. Result extraction -- Extracts the result field from the JSON-RPC response.
3. BigInt upcast -- Converts integer values to BigInt (except those in allowed numeric key paths).

import 'package:solana_kit_rpc_spec_types/solana_kit_rpc_spec_types.dart';
import 'package:solana_kit_rpc_transformers/solana_kit_rpc_transformers.dart';

final transformer = getDefaultResponseTransformerForSolanaRpc(
  ResponseTransformerConfig(
    allowedNumericKeyPaths: {
      'getAccountInfo': [
        ['value', 'data', 'parsed', 'info', 'tokenAmount', 'decimals'],
      ],
    },
  ),
);

// Successful response.
final response = {
  'jsonrpc': '2.0',
  'result': {
    'context': {'slot': BigInt.from(12345)},
    'value': BigInt.from(1000000),
  },
  'id': '1',
};

final request = RpcRequest<Object?>(
  methodName: 'getBalance',
  params: ['address123'],
);

final result = transformer(response, request);
// Returns {'context': {'slot': BigInt(12345)}, 'value': BigInt(1000000)}

BigInt downcast request transformer

Converts all BigInt values in request parameters to int, since JSON encoding does not support BigInt directly.

import 'package:solana_kit_rpc_spec_types/solana_kit_rpc_spec_types.dart';
import 'package:solana_kit_rpc_transformers/solana_kit_rpc_transformers.dart';

final transformer = getBigIntDowncastRequestTransformer();

final request = RpcRequest<Object?>(
  methodName: 'getBalance',
  params: ['address', {'minContextSlot': BigInt.from(100)}],
);

final result = transformer(request);
// params now contain int(100) instead of BigInt(100)

Integer overflow request transformer

Walks the request parameter tree and invokes the provided handler whenever a BigInt value exceeds the safe JavaScript integer range (2^53 - 1).

import 'package:solana_kit_rpc_spec_types/solana_kit_rpc_spec_types.dart';
import 'package:solana_kit_rpc_transformers/solana_kit_rpc_transformers.dart';

final transformer = getIntegerOverflowRequestTransformer(
  (request, keyPath, value) {
    throw Exception(
      'Value $value at path $keyPath in ${request.methodName} exceeds safe range',
    );
  },
);

final request = RpcRequest<Object?>(
  methodName: 'sendTransaction',
  params: [BigInt.parse('9007199254740993')], // MAX_SAFE_INTEGER + 1
);

// This will invoke the handler and throw.
// transformer(request);

Default commitment request transformer

Injects a default commitment level into the options object of RPC methods that accept one, but only when the caller has not already specified a commitment.

import 'package:solana_kit_rpc_spec_types/solana_kit_rpc_spec_types.dart';
import 'package:solana_kit_rpc_transformers/solana_kit_rpc_transformers.dart';
import 'package:solana_kit_rpc_types/solana_kit_rpc_types.dart';

final transformer = getDefaultCommitmentRequestTransformer(
  optionsObjectPositionByMethod: OPTIONS_OBJECT_POSITION_BY_METHOD,
  defaultCommitment: Commitment.confirmed,
);

// Request without commitment -> gets 'confirmed' injected.
final request = RpcRequest<Object?>(
  methodName: 'getBalance',
  params: ['address123'],
);
final result = transformer(request);
// params: ['address123', {'commitment': 'confirmed'}]

BigInt upcast response transformer

Converts all integer values in a response to BigInt, except for values at specified key paths which remain as int.

import 'package:solana_kit_rpc_spec_types/solana_kit_rpc_spec_types.dart';
import 'package:solana_kit_rpc_transformers/solana_kit_rpc_transformers.dart';

// Keep 'decimals' as int, upcast everything else to BigInt.
final transformer = getBigIntUpcastResponseTransformer([
  ['value', 'data', 'parsed', 'info', 'tokenAmount', 'decimals'],
]);

final request = RpcRequest<Object?>(
  methodName: 'getAccountInfo',
  params: ['address123'],
);

final response = {
  'value': {
    'lamports': 1000000,
    'data': {
      'parsed': {
        'info': {
          'tokenAmount': {'amount': '1000000', 'decimals': 6},
        },
      },
    },
  },
};

final result = transformer(response, request);
// 'lamports' -> BigInt(1000000), 'decimals' -> int(6)

Result response transformer

Extracts the result field from a JSON-RPC 2.0 response envelope.

import 'package:solana_kit_rpc_spec_types/solana_kit_rpc_spec_types.dart';
import 'package:solana_kit_rpc_transformers/solana_kit_rpc_transformers.dart';

final transformer = getResultResponseTransformer();
final request = RpcRequest<Object?>(methodName: 'getSlot', params: []);

final result = transformer(
  {'jsonrpc': '2.0', 'result': BigInt.from(12345), 'id': '1'},
  request,
);
print(result); // BigInt(12345)

Throw Solana error response transformer

Inspects the response for a JSON-RPC error field and throws a SolanaError if one is found.

import 'package:solana_kit_errors/solana_kit_errors.dart';
import 'package:solana_kit_rpc_spec_types/solana_kit_rpc_spec_types.dart';
import 'package:solana_kit_rpc_transformers/solana_kit_rpc_transformers.dart';

final transformer = getThrowSolanaErrorResponseTransformer();
final request = RpcRequest<Object?>(methodName: 'getSlot', params: []);

try {
  transformer(
    {
      'jsonrpc': '2.0',
      'error': {'code': -32005, 'message': 'Node is unhealthy'},
      'id': '1',
    },
    request,
  );
} on SolanaError catch (e) {
  print(e.code); // SolanaErrorCode.jsonRpcServerErrorNodeUnhealthy
}

Tree traversal

The getTreeWalkerRequestTransformer and getTreeWalkerResponseTransformer functions create transformers that recursively traverse data structures and apply visitor functions at each leaf node.

import 'package:solana_kit_rpc_spec_types/solana_kit_rpc_spec_types.dart';
import 'package:solana_kit_rpc_transformers/solana_kit_rpc_transformers.dart';

// A visitor that converts all strings to uppercase.
NodeVisitor uppercaseVisitor = (value, state) {
  if (value is String) return value.toUpperCase();
  return value;
};

final transformer = getTreeWalkerRequestTransformer(
  [uppercaseVisitor],
  const TraversalState(keyPath: []),
);

final request = RpcRequest<Object?>(
  methodName: 'test',
  params: ['hello', {'name': 'world'}],
);

final result = transformer(request);
// params: ['HELLO', {'name': 'WORLD'}]

You can use KEYPATH_WILDCARD to match any key at a given position in a key path:

import 'package:solana_kit_rpc_transformers/solana_kit_rpc_transformers.dart';

// Match any element in an array.
final keyPath = ['accounts', KEYPATH_WILDCARD, 'balance'];
// Matches: accounts[0].balance, accounts[1].balance, etc.

API Reference

Request Transformers

• getDefaultRequestTransformerForSolanaRpc([RequestTransformerConfig?]) -- Composes the integer overflow, BigInt downcast, and default commitment transformers.
• getBigIntDowncastRequestTransformer() -- Downcasts all BigInt values to int.
• getIntegerOverflowRequestTransformer(IntegerOverflowHandler) -- Detects BigInt values that exceed the safe integer range.
• getDefaultCommitmentRequestTransformer({required Map optionsObjectPositionByMethod, Commitment? defaultCommitment}) -- Injects a default commitment into RPC method options.
• getTreeWalkerRequestTransformer(List<NodeVisitor>, TraversalState) -- Creates a request transformer from a list of tree-walking visitors.

Response Transformers

• getDefaultResponseTransformerForSolanaRpc([ResponseTransformerConfig?]) -- Composes error throwing, result extraction, and BigInt upcast transformers.
• getDefaultResponseTransformerForSolanaRpcSubscriptions([ResponseTransformerConfig?]) -- BigInt upcast transformer only (for WebSocket subscriptions).
• getBigIntUpcastResponseTransformer(List<KeyPath>) -- Upcasts integers to BigInt, except at the specified key paths.
• getResultResponseTransformer() -- Extracts the result field from a JSON-RPC response.
• getThrowSolanaErrorResponseTransformer() -- Throws a SolanaError if the response contains an error.
• getTreeWalkerResponseTransformer(List<NodeVisitor>, TraversalState) -- Creates a response transformer from a list of tree-walking visitors.

Configuration Classes

• RequestTransformerConfig -- Configuration with optional defaultCommitment and onIntegerOverflow.
• ResponseTransformerConfig -- Configuration with optional allowedNumericKeyPaths.

Tree Traversal

• TraversalState -- Holds the current keyPath during tree traversal.
• KeyPath -- List<Object> representing a path through a nested data structure.
• KEYPATH_WILDCARD -- Sentinel value that matches any key at a given level.
• NodeVisitor -- Object? Function(Object? value, TraversalState state) -- A function applied at each leaf node.

Typedefs

• IntegerOverflowHandler -- void Function(RpcRequest<Object?>, KeyPath, BigInt) -- Called when a BigInt exceeds safe range.
• AllowedNumericKeypaths -- Map<String, List<KeyPath>> -- Maps method names to key paths that should remain as int.

Constants

• OPTIONS_OBJECT_POSITION_BY_METHOD -- Maps each Solana RPC method name to the index of its options object in the params array.
• jsonParsedTokenAccountsConfigs -- Key paths for numeric values in parsed token accounts.
• jsonParsedAccountsConfigs -- Key paths for numeric values in all parsed accounts.
• innerInstructionsConfigs -- Key paths for numeric values in inner instructions.
• messageConfig -- Key paths for numeric values in transaction messages.

Example

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

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