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

Author: lorisleiva

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'));
+```