Add dynamic-parsers package

.changeset/wicked-radios-cough.md

@@ -0,0 +1,5 @@
+---
+'@codama/dynamic-parsers': minor
+---
+
+Add new `dynamic-parsers` package that identifies accounts and instructions from a root node and decodes the provided byte array accordingly

packages/dynamic-codecs/src/index.ts

@@ -1,2 +1,23 @@
+import { LinkableDictionary, NodeStack } from '@codama/visitors-core';
+import { containsBytes, ReadonlyUint8Array } from '@solana/codecs';
+
+import { getNodeCodecVisitor } from './codecs';
+import { getValueNodeVisitor } from './values';
+
 export * from './codecs';
 export * from './values';
+
+export type { ReadonlyUint8Array };
+export { containsBytes };
+
+export type CodecAndValueVisitors = {
+    codecVisitor: ReturnType<typeof getNodeCodecVisitor>;
+    valueVisitor: ReturnType<typeof getValueNodeVisitor>;
+};
+
+export function getCodecAndValueVisitors(linkables: LinkableDictionary, options: { stack?: NodeStack } = {}) {
+    const stack = options.stack ?? new NodeStack();
+    const codecVisitor = getNodeCodecVisitor(linkables, { stack });
+    const valueVisitor = getValueNodeVisitor(linkables, { codecVisitorFactory: () => codecVisitor, stack });
+    return { codecVisitor, valueVisitor };
+}

packages/dynamic-parsers/.gitignore

@@ -0,0 +1 @@
+dist/

packages/dynamic-parsers/.prettierignore

@@ -0,0 +1,5 @@
+dist/
+e2e/
+test-ledger/
+target/
+CHANGELOG.md

packages/dynamic-parsers/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Codama
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/dynamic-parsers/README.md

@@ -0,0 +1,101 @@
+# Codama ➤ Dynamic Parsers
+
+[![npm][npm-image]][npm-url]
+[![npm-downloads][npm-downloads-image]][npm-url]
+
+[npm-downloads-image]: https://img.shields.io/npm/dm/@codama/dynamic-parsers.svg?style=flat
+[npm-image]: https://img.shields.io/npm/v/@codama/dynamic-parsers.svg?style=flat&label=%40codama%2Fdynamic-parsers
+[npm-url]: https://www.npmjs.com/package/@codama/dynamic-parsers
+
+This package provides a set of helpers that, given any Codama IDL, dynamically identifies and parses any byte array into deserialized accounts and instructions.
+
+## Installation
+
+```sh
+pnpm install @codama/dynamic-parsers
+```
+
+> [!NOTE]
+> This package is **not** included in the main [`codama`](../library) package.
+
+## Types
+
+### `ParsedData<TNode>`
+
+This type represents the result of identifying and parsing a byte array from a given root node. It provides us with the full `NodePath` of the identified node, as well as the data deserialized from the provided bytes.
+
+```ts
+type ParsedData<TNode extends AccountNode | InstructionNode> = {
+    data: unknown;
+    path: NodePath<TNode>;
+};
+```
+
+## Functions
+
+### `parseAccountData(rootNode, bytes)`
+
+Given a `RootNode` and a byte array, this function will attempt to identify the correct account node and use it to deserialize the provided bytes. Therefore, it returns a `ParsedData<AccountNode>` object if the parsing was successful, or `undefined` otherwise.
+
+```ts
+const parsedData = parseAccountData(rootNode, bytes);
+// ^ ParsedData<AccountNode> | undefined
+
+if (parsedData) {
+    const accountNode: AccountNode = getLastNodeFromPath(parsedData.path);
+    const decodedData: unknown = parsedData.data;
+}
+```
+
+### `parseInstructionData(rootNode, bytes)`
+
+Similarly to `parseAccountData`, this function will match the provided bytes to an instruction node and deserialize them accordingly. It returns a `ParsedData<InstructionNode>` object if the parsing was successful, or `undefined` otherwise.
+
+```ts
+const parsedData = parseInstructionData(rootNode, bytes);
+// ^ ParsedData<InstructionNode> | undefined
+
+if (parsedData) {
+    const instructionNode: InstructionNode = getLastNodeFromPath(parsedData.path);
+    const decodedData: unknown = parsedData.data;
+}
+```
+
+### `parseInstruction(rootNode, instruction)`
+
+This function accepts a `RootNode` and an `IInstruction` type — as defined in `@solana/instructions` — in order to return a `ParsedData<InstructionNode>` object that also includes an `accounts` array that match each `IAccountMeta` with its corresponding account name.
+
+```ts
+const parsedData = parseInstruction(rootNode, instruction);
+
+if (parsedData) {
+    const namedAccounts = parsedData.accounts;
+    // ^ Array<IAccountMeta & { name: string }>
+}
+```
+
+### `identifyAccountData`
+
+This function tries to match the provided bytes to an account node, returning a `NodePath<AccountNode>` object if the identification was successful, or `undefined` otherwise. It is used by the `parseAccountData` function under the hood.
+
+```ts
+const path = identifyAccountData(root, bytes);
+// ^ NodePath<AccountNode> | undefined
+
+if (path) {
+    const accountNode: AccountNode = getLastNodeFromPath(path);
+}
+```
+
+### `identifyInstructionData`
+
+This function tries to match the provided bytes to an instruction node, returning a `NodePath<InstructionNode>` object if the identification was successful, or `undefined` otherwise. It is used by the `parseInstructionData` function under the hood.
+
+```ts
+const path = identifyInstructionData(root, bytes);
+// ^ NodePath<InstructionNode> | undefined
+
+if (path) {
+    const instructionNode: InstructionNode = getLastNodeFromPath(path);
+}
+```

