Codama ➤ Dynamic Codecs

This package provides a set of helpers that provide Codecs for Codama nodes that describe data.

Installation

pnpm install @codama/dynamic-codecs

[!NOTE] This package is not included in the main codama package.

Functions

getNodeCodec(path, options?)

Given the full NodePath of a node inside a Codama IDL, returns a Codec<unknown> (as defined in @solana/codecs) that enables encoding and decoding data for that node.

const codec = getNodeCodec([root, program, definedType]);
const bytes = codec.encode(someData);
const decodedData = codec.decode(bytes);

Note that it is important to provide the full NodePath of the node in order to properly follow link nodes inside the Codama IDL. Here is a more complex example illustrating how link nodes are resolved:

// Here we define a program with two types, one of which is a link to the other.
const root = rootNode(
    programNode({
        definedTypes: [
            definedTypeNode({ name: 'slot', type: numberTypeNode('u64') }),
            definedTypeNode({ name: 'lastSlot', type: definedTypeLinkNode('slot') }),
        ],
        name: 'myProgram',
        publicKey: '1111',
    }),
);

// The codec for the linked `lastSlot` defined type is resolved using the `slot` defined type.
const codec = getNodeCodec([root, root.program, root.program.definedTypes[1]]);
expect(codec.encode(42)).toStrictEqual(hex('2a00000000000000'));
expect(codec.decode(hex('2a00000000000000'))).toBe(42n);

Options

The getNodeCodec function accepts the following options.

| Name | Type | Default | Description | | --------------- | --------------- | ---------- | -------------------------------------------------------- | | bytesEncoding | BytesEncoding | "base64" | The default encoding to use when formatting plain bytes. |

Decoded format

In the table below, we illustrate the format of each codec based on the node from which it was created.

Note that we purposefully avoid types such as Uint8Array, Set or Map in order to keep the format JSON compatible. For instance, plain bytes are not provided as Uint8Array but as a tuple of type [BytesEncoding, string] — e.g. ["base64", "HelloWorld++"] — where the default bytes encoding is base64 which is configurable via the bytesEncoding option.

| Node | Example | Notes | | --------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | AccountLinkNode | - | Same as AccountNode | | AccountNode | - | Same as node.data | | DefinedTypeLinkNode | - | Same as DefinedTypeNode | | DefinedTypeNode | - | Same as node.type | | InstructionArgumentLinkNode | - | Same as InstructionArgumentNode | | InstructionArgumentNode | - | Same as node.type | | InstructionLinkNode | - | Same as InstructionNode | | InstructionNode | - | Same as a StructTypeNode containing all node.arguments | | AmountTypeNode | 42 | Same as NumberTypeNode | | ArrayTypeNode | [1, 2, 3] | | | BooleanTypeNode | true or false | | | BytesTypeNode | ["base16", "00ffaa"] | Uses bytesEncoding option to decode | | DateTimeTypeNode | 42 | Same as NumberTypeNode | | EnumTypeNode | 2 or { __kind: "move", x: 12, y: 34 } | Uses number indices for scalar enums. Uses discriminated unions otherwise. | | FixedSizeTypeNode | - | Same as node.type | | HiddenPrefixTypeNode | - | Same as node.type | | HiddenSuffixTypeNode | - | Same as node.type | | MapTypeNode | { key1: "value1", key2: "value2" } | Represent Maps as objects | | NumberTypeNode | 42 | This could be a bigint | | OptionTypeNode | { __option: "Some", value: 42 } or { __option: "None" } | Uses value objects (instead of T \| null) to avoid loosing information on nested options. | | PostOffsetTypeNode | - | Same as node.type | | PreOffsetTypeNode | - | Same as node.type | | PublicKeyTypeNode | "3QC7Pnv2KfwwdC44gPcmQWuZXmRSbUpmWMJnhenMC8CU" | Uses base58 representations of public keys | | RemainderOptionTypeNode | { __option: "Some", value: 42 } or { __option: "None" } | Same as OptionTypeNode | | SentinelTypeNode | - | Same as node.type | | SetTypeNode | [1, 2, 3] | Same as ArrayTypeNode | | SizePrefixTypeNode | - | Same as node.type | | SolAmountTypeNode | 42 | Same as NumberTypeNode | | StringTypeNode | "Hello World" | Uses the encoding defined in the node — i.e. node.encoding | | StructTypeNode | { name: "John", age: 42 } | | | TupleTypeNode | ["John", 42] | Uses arrays to create tuples | | ZeroableOptionTypeNode | { __option: "Some", value: 42 } or { __option: "None" } | Same as OptionTypeNode |

getNodeCodecVisitor(linkables, options?)

This visitor is used by getNodeCodec under the hood. It returns a Codec<unknown> for the visited node.

return visit(someTypeNode, getNodeCodecVisitor(linkables));

getValueNodeVisitor(linkables, options?)

This visitor is used by the getValueNodeVisitor under the hood. It returns an unknown value for the visited ValueNode.

return visit(someValueNode, getValueNodeVisitor(linkables));