@kinobi-so/visitors
v0.22.0
Published
All visitors for the Kinobi framework
Downloads
1,653
Maintainers
Readme
Kinobi ➤ Visitors
This package offers various visitors for Kinobi IDLs to traverse and manipulate their nodes.
Installation
pnpm install @kinobi-so/visitors
[!NOTE] This package is included in the main
kinobi
package. Meaning, you already have access to its content if you are installing Kinobi this way.pnpm install kinobi
Understanding visitors
This package includes and re-exports the @kinobi-so/visitors-core
package which provides the core interfaces and functions to create and compose visitors.
To get a better understanding of visitors and how they work, please refer to the @kinobi-so/visitors-core
documentation.
In the rest of this documentation, we focus on the high-level visitors that are only available in this package. The main goal of these visitors is to provide a set of specific operations that can be applied to Kinobi IDLs — as opposed to the generic primitives provided by the core package.
For instance, this package offers visitors that unwrap link nodes, update instructions, add PDAs, set default values, and more.
Let's go through all of them alphabetically.
Available visitors
addPdasVisitor
This visitor adds PdaNodes
to the desired ProgramNodes
. It accepts an object where the keys are the program names and the values are the PdaNodes
to add within these programs.
kinobi.update(
addPdasVisitor({
// Add a PDA to the 'token' program.
token: [
{
name: 'associatedToken',
seeds: [
variablePdaSeedNode('mint', publicKeyTypeNode()),
constantPdaSeedNode(
publicKeyTypeNode(),
publicKeyValueNode('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'),
),
variablePdaSeedNode('owner', publicKeyTypeNode()),
],
},
],
// Add two PDAs to the 'counter' program.
counter: [
{
name: 'counter',
seeds: [variablePdaSeedNode('authority', publicKeyTypeNode())],
},
{
name: 'counterConfig',
seeds: [variablePdaSeedNode('counter', publicKeyTypeNode())],
},
],
}),
);
createSubInstructionsFromEnumArgsVisitor
This visitor splits an instruction into multiple sub-instructions by using an enum argument such that each of its variants creates a different sub-instruction. It accepts an object where the keys are the instruction names and the values are the enum argument names that will be used to split the instruction.
kinobi.update(
createSubInstructionsFromEnumArgsVisitor({
mint: 'mintArgs',
transfer: 'transferArgs',
burn: 'burnArgs',
}),
);
deduplicateIdenticalDefinedTypesVisitor
This visitor goes through the DefinedTypeNodes
of all ProgramNodes
inside the Kinobi IDL and removes any duplicates. A DefinedTypeNode
is considered a duplicate if it has the same name and data structure as another DefinedTypeNode
. This is useful when you have multiple programs that share the same types.
kinobi.update(deduplicateIdenticalDefinedTypesVisitor());
fillDefaultPdaSeedValuesVisitor
This visitor fills any missing PdaSeedValueNodes
from PdaValueNodes
using the provided InstructionNode
such that:
- If a
VariablePdaSeedNode
is of typePublicKeyTypeNode
and the name of the seed matches the name of an account in theInstructionNode
, then a newPdaSeedValueNode
will be added with the matching account. - Otherwise, if a
VariablePdaSeedNode
is of any other type and the name of the seed matches the name of an argument in theInstructionNode
, then a newPdaSeedValueNode
will be added with the matching argument. - Otherwise, no
PdaSeedValueNode
will be added.
It also requires a LinkableDictionary
to resolve any link nodes and an optional strictMode
boolean to throw an error if seeds are still missing after the visitor has run.
Note that this visitor is mainly used for internal purposes.
kinobi.update(fillDefaultPdaSeedValuesVisitor(instructionNode, linkables, strictMode));
flattenInstructionDataArgumentsVisitor
This visitor flattens any instruction arguments of type StructTypeNode
such that their fields are no longer nested. This can be useful to simplify the data structure of an instruction.
kinobi.update(flattenInstructionDataArgumentsVisitor());
flattenStructVisitor
This visitor flattens any struct fields that are also structs such that their fields are no longer nested. It accepts an object such that the keys are the struct names and the values are the field names to flatten or "*"
to flatten all struct fields.
kinobi.update(
flattenStructVisitor({
counter: ['data', 'config'],
escrow: '*',
}),
);
getDefinedTypeHistogramVisitor
This visitor goes through all DefinedTypeNodes
and outputs a histogram of how many times each type is used in the Kinobi IDL.
const histogram = kinobi.accept(getDefinedTypeHistogramVisitor());
The returned histogram is an object such that the keys are the names of visited DefinedTypeNodes
and the values are objects with properties described below.
export type DefinedTypeHistogram = {
[key: CamelCaseString]: {
// The number of times the type is used as a direct instruction argument.
directlyAsInstructionArgs: number;
// The number of times the type is used in account data.
inAccounts: number;
// The number of times the type is used in other defined types.
inDefinedTypes: number;
// The number of times the type is used in instruction arguments.
inInstructionArgs: number;
// The number of times the type is used in total.
total: number;
};
};
This histogram is used internally in other visitors to understand how types are used before applying transformations.
setAccountDiscriminatorFromFieldVisitor
This visitor helps set account discriminators based on a field in the account data and the value it should take. This is typically used on the very first field of the account data which usually refers to a discriminator value that helps distinguish between multiple accounts in a program.
kinobi.update(
setAccountDiscriminatorFromFieldVisitor({
counter: { field: 'discriminator', value: k.enumValueNode('accountState', 'counter') },
escrow: { field: 'discriminator', value: k.enumValueNode('accountState', 'escrow') },
vault: { field: 'discriminator', value: k.enumValueNode('accountState', 'vault') },
}),
);
setFixedAccountSizesVisitor
This visitor uses the getByteSizeVisitor
to check the size of all AccountNodes
and, if a fixed-size is identified, it sets the size
property of the account to that value.
kinobi.update(setFixedAccountSizesVisitor());
setInstructionAccountDefaultValuesVisitor
This visitor helps set the default values of instruction accounts in bulk. It accepts an array of "rule" objects that must contain the default value to set and the name of the instruction account to set it on. The account name may also be a regular expression to match more complex patterns.
kinobi.update(
setInstructionAccountDefaultValuesVisitor([
{
// Set this public key as default value to any account named 'counterProgram'.
account: 'counterProgram',
defaultValue: publicKeyValueNode('MyCounterProgram11111111111111111111111111'),
},
{
// Set this PDA as default value to any account named 'associatedToken' or 'ata'.
account: /^(associatedToken|ata)$/,
defaultValue: pdaValueNode('associatedToken'),
},
]),
);
setInstructionDiscriminatorsVisitor
This visitor adds a new instruction argument to each of the provided instruction names. The new argument is added before any existing argument and marked as a discriminator of the instruction. This is useful if your Kinobi IDL is missing discriminators in the instruction data.
kinobi.update(
setInstructionDiscriminatorsVisitor({
mint: { name: 'discriminator', type: numberTypeNode('u8'), value: numberValueNode(0) },
transfer: { name: 'discriminator', type: numberTypeNode('u8'), value: numberValueNode(1) },
burn: { name: 'discriminator', type: numberTypeNode('u8'), value: numberValueNode(2) },
}),
);
setNumberWrappersVisitor
This visitor helps wrap NumberTypeNodes
matching a given name with a specific number wrapper.
kinobi.update(
setNumberWrappersVisitor({
lamports: { kind: 'SolAmount' },
timestamp: { kind: 'DateTime' },
percent: { decimals: 2, kind: 'Amount', unit: '%' },
}),
);
setStructDefaultValuesVisitor
This visitor sets default values for all provided fields of a struct. It accepts an object where the keys are the struct names and the values are objects that map field names to their new default values.
kinobi.update(
setStructDefaultValuesVisitor({
person: {
age: numberValueNode(42),
dateOfBirth: noneValueNode(),
},
counter: {
count: numberValueNode(0),
},
}),
);
transformDefinedTypesIntoAccountsVisitor
This visitor transforms DefinedTypeNodes
matching the provided names into AccountNodes
within the same ProgramNode
.
kinobi.update(transformDefinedTypesIntoAccountsVisitor(['counter', 'escrow']));
transformU8ArraysToBytesVisitor
This visitor transforms any fixed-size array of u8
numbers into a fixed-size BytesTypeNode
.
kinobi.update(transformU8ArraysToBytesVisitor());
unwrapDefinedTypesVisitor
This visitor replaces any DefinedTypeLinkNode
with the actual DefinedTypeNode
it points to. By default, it unwraps all defined types, but you can provide an array of names to only unwrap specific types.
Note that if multiple link nodes point to the same defined type, each link node will be replaced by a copy of the defined type.
kinobi.update(unwrapDefinedTypesVisitor(['counter', 'escrow']));
unwrapInstructionArgsDefinedTypesVisitor
This visitor replaces DefinedTypeLinkNodes
used only once inside an instruction argument with the actual DefinedTypeNodes
they refer to.
kinobi.update(unwrapInstructionArgsDefinedTypesVisitor());
unwrapTupleEnumWithSingleStructVisitor
This visitor transforms EnumTupleVariantTypeNodes
with a single StructTypeNode
item into EnumStructVariantTypeNodes
. By default, it will unwrap all tuple variants matching that criteria, but you can provide an array of names to only unwrap specific variants.
kinobi.update(unwrapTupleEnumWithSingleStructVisitor());
unwrapTypeDefinedLinksVisitor
This visitor replaces any DefinedTypeLinkNode
matching the provided NodeSelectors
with the actual DefinedTypeNode
it points to.
Contrary to the unwrapDefinedTypesVisitor
though, it only replaces the requested DefinedTypeLinkNodes
and does not remove the associated DefinedTypeNode
from its ProgramNode
.
kinobi.update(unwrapTypeDefinedLinksVisitor(['[accountNode]counter.data', '[instructionNode]transfer.config']));
updateAccountsVisitor
This visitor allows us to update various aspects of AccountNodes
and/or delete them. It accepts an object where the keys are the account names and the values are the operations to apply to these accounts.
kinobi.update(
updateAccountsVisitor({
vault: {
// Rename the 'vault' account to 'safe'.
name: 'safe',
// Rename the 'owner' field to 'authority'.
data: { owner: 'authority' },
// Create a new PDA node and link it to this account.
seeds: [variablePdaSeedNode('authority', publicKeyTypeNode())],
},
counter: {
// Delete the 'counter' account.
delete: true,
},
}),
);
updateDefinedTypesVisitor
This visitor allows us to update various aspects of DefinedTypeNode
and/or delete them. It accepts an object where the keys are the defined type names and the values are the operations to apply to these types.
kinobi.update(
updateDefinedTypesVisitor({
options: {
// Rename the 'options' type to 'configs'.
name: 'configs',
// Rename the 'sol' field to 'lamports'.
data: { sol: 'lamports' },
},
player: {
// Delete the 'player' type.
delete: true,
},
}),
);
updateErrorsVisitor
This visitor allows us to update various aspects of ErrorNodes
and/or delete them. It accepts an object where the keys are the error names and the values are the operations to apply to these errors.
kinobi.update(
updateErrorsVisitor({
invalidPda: {
// Rename the 'invalidPda' error to 'invalidProgramDerivedAddress'.
name: 'invalidProgramDerivedAddress',
// Change the error message.
message: 'The program-derived address is invalid.',
// Change the error code.
code: 123,
},
accountMismatch: {
// Delete the 'accountMismatch' error.
delete: true,
},
}),
);
updateInstructionsVisitor
This visitor allows us to update various aspects of InstructionNodes
and/or delete them. It accepts an object where the keys are the instruction names and the values are the operations to apply to these instructions.
kinobi.update(
updateInstructionsVisitor({
send: {
// Rename the 'send' instruction to 'transfer'.
name: 'transfer',
accounts: {
// Rename the 'owner' instruction account to 'authority'.
owner: { name: 'authority' },
// Set a default value for the 'associatedToken' instruction account.
associatedToken: { defaultValue: pdaValueNode('associatedToken') },
// Update the signer status of the 'payer' instruction account to `true`.
payer: { isSigner: true },
// Mark the 'mint' instruction account as optional.
mint: { isOptional: true },
},
arguments: {
// Set a default value for the 'amount' instruction argument to 1.
amount: { defaultValue: numberValueNode(1) },
// Rename the 'decimals' instruction argument to 'mintDecimals'.
decimals: { name: 'mintDecimals' },
},
},
burn: {
// Delete the 'burn' instruction.
delete: true,
},
}),
);
updateProgramsVisitor
This visitor allows us to update various aspects of ProgramNodes
and/or delete them. It accepts an object where the keys are the program names and the values are the operations to apply to these programs.
kinobi.update(
updateProgramsVisitor({
splToken: {
// Rename the 'splToken' program to 'token'.
name: 'token',
// Change the program version.
version: '3.0.0',
// Change the program's public key.
publicKey: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
},
splAssociatedToken: {
// Delete the 'splAssociatedToken' program.
delete: true,
},
}),
);