packages/dynamic-parsers/package.json

@@ -0,0 +1,74 @@
+{
+    "name": "@codama/dynamic-parsers",
+    "version": "1.0.0",
+    "description": "Helpers to dynamically identify and parse accounts and instructions",
+    "exports": {
+        "types": "./dist/types/index.d.ts",
+        "react-native": "./dist/index.react-native.mjs",
+        "browser": {
+            "import": "./dist/index.browser.mjs",
+            "require": "./dist/index.browser.cjs"
+        },
+        "node": {
+            "import": "./dist/index.node.mjs",
+            "require": "./dist/index.node.cjs"
+        }
+    },
+    "browser": {
+        "./dist/index.node.cjs": "./dist/index.browser.cjs",
+        "./dist/index.node.mjs": "./dist/index.browser.mjs"
+    },
+    "main": "./dist/index.node.cjs",
+    "module": "./dist/index.node.mjs",
+    "react-native": "./dist/index.react-native.mjs",
+    "types": "./dist/types/index.d.ts",
+    "type": "commonjs",
+    "files": [
+        "./dist/types",
+        "./dist/index.*"
+    ],
+    "sideEffects": false,
+    "keywords": [
+        "solana",
+        "framework",
+        "standard",
+        "specifications",
+        "parsers"
+    ],
+    "scripts": {
+        "build": "rimraf dist && pnpm build:src && pnpm build:types",
+        "build:src": "zx ../../node_modules/@codama/internals/scripts/build-src.mjs package",
+        "build:types": "zx ../../node_modules/@codama/internals/scripts/build-types.mjs",
+        "dev": "zx ../../node_modules/@codama/internals/scripts/test-unit.mjs node --watch",
+        "lint": "zx ../../node_modules/@codama/internals/scripts/lint.mjs",
+        "lint:fix": "zx ../../node_modules/@codama/internals/scripts/lint.mjs --fix",
+        "test": "pnpm test:types && pnpm test:treeshakability && pnpm test:browser && pnpm test:node && pnpm test:react-native",
+        "test:browser": "zx ../../node_modules/@codama/internals/scripts/test-unit.mjs browser",
+        "test:node": "zx ../../node_modules/@codama/internals/scripts/test-unit.mjs node",
+        "test:react-native": "zx ../../node_modules/@codama/internals/scripts/test-unit.mjs react-native",
+        "test:treeshakability": "zx ../../node_modules/@codama/internals/scripts/test-treeshakability.mjs",
+        "test:types": "zx ../../node_modules/@codama/internals/scripts/test-types.mjs"
+    },
+    "dependencies": {
+        "@codama/dynamic-codecs": "workspace:*",
+        "@codama/errors": "workspace:*",
+        "@codama/nodes": "workspace:*",
+        "@codama/visitors-core": "workspace:*",
+        "@solana/instructions": "2.0.0-rc.4"
+    },
+    "devDependencies": {
+        "@solana/codecs": "2.0.0-rc.4"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/codama-idl/codama"
+    },
+    "bugs": {
+        "url": "http://github.com/codama-idl/codama/issues"
+    },
+    "browserslist": [
+        "supports bigint and not dead",
+        "maintained node versions"
+    ]
+}

