Skip to content

Commit 4d0d3af

Browse files
lorisleivalorisleiva
authored
Add node documentation — Part 4: Top-level nodes (#99)
1 parent 9aa6cb8 commit 4d0d3af

File tree

11 files changed

+799
-0
lines changed

11 files changed

+799
-0
lines changed

‎packages/nodes/docs/AccountNode.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# `AccountNode`
2+
3+
This node defines an on-chain account. It is characterized by its name, data structure, and optional attributes such as PDA definition and account discriminators.
4+
5+
![Diagram](https://github.com/kinobi-so/kinobi/assets/3642397/77974dad-212e-49b1-8e41-5d466c273a02)
6+
7+
## Attributes
8+
9+
### Data
10+
11+
| Attribute | Type | Description |
12+
| --------- | ----------------- | ----------------------------------------------------------------------------------- |
13+
| `kind` | `"accountNode"` | The node discriminator. |
14+
| `name` | `CamelCaseString` | The name of the account. |
15+
| `docs` | `string[]` | Markdown documentation for the account. |
16+
| `size` | `number` | (Optional) The size of the account in bytes, if the account's data length is fixed. |
17+
18+
### Children
19+
20+
| Attribute | Type | Description |
21+
| ---------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
22+
| `data` | [`NestedTypeNode`](./typeNodes/NestedTypeNode.md)<[`StructTypeNode`](./typeNodes/StructTypeNode.md)> | The type node that describes the account's data. Note that it must be a struct so we can access its fields via other nodes. |
23+
| `pda` | [`PdaLinkNode`](./linkNodes/PdaLinkNode.md) | (Optional) The link node that describes the account's PDA, if its address is derived from one. |
24+
| `discriminators` | [`DiscriminatorNode`](./discriminatorNodes/README.md)[] | (Optional) The nodes that distinguish this account from others in the program. If multiple discriminators are provided, they are combined using a logical AND operation. |
25+
26+
## Functions
27+
28+
### `accountNode(input)`
29+
30+
Helper function that creates a `AccountNode` object from an input object.
31+
32+
```ts
33+
const node = accountNode({
34+
name: 'myCounter',
35+
data: structTypeNode([
36+
structFieldTypeNode({ name: 'authority', type: publicKeyTypeNode() }),
37+
structFieldTypeNode({ name: 'value', type: numberTypeNode('u64') }),
38+
]),
39+
});
40+
```
41+
42+
## Examples
43+
44+
### A fixed-size account
45+
46+
```ts
47+
const node = accountNode({
48+
name: 'token',
49+
data: structTypeNode([
50+
structFieldTypeNode({ name: 'mint', type: publicKeyTypeNode() }),
51+
structFieldTypeNode({ name: 'owner', type: publicKeyTypeNode() }),
52+
structFieldTypeNode({ name: 'amount', type: numberTypeNode('u64') }),
53+
]),
54+
discriminators: [sizeDiscriminatorNode(72)],
55+
size: 72,
56+
});
57+
```
58+
59+
### An account with a linked PDA
60+
61+
```ts
62+
programNode({
63+
name: 'myProgram',
64+
accounts: [
65+
accountNode({
66+
name: 'token',
67+
data: structTypeNode([structFieldTypeNode({ name: 'authority', type: publicKeyTypeNode() })]),
68+
pda: pdaLinkNode('myPda'),
69+
}),
70+
],
71+
pdas: [
72+
pdaNode({
73+
name: 'myPda',
74+
seeds: [
75+
constantPdaSeedNodeFromString('utf8', 'token'),
76+
variablePdaSeedNode('authority', publicKeyTypeNode()),
77+
],
78+
}),
79+
],
80+
});
81+
```

‎packages/nodes/docs/ErrorNode.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# `ErrorNode`
2+
3+
This node defines an error that can be returned by a program.
4+
5+
![Diagram](https://github.com/kinobi-so/kinobi/assets/3642397/0bde98ea-0327-404b-bf38-137d105826b0)
6+
7+
## Attributes
8+
9+
### Data
10+
11+
| Attribute | Type | Description |
12+
| --------- | ----------------- | ------------------------------------------------ |
13+
| `kind` | `"errorNode"` | The node discriminator. |
14+
| `name` | `CamelCaseString` | The name of the error. |
15+
| `code` | `number` | The error code. |
16+
| `message` | `string` | A human-friendly message describing the error. |
17+
| `docs` | `string[]` | Additional Markdown documentation for the error. |
18+
19+
### Children
20+
21+
_This node has no children._
22+
23+
## Functions
24+
25+
### `errorNode(input)`
26+
27+
Helper function that creates a `ErrorNode` object from an input object.
28+
29+
```ts
30+
const node = errorNode({
31+
name: 'invalidAmountArgument',
32+
code: 1,
33+
message: 'The amount argument is invalid.',
34+
});
35+
```

‎packages/nodes/docs/InstructionAccountNode.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# `InstructionAccountNode`
2+
3+
This node defines an account used by an instruction. It is characterized by its name and various requirements such as whether it needs to be writable or a signer.
4+
5+
![Diagram](https://github.com/kinobi-so/kinobi/assets/3642397/4656a08b-2f89-49c2-b428-5378cb1a0b9e)
6+
7+
## Attributes
8+
9+
### Data
10+
11+
| Attribute | Type | Description |
12+
| ------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
13+
| `kind` | `"instructionAccountNode"` | The node discriminator. |
14+
| `name` | `CamelCaseString` | The name of the instruction account. |
15+
| `isWritable` | `boolean` | Whether of not the account needs to be writable. |
16+
| `isSigner` | `boolean` \| `"either"` | Whether or not the account needs to be a signer. If the value `"either"` is provided, the account can be either a signer or not depending on the context. |
17+
| `isOptional` | `boolean` | (Optional) Whether or not the account is optional. If this is `true`, the account should be handled as an optional account according to the `optionalAccountStrategy` attribute of the [`InstructionNode`.](./InstructionNode.md) Defaults to `false`. |
18+
| `docs` | `string[]` | Markdown documentation for the instruction account. |
19+
20+
### Children
21+
22+
| Attribute | Type | Description |
23+
| -------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
24+
| `defaultValue` | [`InstructionInputValueNode`](./contextualValueNodes/InstructionInputValueNode.md) | (Optional) A default value for the account should this account not be provided when constructing the instruction. |
25+
26+
## Functions
27+
28+
### `instructionAccountNode(input)`
29+
30+
Helper function that creates a `InstructionAccountNode` object from an input object.
31+
32+
```ts
33+
const node = instructionAccountNode({
34+
name: 'authority',
35+
isWritable: false,
36+
isSigner: true,
37+
docs: ['This account that has the authority to perform this instruction.'],
38+
});
39+
```
40+
41+
## Examples
42+
43+
### An optional account
44+
45+
```ts
46+
instructionAccountNode({
47+
name: 'freezeAuthority',
48+
isWritable: false,
49+
isSigner: false,
50+
isOptional: true,
51+
docs: ['The freeze authority to set on the asset, if any.'],
52+
});
53+
```
54+
55+
### An optional signer account
56+
57+
```ts
58+
instructionAccountNode({
59+
name: 'owner',
60+
isWritable: true,
61+
isSigner: 'either',
62+
docs: ['The owner of the asset. The owner must only sign the transaction if the asset is being updated.'],
63+
});
64+
```

‎packages/nodes/docs/InstructionArgumentNode.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# `InstructionArgumentNode`
2+
3+
This node defines an argument that is passed to an instruction. When all arguments are combined and serialized next to each other, they form the instruction's data.
4+
5+
![Diagram](https://github.com/kinobi-so/kinobi/assets/3642397/7e2def82-949a-4663-bdc3-ac599d39d2d2)
6+
7+
## Attributes
8+
9+
### Data
10+
11+
| Attribute | Type | Description |
12+
| ---------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13+
| `kind` | `"instructionArgumentNode"` | The node discriminator. |
14+
| `name` | `CamelCaseString` | The name of the instruction argument. |
15+
| `docs` | `string[]` | Markdown documentation for the instruction argument. |
16+
| `defaultValueStrategy` | `"optional"` \| `"omitted"` | (Optional) The strategy to use when a default value is provided for the argument. `"optional"` means that the argument's default value may be overriden by a provided argument, while `"omitted"` means that no argument should be provided and the default value should always be the argument's value. Defaults to `"optional"`. |
17+
18+
### Children
19+
20+
| Attribute | Type | Description |
21+
| -------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
22+
| `type` | [`TypeNode`](./typeNodes/README.md) | The `TypeNode` that describes the argument's data. |
23+
| `defaultValue` | [`InstructionInputValueNode`](./contextualValueNodes/InstructionInputValueNode.md) | (Optional) A default value for the argument should this argument not be provided when constructing the instruction. |
24+
25+
## Functions
26+
27+
### `instructionArgumentNode(input)`
28+
29+
Helper function that creates a `InstructionArgumentNode` object from an input object.
30+
31+
```ts
32+
const node = instructionArgumentNode({
33+
name: 'amount',
34+
type: numberTypeNode('u64'),
35+
docs: ['This amount of tokens to transfer.'],
36+
});
37+
```
38+
39+
## Examples
40+
41+
### An argument with a default value
42+
43+
```ts
44+
instructionArgumentNode({
45+
name: 'amount',
46+
type: numberTypeNode('u64'),
47+
defaultValue: numberValueNode(0),
48+
});
49+
```
50+
51+
### An argument with an omitted default value
52+
53+
```ts
54+
instructionArgumentNode({
55+
name: 'instructionDiscriminator',
56+
type: numberTypeNode('u8'),
57+
defaultValue: numberValueNode(42),
58+
defaultValueStrategy: 'omitted',
59+
});
60+
```

‎packages/nodes/docs/InstructionByteDeltaNode.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# `InstructionByteDeltaNode`
2+
3+
This node represents a difference in bytes stored on-chain from executing an instruction. For instance, if an instruction creates a new account of 42 bytes, this node can provide this information. This enables clients to allocate the right amount of lamports to cover the cost of executing the instruction.
4+
5+
## Attributes
6+
7+
### Data
8+
9+
| Attribute | Type | Description |
10+
| ------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11+
| `kind` | `"instructionByteDeltaNode"` | The node discriminator. |
12+
| `withHeader` | `boolean` | (Optional) Whether or not we should add the account header size — i.e. 128 bytes — to the value. Default to `false` when the value is a `ResolverValueNode` and `true` otherwise. |
13+
| `subtract` | `boolean` | (Optional) Whether or not the provided value should be subtracted from the total byte delta. Defaults to `false`. |
14+
15+
### Children
16+
17+
| Attribute | Type | Description |
18+
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
19+
| `value` | [`AccountLinkNode`](./linkNodes/AccountLinkNode.md) \| [`ArgumentValueNode`](./contextualValueNodes/ArgumentValueNode.md) \| [`NumberValueNode`](./valueNodes/NumberValueNode.md) \| [`ResolverValueNode`](./contextualValueNodes/ResolverValueNode.md) | The value representing the byte delta. If an `AccountLinkNode` is used, the size of the linked account will be used. If an `ArgumentValueNode` is used, the value of the instruction argument will be used. If a `NumberValueNode` is used, that explicit number will be used. Otherwise, a `ResolverValueNode` can be used as a fallback for more complex values. |
20+
21+
## Functions
22+
23+
### `instructionByteDeltaNode(value, options?)`
24+
25+
Helper function that creates a `InstructionByteDeltaNode` object from a value node and some options.
26+
27+
```ts
28+
const node = instructionByteDeltaNode(numberValueNode(42), { withHeader: false });
29+
```
30+
31+
## Examples
32+
33+
### A byte delta that represents a new account
34+
35+
```ts
36+
instructionByteDeltaNode(accountLinkNode('token'));
37+
```
38+
39+
### A byte delta that represents an account deletion
40+
41+
```ts
42+
instructionByteDeltaNode(accountLinkNode('token'), { subtract: true });
43+
```
44+
45+
### A byte delta that uses an argument value to increase the space of an account
46+
47+
```ts
48+
instructionByteDeltaNode(argumentValueNode('additionalSpace'), { withHeader: false });
49+
```

0 commit comments

Comments
 (0)