Skip to content

Commit d065ea1

Browse files
committed
Add dynamic-parsers package
1 parent 4bcf5b6 commit d065ea1

23 files changed

+1143
-0
lines changed

.changeset/wicked-radios-cough.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@codama/dynamic-parsers': minor
3+
---
4+
5+
Add new `dynamic-parsers` package that identifies accounts and instructions from a root node and decodes the provided byte array accordingly
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,23 @@
1+
import { LinkableDictionary, NodeStack } from '@codama/visitors-core';
2+
import { containsBytes, ReadonlyUint8Array } from '@solana/codecs';
3+
4+
import { getNodeCodecVisitor } from './codecs';
5+
import { getValueNodeVisitor } from './values';
6+
17
export * from './codecs';
28
export * from './values';
9+
10+
export type { ReadonlyUint8Array };
11+
export { containsBytes };
12+
13+
export type CodecAndValueVisitors = {
14+
codecVisitor: ReturnType<typeof getNodeCodecVisitor>;
15+
valueVisitor: ReturnType<typeof getValueNodeVisitor>;
16+
};
17+
18+
export function getCodecAndValueVisitors(linkables: LinkableDictionary, options: { stack?: NodeStack } = {}) {
19+
const stack = options.stack ?? new NodeStack();
20+
const codecVisitor = getNodeCodecVisitor(linkables, { stack });
21+
const valueVisitor = getValueNodeVisitor(linkables, { codecVisitorFactory: () => codecVisitor, stack });
22+
return { codecVisitor, valueVisitor };
23+
}
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
dist/
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
dist/
2+
e2e/
3+
test-ledger/
4+
target/
5+
CHANGELOG.md

packages/dynamic-parsers/LICENSE

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