packages/dynamic-parsers/src/discriminators.ts

@@ -0,0 +1,83 @@
+import { CodecAndValueVisitors, containsBytes, ReadonlyUint8Array } from '@codama/dynamic-codecs';
+import {
+    CODAMA_ERROR__DISCRIMINATOR_FIELD_HAS_NO_DEFAULT_VALUE,
+    CODAMA_ERROR__DISCRIMINATOR_FIELD_NOT_FOUND,
+    CodamaError,
+} from '@codama/errors';
+import {
+    assertIsNode,
+    ConstantDiscriminatorNode,
+    constantDiscriminatorNode,
+    constantValueNode,
+    DiscriminatorNode,
+    FieldDiscriminatorNode,
+    isNode,
+    SizeDiscriminatorNode,
+    StructTypeNode,
+} from '@codama/nodes';
+import { visit } from '@codama/visitors-core';
+
+export function matchDiscriminators(
+    bytes: ReadonlyUint8Array,
+    discriminators: DiscriminatorNode[],
+    struct: StructTypeNode,
+    visitors: CodecAndValueVisitors,
+): boolean {
+    return (
+        discriminators.length > 0 &&
+        discriminators.every(discriminator => matchDiscriminator(bytes, discriminator, struct, visitors))
+    );
+}
+
+function matchDiscriminator(
+    bytes: ReadonlyUint8Array,
+    discriminator: DiscriminatorNode,
+    struct: StructTypeNode,
+    visitors: CodecAndValueVisitors,
+): boolean {
+    if (isNode(discriminator, 'constantDiscriminatorNode')) {
+        return matchConstantDiscriminator(bytes, discriminator, visitors);
+    }
+    if (isNode(discriminator, 'fieldDiscriminatorNode')) {
+        return matchFieldDiscriminator(bytes, discriminator, struct, visitors);
+    }
+    assertIsNode(discriminator, 'sizeDiscriminatorNode');
+    return matchSizeDiscriminator(bytes, discriminator);
+}
+
+function matchConstantDiscriminator(
+    bytes: ReadonlyUint8Array,
+    discriminator: ConstantDiscriminatorNode,
+    { codecVisitor, valueVisitor }: CodecAndValueVisitors,
+): boolean {
+    const codec = visit(discriminator.constant.type, codecVisitor);
+    const value = visit(discriminator.constant.value, valueVisitor);
+    const bytesToMatch = codec.encode(value);
+    return containsBytes(bytes, bytesToMatch, discriminator.offset);
+}
+
+function matchFieldDiscriminator(
+    bytes: ReadonlyUint8Array,
+    discriminator: FieldDiscriminatorNode,
+    struct: StructTypeNode,
+    visitors: CodecAndValueVisitors,
+): boolean {
+    const field = struct.fields.find(field => field.name === discriminator.name);
+    if (!field) {
+        throw new CodamaError(CODAMA_ERROR__DISCRIMINATOR_FIELD_NOT_FOUND, {
+            field: discriminator.name,
+        });
+    }
+    if (!field.defaultValue) {
+        throw new CodamaError(CODAMA_ERROR__DISCRIMINATOR_FIELD_HAS_NO_DEFAULT_VALUE, {
+            field: discriminator.name,
+        });
+    }
+    const constantNode = constantValueNode(field.type, field.defaultValue);
+    const constantDiscriminator = constantDiscriminatorNode(constantNode, discriminator.offset);
+    return matchConstantDiscriminator(bytes, constantDiscriminator, visitors);
+}
+
+function matchSizeDiscriminator(bytes: ReadonlyUint8Array, discriminator: SizeDiscriminatorNode): boolean {
+    return bytes.length === discriminator.size;
+}