Add node documentation — Part 3: ContextualValueNodes (#98)

packages/nodes/docs/contextualValueNodes/AccountBumpValueNode.md

@@ -0,0 +1,52 @@
+# `AccountBumpValueNode`
+
+A node that refers to the seed bump of a PDA account.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                     | Description              |
+| --------- | ------------------------ | ------------------------ |
+| `kind`    | `"accountBumpValueNode"` | The node discriminator.  |
+| `name`    | `CamelCaseString`        | The name of the account. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `accountBumpValueNode(name)`
+
+Helper function that creates a `AccountBumpValueNode` object from the account name.
+
+```ts
+const node = accountBumpValueNode('associatedTokenAccount');
+```
+
+## Examples
+
+### An instruction argument defaulting to the bump derivation of an instruction account
+
+```ts
+instructionNode({
+    name: 'transfer',
+    accounts: [
+        instructionAccountNode({
+            name: 'associatedTokenAccount',
+            isSigner: false,
+            isWritable: true,
+        }),
+        // ...
+    ],
+    arguments: [
+        instructionArgumentNode({
+            name: 'bump',
+            type: numberTypeNode('u8'),
+            defaultValue: accountBumpValueNode('associatedTokenAccount'),
+        }),
+        // ...
+    ],
+});
+```

packages/nodes/docs/contextualValueNodes/AccountValueNode.md

@@ -0,0 +1,50 @@
+# `AccountValueNode`
+
+A node that refers to an account — e.g. an instruction account in the context of an instruction.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                 | Description              |
+| --------- | -------------------- | ------------------------ |
+| `kind`    | `"accountValueNode"` | The node discriminator.  |
+| `name`    | `CamelCaseString`    | The name of the account. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `accountValueNode(name)`
+
+Helper function that creates a `AccountValueNode` object from the account name.
+
+```ts
+const node = accountValueNode('mint');
+```
+
+## Examples
+
+### An instruction account defaulting to another account
+
+```ts
+instructionNode({
+    name: 'mint',
+    accounts: [
+        instructionAccountNode({
+            name: 'payer',
+            isSigner: true,
+            isWritable: false,
+        }),
+        instructionAccountNode({
+            name: 'authority',
+            isSigner: false,
+            isWritable: true,
+            defaultValue: accountValueNode('payer'),
+        }),
+        // ...
+    ],
+});
+```

packages/nodes/docs/contextualValueNodes/ArgumentValueNode.md

@@ -0,0 +1,48 @@
+# `ArgumentValueNode`
+
+A node that refers to an argument — e.g. an instruction argument in the context of an instruction.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                  | Description               |
+| --------- | --------------------- | ------------------------- |
+| `kind`    | `"argumentValueNode"` | The node discriminator.   |
+| `name`    | `CamelCaseString`     | The name of the argument. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `argumentValueNode(name)`
+
+Helper function that creates a `ArgumentValueNode` object from the argument name.
+
+```ts
+const node = argumentValueNode('amount');
+```
+
+## Examples
+
+### An instruction argument defaulting to another argument
+
+```ts
+instructionNode({
+    name: 'mint',
+    arguments: [
+        instructionArgumentNode({
+            name: 'amount',
+            type: numberTypeNode('u64'),
+        }),
+        instructionArgumentNode({
+            name: 'amountToDelegate',
+            type: numberTypeNode('u64'),
+            defaultValue: argumentValueNode('amount'),
+        }),
+        // ...
+    ],
+});
+```

packages/nodes/docs/contextualValueNodes/ConditionalValueNode.md

@@ -0,0 +1,70 @@
+# `ConditionalValueNode`
+
+A value node that differs based on a condition.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                     | Description             |
+| --------- | ------------------------ | ----------------------- |
+| `kind`    | `"conditionalValueNode"` | The node discriminator. |
+
+### Children
+
+| Attribute   | Type                                                                                                                                          | Description                                                                                                                          |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `condition` | [`AccountValueNode`](./AccountValueNode.md) \| [`ArgumentValueNode`](./ArgumentValueNode.md) \| [`ResolverValueNode`](./ResolverValueNode.md) | The condition that must be met. If it is an argument or value node, the `value` attribute may be used to assert on a specific value. |
+| `value`     | [`ValueNode`](../valueNodes/README.md)                                                                                                        | (Optional) If provided, the `condition` must be equal to this value. Otherwise, the `condition` must simply exist.                   |
+| `ifTrue`    | [`InstructionInputValueNode`](./InstructionInputValueNode.md)                                                                                 | (Optional) The value to use if the condition is true.                                                                                |
+| `ifFalse`   | [`InstructionInputValueNode`](./InstructionInputValueNode.md)                                                                                 | (Optional) The value to use if the condition is false.                                                                               |
+
+## Functions
+
+### `conditionalValueNode(input)`
+
+Helper function that creates a `ConditionalValueNode` object from an input object.
+
+```ts
+const node = conditionalValueNode({
+    condition: argumentValueNode('amount'),
+    value: numberValueNode(0),
+    ifTrue: accountValueNode('mint'),
+    ifFalse: programIdValueNode(),
+});
+```
+
+## Examples
+
+### An instruction account that defaults to another account if a condition is met
+
+```ts
+instructionNode({
+    name: 'transfer',
+    accounts: [
+        instructionAccountNode({
+            name: 'source',
+            isSigner: false,
+            isWritable: true,
+        }),
+        instructionAccountNode({
+            name: 'destination',
+            isSigner: false,
+            isWritable: true,
+            isOptional: true,
+            defaultValue: conditionalValueNode({
+                condition: argumentValueNode('amount'),
+                value: numberValueNode(0),
+                ifTrue: accountValueNode('source'),
+            }),
+        }),
+        // ...
+    ],
+    arguments: [
+        instructionArgumentNode({
+            name: 'amount',
+            type: numberTypeNode('u64'),
+        }),
+    ],
+});
+```

packages/nodes/docs/contextualValueNodes/IdentityValueNode.md

@@ -0,0 +1,48 @@
+# `IdentityValueNode`
+
+A node that represents the main wallet that should **own things**.
+
+For instance, in an web application, the identity would be the user's wallet; in a terminal, the identity would be the wallet identitied by `solana address`; etc.
+
+Note that a similar node exists for representing the main wallet that should **pay for things** — the [`PayerValueNode`](./PayerValueNode.md). In practice, the identity and the payer are often the same but allowing the program maintainer to offer this distinction can be useful should they be different.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                  | Description             |
+| --------- | --------------------- | ----------------------- |
+| `kind`    | `"identityValueNode"` | The node discriminator. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `identityValueNode()`
+
+Helper function that creates a `IdentityValueNode` object.
+
+```ts
+const node = identityValueNode();
+```
+
+## Examples
+
+### An instruction account defaulting to the identity value
+
+```ts
+instructionNode({
+    name: 'transfer',
+    accounts: [
+        instructionAccountNode({
+            name: 'authority',
+            isSigner: true,
+            isWritable: false,
+            defaultValue: identityValueNode(),
+        }),
+        // ...
+    ],
+});
+```

packages/nodes/docs/contextualValueNodes/InstructionInputValueNode.md

@@ -0,0 +1,7 @@
+# `InstructionInputValueNode` (abstract)
+
+The `InstructionInputValueNode` type helper represents all values that can be used as a default value for an instruction account or an instruction argument. Note that `InstructionInputValueNode` is a type alias and cannot be used directly as a node. Instead you may use one of the following nodes:
+
+-   [`ContextualValueNode`](./README.md) (abstract)
+-   [`ProgramLinkNode`](../linkNodes/ProgramLinkNode.md)
+-   [`ValueNode`](../valueNodes/README.md) (abstract)

packages/nodes/docs/contextualValueNodes/PayerValueNode.md

@@ -0,0 +1,48 @@
+# `PayerValueNode`
+
+A node that represents the main wallet that should **pay for things**.
+
+For instance, in an web application, the payer would be the user's wallet; in a terminal, the payer would be the wallet identitied by `solana address`; etc.
+
+Note that a similar node exists for representing the main wallet that should **own things** — the [`IdentityValueNode`](./IdentityValueNode.md). In practice, the payer and the identity are often the same but allowing the program maintainer to offer this distinction can be useful should they be different.
+
+## Attributes
+
+### Data
+
+| Attribute | Type               | Description             |
+| --------- | ------------------ | ----------------------- |
+| `kind`    | `"payerValueNode"` | The node discriminator. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `payerValueNode()`
+
+Helper function that creates a `PayerValueNode` object.
+
+```ts
+const node = payerValueNode();
+```
+
+## Examples
+
+### An instruction account defaulting to the payer value
+
+```ts
+instructionNode({
+    name: 'transfer',
+    accounts: [
+        instructionAccountNode({
+            name: 'payer',
+            isSigner: true,
+            isWritable: false,
+            defaultValue: payerValueNode(),
+        }),
+        // ...
+    ],
+});
+```

packages/nodes/docs/contextualValueNodes/PdaSeedValueNode.md

@@ -0,0 +1,28 @@
+# `PdaSeedValueNode`
+
+A node that represents the value of a variable PDA seed.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                 | Description                    |
+| --------- | -------------------- | ------------------------------ |
+| `kind`    | `"pdaSeedValueNode"` | The node discriminator.        |
+| `name`    | `CamelCaseString`    | The name of the variable seed. |
+
+### Children
+
+| Attribute | Type                                                                                                                                   | Description                                                                                                                         |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `value`   | [`AccountValueNode`](./AccountValueNode.md) \| [`ArgumentValueNode`](./ArgumentValueNode.md) \| [`ValueNode`](../valueNodes/README.md) | The value of the variable PDA seed. This can be a simple `ValueNode` or a contextual value pointing to another account or argument. |
+
+## Functions
+
+### `pdaSeedValueNode(name, value)`
+
+Helper function that creates a `PdaSeedValueNode` object from the name of the variable seed and its value.
+
+```ts
+const node = pdaSeedValueNode('mint', accountValueNode('mint'));
+```

packages/nodes/docs/contextualValueNodes/PdaValueNode.md

@@ -0,0 +1,60 @@
+# `PdaValueNode`
+
+A node that represents a PDA value. It alone can be used to derive the PDA address.
+
+## Attributes
+
+### Data
+
+| Attribute | Type             | Description             |
+| --------- | ---------------- | ----------------------- |
+| `kind`    | `"pdaValueNode"` | The node discriminator. |
+
+### Children
+
+| Attribute | Type                                                                       | Description                                                                                                                                                                                          |
+| --------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pda`     | [`PdaLinkNode`](../linkNodes/PdaLinkNode.md) \| [`PdaNode`](../PdaNode.md) | The PDA definition to use. It can either be a `PdaLinkNode` — therefore pointing to an existing PDA definition on the `ProgramNode` — or a direct `PdaNode` if we want to inline the PDA definition. |
+| `seeds`   | [`PdaSeedValueNode`](./PdaSeedValueNode.md)[]                              | The values of all variable seeds in the PDA.                                                                                                                                                         |
+
+## Functions
+
+### `pdaValueNode(pda, seeds)`
+
+Helper function that creates a `PdaValueNode` object from a PDA definition and an array of seed values. When a `string` is provided as the `pda` definition, it is used as a `PdaLinkNode`.
+
+```ts
+const node = pdaValueNode('associatedToken', [
+    pdaSeedValueNode('mint', publicKeyValueNode('G345gmp34svbGxyXuCvKVVHDbqJQ66y65vVrx7m7FmBE')),
+    pdaSeedValueNode('owner', publicKeyValueNode('Nzgr9bYfMRq5768bHfXsXoPTnLWAXgQNosRBxK63jRH')),
+]);
+```
+
+## Examples
+
+### A PDA value whose seeds point to other accounts
+
+```ts
+pdaValueNode('associatedToken', [
+    pdaSeedValueNode('mint', accountValueNode('mint')),
+    pdaSeedValueNode('owner', accountValueNode('authority')),
+]);
+```
+
+### A PDA value with an inlined PDA definition
+
+```ts
+const inlinedPdaNode = pdaNode({
+    name: 'associatedToken',
+    seeds: [
+        variablePdaSeedNode('mint', publicKeyTypeNode()),
+        constantPdaSeedNode(publicKeyTypeNode(), publicKeyValueNode('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA')),
+        variablePdaSeedNode('owner', publicKeyTypeNode()),
+    ],
+});
+
+pdaValueNode(inlinedPdaNode, [
+    pdaSeedValueNode('mint', accountValueNode('mint')),
+    pdaSeedValueNode('owner', accountValueNode('authority')),
+]);
+```

packages/nodes/docs/contextualValueNodes/ProgramIdValueNode.md

@@ -0,0 +1,25 @@
+# `ProgramIdValueNode`
+
+A node that represents the public key of the current program. That is, the address of the `ProgramNode` from which this node descends.
+
+## Attributes
+
+### Data
+
+| Attribute | Type                   | Description             |
+| --------- | ---------------------- | ----------------------- |
+| `kind`    | `"programIdValueNode"` | The node discriminator. |
+
+### Children
+
+_This node has no children._
+
+## Functions
+
+### `programIdValueNode()`
+
+Helper function that creates a `ProgramIdValueNode` object.
+
+```ts
+const node = programIdValueNode();
+```

packages/nodes/docs/contextualValueNodes/README.md

@@ -0,0 +1,13 @@
+# `ContextualValueNode` (abstract)
+
+The `ContextualValueNode` type helper represents all the available contextual value nodes. Note that `ContextualValueNode` is a type alias and cannot be used directly as a node. Instead you may use one of the following nodes:
+
+-   [`AccountBumpValueNode`](./AccountBumpValueNode.md)
+-   [`AccountValueNode`](./AccountValueNode.md)
+-   [`ArgumentValueNode`](./ArgumentValueNode.md)
+-   [`ConditionalValueNode`](./ConditionalValueNode.md)
+-   [`IdentityValueNode`](./IdentityValueNode.md)
+-   [`PayerValueNode`](./PayerValueNode.md)
+-   [`PdaValueNode`](./PdaValueNode.md)
+-   [`ProgramIdValueNode`](./ProgramIdValueNode.md)
+-   [`ResolverValueNode`](./ResolverValueNode.md)

packages/nodes/docs/contextualValueNodes/ResolverValueNode.md

@@ -0,0 +1,39 @@
+# `ResolverValueNode`
+
+A node that represents any custom value or logic described by some documentation.
+
+This node acts as a fallback node for any value or logic that cannot easily be described by the other nodes. Instead, the program maintainer can use this node to describe the value or logic in detail. Visitors that render code from Kinobi IDLs will treat these `ResolverValueNodes` as functions that can be injected into the generated code.
+
+## Attributes
+
+### Data
+
+| Attribute    | Type                  | Description                                                                                                                                                                                                                                                                                                                        |
+| ------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kind`       | `"resolverValueNode"` | The node discriminator.                                                                                                                                                                                                                                                                                                            |
+| `name`       | `CamelCaseString`     | A unique name for the resolver. This will typically be the name of the function that the renderers will try to invoke.                                                                                                                                                                                                             |
+| `docs`       | `string[]`            | Detailed Markdown documentation for the resolver.                                                                                                                                                                                                                                                                                  |
+| `importFrom` | `string`              | (Optional) A unique string that identifies the module from which the resolver should be imported. Defaults to `"hooked"` meaning the function is locally available next to the generated code. Note that this is a renderer-specific piece of data that may be removed in the future and pushed to the renderers' options instead. |
+
+### Children
+
+| Attribute   | Type                                                                                             | Description                                                                                                                                                                  |
+| ----------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dependsOn` | ([`AccountValueNode`](./AccountValueNode.md) \| [`ArgumentValueNode`](./ArgumentValueNode.md))[] | (Optional) The list of accounts or arguments that this custom value depends on. This is useful for code renderers to know in which order they should resolve default values. |
+
+## Functions
+
+### `resolverValueNode(name, options)`
+
+Helper function that creates a `ResolverValueNode` object from the resolver name and some options.
+
+```ts
+const node = resolverValueNode('resolveCustomTokenProgram', {
+    docs: [
+        'If the mint account has more than 0 decimals and the ',
+        'delegated amount is greater than zero, than we use our ',
+        'own custom token program. Otherwise, we use Token 2022.',
+    ],
+    dependsOn: [accountValueNode('mint'), argumentValueNode('delegatedAmount')],
+});
+```