packages/dynamic-parsers/README.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Codama ➤ Dynamic Parsers
2+
3+
[![npm][npm-image]][npm-url]
4+
[![npm-downloads][npm-downloads-image]][npm-url]
5+
6+
[npm-downloads-image]: https://img.shields.io/npm/dm/@codama/dynamic-parsers.svg?style=flat
7+
[npm-image]: https://img.shields.io/npm/v/@codama/dynamic-parsers.svg?style=flat&label=%40codama%2Fdynamic-parsers
8+
[npm-url]: https://www.npmjs.com/package/@codama/dynamic-parsers
9+
10+
This package provides a set of helpers that, given any Codama IDL, dynamically identifies and parses any byte array into deserialized accounts, instructions and defined types.
11+
12+
## Installation
13+
14+
```sh
15+
pnpm install @codama/dynamic-parsers
16+
```
17+
18+
> [!NOTE]
19+
> This package is **not** included in the main [`codama`](../library) package.
20+
21+
## Types
22+
23+
### `ParsedData<TNode>`
24+
25+
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.
26+
27+
```ts
28+
type ParsedData<TNode extends AccountNode | InstructionNode> = {
29+
data: unknown;
30+
path: NodePath<TNode>;
31+
};
32+
```
33+
34+
## Functions
35+
36+
### `parseAccountData(rootNode, bytes)`
37+
38+
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.
39+
40+
```ts
41+
const parsedData = parseAccountData(rootNode, bytes);
42+
// ^ ParsedData<AccountNode> | undefined
43+
44+
if (parsedData) {
45+
const accountNode: AccountNode = getLastNodeFromPath(parsedData.path);
46+
const decodedData: unknown = parsedData.data;
47+
}
48+
```
49+
50+
### `parseInstructionData(rootNode, bytes)`
51+
52+
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.
53+
54+
```ts
55+
const parsedData = parseInstructionData(rootNode, bytes);
56+
// ^ ParsedData<InstructionNode> | undefined
57+
58+
if (parsedData) {
59+
const instructionNode: InstructionNode = getLastNodeFromPath(parsedData.path);
60+
const decodedData: unknown = parsedData.data;
61+
}
62+
```
63+
64+
### `parseInstruction(rootNode, instruction)`
65+
66+
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.
67+
68+
```ts
69+
const parsedData = parseInstruction(rootNode, instruction);
70+
71+
if (parsedData) {
72+
const namedAccounts = parsedData.accounts;
73+
// ^ Array<IAccountMeta & { name: string }>
74+
}
75+
```
76+
77+
### `identifyAccountData`
78+
79+
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.
80+
81+
```ts
82+
const path = identifyAccountData(root, bytes);
83+
// ^ NodePath<AccountNode> | undefined
84+
85+
if (path) {
86+
const accountNode: AccountNode = getLastNodeFromPath(path);
87+
}
88+
```
89+
90+
### `identifyInstructionData`
91+
92+
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.
93+
94+
```ts
95+
const path = identifyInstructionData(root, bytes);
96+
// ^ NodePath<InstructionNode> | undefined
97+
98+
if (path) {
99+
const instructionNode: InstructionNode = getLastNodeFromPath(path);
100+
}
101+
```
Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
{
2+
"name": "@codama/dynamic-parsers",
3+
"version": "1.0.0",
4+
"description": "Helpers to dynamically identify and parse accounts and instructions",
5+
"exports": {
6+
"types": "./dist/types/index.d.ts",
7+
"react-native": "./dist/index.react-native.mjs",
8+
"browser": {
9+
"import": "./dist/index.browser.mjs",
10+
"require": "./dist/index.browser.cjs"
11+
},
12+
"node": {
13+
"import": "./dist/index.node.mjs",
14+
"require": "./dist/index.node.cjs"
15+
}
16+
},
17+
"browser": {
18+
"./dist/index.node.cjs": "./dist/index.browser.cjs",
19+
"./dist/index.node.mjs": "./dist/index.browser.mjs"
20+
},
21+
"main": "./dist/index.node.cjs",
22+
"module": "./dist/index.node.mjs",
23+
"react-native": "./dist/index.react-native.mjs",
24+
"types": "./dist/types/index.d.ts",
25+
"type": "commonjs",
26+
"files": [
27+
"./dist/types",
28+
"./dist/index.*"
29+
],
30+
"sideEffects": false,
31+
"keywords": [
32+
"solana",
33+
"framework",
34+
"standard",
35+
"specifications",
36+
"parsers"
37+
],
38+
"scripts": {
39+
"build": "rimraf dist && pnpm build:src && pnpm build:types",
40+
"build:src": "zx ../../node_modules/@codama/internals/scripts/build-src.mjs package",
41+
"build:types": "zx ../../node_modules/@codama/internals/scripts/build-types.mjs",
42+
"dev": "zx ../../node_modules/@codama/internals/scripts/test-unit.mjs node --watch",
43+
"lint": "zx ../../node_modules/@codama/internals/scripts/lint.mjs",
44+
"lint:fix": "zx ../../node_modules/@codama/internals/scripts/lint.mjs --fix",
45+
"test": "pnpm test:types && pnpm test:treeshakability && pnpm test:browser && pnpm test:node && pnpm test:react-native",
46+
"test:browser": "zx ../../node_modules/@codama/internals/scripts/test-unit.mjs browser",
47+
"test:node": "zx ../../node_modules/@codama/internals/scripts/test-unit.mjs node",
48+
"test:react-native": "zx ../../node_modules/@codama/internals/scripts/test-unit.mjs react-native",
49+
"test:treeshakability": "zx ../../node_modules/@codama/internals/scripts/test-treeshakability.mjs",
50+
"test:types": "zx ../../node_modules/@codama/internals/scripts/test-types.mjs"
51+
},
52+
"dependencies": {
53+
"@codama/dynamic-codecs": "workspace:*",
54+
"@codama/errors": "workspace:*",
55+
"@codama/nodes": "workspace:*",
56+
"@codama/visitors-core": "workspace:*",
57+
"@solana/instructions": "2.0.0-rc.4"
58+
},
59+
"devDependencies": {
60+
"@solana/codecs": "2.0.0-rc.4"
61+
},
62+
"license": "MIT",
63+
"repository": {
64+
"type": "git",
65+
"url": "https://github.com/codama-idl/codama"
66+
},
67+
"bugs": {
68+
"url": "http://github.com/codama-idl/codama/issues"
69+
},
70+
"browserslist": [
71+
"supports bigint and not dead",
72+
"maintained node versions"
73+
]
74+
}
Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
import { CodecAndValueVisitors, containsBytes, ReadonlyUint8Array } from '@codama/dynamic-codecs';
2+
import {
3+
CODAMA_ERROR__DISCRIMINATOR_FIELD_HAS_NO_DEFAULT_VALUE,
4+
CODAMA_ERROR__DISCRIMINATOR_FIELD_NOT_FOUND,
5+
CodamaError,
6+
} from '@codama/errors';
7+
import {
8+
assertIsNode,
9+
ConstantDiscriminatorNode,
10+
constantDiscriminatorNode,
11+
constantValueNode,
12+
DiscriminatorNode,
13+
FieldDiscriminatorNode,
14+
isNode,
15+
SizeDiscriminatorNode,
16+
StructTypeNode,
17+
} from '@codama/nodes';
18+
import { visit } from '@codama/visitors-core';
19+
20+
export function matchDiscriminators(
21+
bytes: ReadonlyUint8Array,
22+
discriminators: DiscriminatorNode[],
23+
struct: StructTypeNode,
24+
visitors: CodecAndValueVisitors,
25+
): boolean {
26+
return (
27+
discriminators.length > 0 &&
28+
discriminators.every(discriminator => matchDiscriminator(bytes, discriminator, struct, visitors))
29+
);
30+
}
31+
32+
function matchDiscriminator(
33+
bytes: ReadonlyUint8Array,
34+
discriminator: DiscriminatorNode,
35+
struct: StructTypeNode,
36+
visitors: CodecAndValueVisitors,
37+
): boolean {
38+
if (isNode(discriminator, 'constantDiscriminatorNode')) {
39+
return matchConstantDiscriminator(bytes, discriminator, visitors);
40+
}
41+
if (isNode(discriminator, 'fieldDiscriminatorNode')) {
42+
return matchFieldDiscriminator(bytes, discriminator, struct, visitors);
43+
}
44+
assertIsNode(discriminator, 'sizeDiscriminatorNode');
45+
return matchSizeDiscriminator(bytes, discriminator);
46+
}
47+
48+
function matchConstantDiscriminator(
49+
bytes: ReadonlyUint8Array,
50+
discriminator: ConstantDiscriminatorNode,
51+
{ codecVisitor, valueVisitor }: CodecAndValueVisitors,
52+
): boolean {
53+
const codec = visit(discriminator.constant.type, codecVisitor);
54+
const value = visit(discriminator.constant.value, valueVisitor);
55+
const bytesToMatch = codec.encode(value);
56+
return containsBytes(bytes, bytesToMatch, discriminator.offset);
57+
}
58+
59+
function matchFieldDiscriminator(
60+
bytes: ReadonlyUint8Array,
61+
discriminator: FieldDiscriminatorNode,
62+
struct: StructTypeNode,
63+
visitors: CodecAndValueVisitors,
64+
): boolean {
65+
const field = struct.fields.find(field => field.name === discriminator.name);
66+
if (!field) {
67+
throw new CodamaError(CODAMA_ERROR__DISCRIMINATOR_FIELD_NOT_FOUND, {
68+
field: discriminator.name,
69+
});
70+
}
71+
if (!field.defaultValue) {
72+
throw new CodamaError(CODAMA_ERROR__DISCRIMINATOR_FIELD_HAS_NO_DEFAULT_VALUE, {
73+
field: discriminator.name,
74+
});
75+
}
76+
const constantNode = constantValueNode(field.type, field.defaultValue);
77+
const constantDiscriminator = constantDiscriminatorNode(constantNode, discriminator.offset);
78+
return matchConstantDiscriminator(bytes, constantDiscriminator, visitors);
79+
}
80+
81+
function matchSizeDiscriminator(bytes: ReadonlyUint8Array, discriminator: SizeDiscriminatorNode): boolean {
82+
return bytes.length === discriminator.size;
83+
}

0 commit comments

Comments
 (0)