@metaplex-foundation/kinobi 0.0.1

package/src/visitors/aggregators/GetNodeTreeStringVisitor.ts

@@ -0,0 +1,260 @@
+import type * as nodes from '../../nodes';
+import { Visitor } from '../Visitor';
+
+export class GetNodeTreeStringVisitor implements Visitor<string> {
+  indent = 0;
+
+  readonly separator: string;
+
+  constructor(separator = '|   ') {
+    this.separator = separator;
+  }
+
+  visitRoot(root: nodes.RootNode): string {
+    this.indent += 1;
+    const children = root.programs.map((program) => program.accept(this));
+    this.indent -= 1;
+    return [this.indented('[RootNode]'), ...children].join('\n');
+  }
+
+  visitProgram(program: nodes.ProgramNode): string {
+    this.indent += 1;
+    const children = [
+      ...program.accounts.map((account) => account.accept(this)),
+      ...program.instructionsWithSubs.map((ix) => ix.accept(this)),
+      ...program.definedTypes.map((type) => type.accept(this)),
+      ...program.errors.map((type) => type.accept(this)),
+    ];
+    this.indent -= 1;
+    const data = program.metadata;
+    const tags = [];
+    if (data.publicKey) tags.push(`publicKey: ${data.publicKey}`);
+    if (data.version) tags.push(`version: ${data.version}`);
+    if (data.origin) tags.push(`origin: ${data.origin}`);
+    const tagsStr = tags.length > 0 ? ` (${tags.join(', ')})` : '';
+    return [
+      this.indented(`[ProgramNode] ${data.name}${tagsStr}`),
+      ...children,
+    ].join('\n');
+  }
+
+  visitAccount(account: nodes.AccountNode): string {
+    const children: string[] = [];
+    children.push(this.indented(`[AccountNode] ${account.name}`));
+    this.indent += 1;
+    if (account.metadata.size !== null) {
+      children.push(this.indented(`size: ${account.metadata.size}`));
+    }
+    if (account.metadata.seeds.length > 0) {
+      children.push(this.indented('seeds:'));
+      this.indent += 1;
+      children.push(
+        ...account.metadata.seeds.map((seed) => {
+          if (seed.kind === 'programId') return this.indented('programId');
+          if (seed.kind === 'literal') return this.indented(`"${seed.value}"`);
+          this.indent += 1;
+          const type = seed.type.accept(this);
+          this.indent -= 1;
+          return [
+            this.indented(`${seed.name} (${seed.description})`),
+            type,
+          ].join('\n');
+        })
+      );
+      this.indent -= 1;
+    }
+    children.push(account.type.accept(this));
+    this.indent -= 1;
+    return children.join('\n');
+  }
+
+  visitInstruction(instruction: nodes.InstructionNode): string {
+    const children: string[] = [];
+    children.push(this.indented(`[InstructionNode] ${instruction.name}`));
+    this.indent += 1;
+    children.push(this.indented('accounts:'));
+    this.indent += 1;
+    children.push(
+      ...instruction.accounts.map((account) => {
+        const tags = [];
+        if (account.isWritable) tags.push('writable');
+        if (account.isSigner) tags.push('signer');
+        if (account.isOptional) tags.push('optional');
+        if (account.defaultsTo.kind !== 'none')
+          tags.push(`defaults to ${account.defaultsTo.kind}`);
+        const tagsAsString = tags.length > 0 ? ` (${tags.join(', ')})` : '';
+        return this.indented(account.name + tagsAsString);
+      })
+    );
+    this.indent -= 1;
+    children.push(this.indented('arguments:'));
+    this.indent += 1;
+    children.push(instruction.args.accept(this));
+    this.indent -= 1;
+    this.indent -= 1;
+    return children.join('\n');
+  }
+
+  visitDefinedType(definedType: nodes.DefinedTypeNode): string {
+    this.indent += 1;
+    const child = definedType.type.accept(this);
+    this.indent -= 1;
+    return [this.indented(`[DefinedTypeNode] ${definedType.name}`), child].join(
+      '\n'
+    );
+  }
+
+  visitError(error: nodes.ErrorNode): string {
+    return this.indented(
+      `[ErrorNode] ${error.name} (${error.code}): ${error.message}`
+    );
+  }
+
+  visitTypeArray(typeArray: nodes.TypeArrayNode): string {
+    this.indent += 1;
+    const child = typeArray.itemType.accept(this);
+    this.indent -= 1;
+    return [
+      this.indented(`[TypeArrayNode] Size: ${typeArray.size}`),
+      child,
+    ].join('\n');
+  }
+
+  visitTypeDefinedLink(typeDefinedLink: nodes.TypeDefinedLinkNode): string {
+    return this.indented(
+      `[TypeDefinedLinkNode] ${typeDefinedLink.definedType}`
+    );
+  }
+
+  visitTypeEnum(typeEnum: nodes.TypeEnumNode): string {
+    this.indent += 1;
+    const children = typeEnum.variants.map((variant) => variant.accept(this));
+    this.indent -= 1;
+    return [
+      this.indented(
+        `[TypeEnumNode]${typeEnum.name ? ` ${typeEnum.name}` : ''}`
+      ),
+      ...children,
+    ].join('\n');
+  }
+
+  visitTypeEnumEmptyVariant(
+    typeEnumEmptyVariant: nodes.TypeEnumEmptyVariantNode
+  ): string {
+    return this.indented(
+      `[TypeEnumEmptyVariantNode] ${typeEnumEmptyVariant.name}`
+    );
+  }
+
+  visitTypeEnumStructVariant(
+    typeEnumStructVariant: nodes.TypeEnumStructVariantNode
+  ): string {
+    this.indent += 1;
+    const child = typeEnumStructVariant.struct.accept(this);
+    this.indent -= 1;
+    return [
+      this.indented(
+        `[TypeEnumStructVariantNode] ${typeEnumStructVariant.name}`
+      ),
+      child,
+    ].join('\n');
+  }
+
+  visitTypeEnumTupleVariant(
+    typeEnumTupleVariant: nodes.TypeEnumTupleVariantNode
+  ): string {
+    this.indent += 1;
+    const child = typeEnumTupleVariant.tuple.accept(this);
+    this.indent -= 1;
+    return [
+      this.indented(`[TypeEnumTupleVariantNode] ${typeEnumTupleVariant.name}`),
+      child,
+    ].join('\n');
+  }
+
+  visitTypeLeaf(typeLeaf: nodes.TypeLeafNode): string {
+    return this.indented(`[TypeLeafNode] ${typeLeaf.type}`);
+  }
+
+  visitTypeLeafWrapper(typeLeafWrapper: nodes.TypeLeafWrapperNode): string {
+    this.indent += 1;
+    const child = typeLeafWrapper.leaf.accept(this);
+    this.indent -= 1;
+    return [
+      this.indented(`[TypeLeafWrapperNode] ${typeLeafWrapper.wrapper.kind}`),
+      child,
+    ].join('\n');
+  }
+
+  visitTypeMap(typeMap: nodes.TypeMapNode): string {
+    const result: string[] = [];
+    result.push(this.indented(`[TypeMapNode] ${typeMap.mapType}`));
+    this.indent += 1;
+    result.push(this.indented('keys:'));
+    this.indent += 1;
+    result.push(typeMap.keyType.accept(this));
+    this.indent -= 1;
+    result.push(this.indented('values:'));
+    this.indent += 1;
+    result.push(typeMap.valueType.accept(this));
+    this.indent -= 1;
+    this.indent -= 1;
+    return result.join('\n');
+  }
+
+  visitTypeOption(typeOption: nodes.TypeOptionNode): string {
+    this.indent += 1;
+    const child = typeOption.type.accept(this);
+    this.indent -= 1;
+    return [this.indented('[TypeOptionNode]'), child].join('\n');
+  }
+
+  visitTypeSet(typeSet: nodes.TypeSetNode): string {
+    this.indent += 1;
+    const child = typeSet.type.accept(this);
+    this.indent -= 1;
+    return [this.indented(`[TypeSetNode] ${typeSet.setType}`), child].join(
+      '\n'
+    );
+  }
+
+  visitTypeStruct(typeStruct: nodes.TypeStructNode): string {
+    this.indent += 1;
+    const children = typeStruct.fields.map((field) => field.accept(this));
+    this.indent -= 1;
+    return [
+      this.indented(`[TypeStructNode] ${typeStruct.name}`),
+      ...children,
+    ].join('\n');
+  }
+
+  visitTypeStructField(typeStructField: nodes.TypeStructFieldNode): string {
+    this.indent += 1;
+    const child = typeStructField.type.accept(this);
+    this.indent -= 1;
+    return [
+      this.indented(`[TypeStructFieldNode] ${typeStructField.name}`),
+      child,
+    ].join('\n');
+  }
+
+  visitTypeTuple(typeTuple: nodes.TypeTupleNode): string {
+    this.indent += 1;
+    const children = typeTuple.itemTypes.map((itemType) =>
+      itemType.accept(this)
+    );
+    this.indent -= 1;
+    return [this.indented('[TypeTupleNode]'), ...children].join('\n');
+  }
+
+  visitTypeVec(typeVec: nodes.TypeVecNode): string {
+    this.indent += 1;
+    const child = typeVec.itemType.accept(this);
+    this.indent -= 1;
+    return [this.indented('[TypeVecNode]'), child].join('\n');
+  }
+
+  indented(text: string) {
+    return this.separator.repeat(this.indent) + text;
+  }
+}

package/src/visitors/aggregators/GetResolvedInstructionAccountsVisitor.ts

@@ -0,0 +1,153 @@
+import type * as nodes from '../../nodes';
+import { InstructionNodeAccountDefaultsSeed } from '../../nodes';
+import { BaseThrowVisitor } from '../BaseThrowVisitor';
+
+export type ResolvedInstructionAccount = nodes.InstructionNodeAccount & {
+  position: number;
+  dependencyPosition: number;
+  dependsOn: string[];
+  resolvedIsSigner: boolean;
+  resolvedIsOptionalSigner: boolean;
+  resolvedIsOptional: boolean;
+};
+
+export class GetResolvedInstructionAccountsVisitor extends BaseThrowVisitor<
+  ResolvedInstructionAccount[]
+> {
+  protected stack: string[] = [];
+
+  protected visited = new Map<string, ResolvedInstructionAccount>();
+
+  protected raw = new Map<string, [nodes.InstructionNodeAccount, number]>();
+
+  protected error: string | null = null;
+
+  getError(): string | null {
+    return this.error;
+  }
+
+  visitInstruction(
+    instruction: nodes.InstructionNode
+  ): ResolvedInstructionAccount[] {
+    // Ensure we always start with a clean slate.
+    this.error = null;
+    this.stack = [];
+    this.visited = new Map();
+    this.raw = instruction.accounts.reduce(
+      (map, account, index) => map.set(account.name, [account, index]),
+      new Map<string, [nodes.InstructionNodeAccount, number]>()
+    );
+
+    // Visit all instruction accounts.
+    this.raw.forEach(([account, index]) => {
+      this.handleInstructionAccount(instruction, account, index);
+    });
+
+    return [...this.visited.values()].sort((a, b) => a.position - b.position);
+  }
+
+  handleInstructionAccount(
+    instruction: nodes.InstructionNode,
+    account: nodes.InstructionNodeAccount,
+    index: number
+  ): void {
+    // Ensure we don't visit the same account twice.
+    if (this.visited.has(account.name)) {
+      return;
+    }
+
+    // Ensure we don't have a circular dependency.
+    if (this.stack.includes(account.name)) {
+      const cycle = [...this.stack, account.name].join(' -> ');
+      this.error =
+        `Circular dependency detected in the accounts of ` +
+        `the "${instruction.name}" instruction. ` +
+        `Got the following account dependency cycle: ${cycle}.`;
+      throw new Error(this.error);
+    }
+
+    // Get account dependencies.
+    const dependsOn: string[] = [];
+    if (account.defaultsTo.kind === 'account') {
+      dependsOn.push(account.defaultsTo.name);
+    } else if (account.defaultsTo.kind === 'pda') {
+      type AccountSeed = Extract<
+        InstructionNodeAccountDefaultsSeed,
+        { kind: 'account' }
+      >;
+      const accounts = Object.values(account.defaultsTo.seeds)
+        .filter((seed): seed is AccountSeed => seed.kind === 'account')
+        .map((seed) => seed.name);
+      dependsOn.push(...new Set(accounts));
+    }
+
+    // Visit account dependencies first.
+    this.stack.push(account.name);
+    dependsOn.forEach((name) => {
+      const rawDependency = this.raw.get(name);
+      if (!rawDependency) {
+        this.error =
+          `Account "${name}" is not a valid dependency of account ` +
+          `"${account.name}" in the "${instruction.name}" instruction.`;
+        throw new Error(this.error);
+      }
+      const [dependency, dependencyIndex] = rawDependency;
+      this.handleInstructionAccount(instruction, dependency, dependencyIndex);
+    });
+    this.stack.pop();
+
+    const resolved: ResolvedInstructionAccount = {
+      ...account,
+      position: index,
+      dependencyPosition: this.visited.size,
+      dependsOn,
+      resolvedIsSigner: account.isSigner,
+      resolvedIsOptionalSigner: account.isOptionalSigner,
+      resolvedIsOptional: account.isOptional,
+    };
+
+    switch (resolved.defaultsTo.kind) {
+      case 'account':
+        const defaultAccount = this.visited.get(resolved.defaultsTo.name)!;
+        const resolvedIsPublicKey =
+          !account.isSigner && !defaultAccount.isSigner;
+        resolved.resolvedIsSigner = account.isSigner && defaultAccount.isSigner;
+        resolved.resolvedIsOptionalSigner =
+          !resolved.resolvedIsSigner && !resolvedIsPublicKey;
+        resolved.resolvedIsOptional = defaultAccount.isOptional;
+        break;
+      case 'publicKey':
+      case 'program':
+      case 'programId':
+        resolved.resolvedIsOptionalSigner = account.isSigner;
+        resolved.resolvedIsSigner = false;
+        resolved.resolvedIsOptional = false;
+        break;
+      case 'pda':
+        resolved.resolvedIsOptionalSigner = account.isSigner;
+        resolved.resolvedIsSigner = false;
+        resolved.resolvedIsOptional = false;
+        const { seeds } = resolved.defaultsTo;
+        Object.keys(seeds).forEach((seedKey) => {
+          const seed = seeds[seedKey];
+          if (seed.kind !== 'account') return;
+          const dependency = this.visited.get(seed.name)!;
+          if (dependency.resolvedIsOptional) {
+            this.error =
+              `Cannot use optional account "${seed.name}" as the "${seedKey}" PDA seed ` +
+              `for the "${account.name}" account of the "${instruction.name}" instruction.`;
+            throw new Error(this.error);
+          }
+        });
+        break;
+      case 'identity':
+      case 'payer':
+        resolved.resolvedIsOptional = false;
+        break;
+      default:
+        break;
+    }
+
+    this.visited.set(account.name, resolved);
+  }
+}

package/src/visitors/aggregators/index.ts

@@ -0,0 +1,6 @@
+export * from './GetByteSizeVisitor';
+export * from './GetDefaultValidatorBagVisitor';
+export * from './GetDefinedTypeHistogramVisitor';
+export * from './GetNodeInlineStringVisitor';
+export * from './GetNodeTreeStringVisitor';
+export * from './GetResolvedInstructionAccountsVisitor';

package/src/visitors/index.ts

@@ -0,0 +1,15 @@
+export * from './aggregators';
+export * from './transformers';
+export * from './workers';
+
+export * from './BaseDelegateVisitor';
+export * from './BaseNodeVisitor';
+export * from './BaseThrowVisitor';
+export * from './BaseVoidVisitor';
+export * from './DefaultVisitor';
+export * from './Dependency';
+export * from './NodeSelector';
+export * from './ValidatorBag';
+export * from './NodeStack';
+export * from './Visitable';
+export * from './Visitor';

package/src/visitors/transformers/AutoSetAnchorDiscriminatorsVisitor.ts

@@ -0,0 +1,90 @@
+import { sha256 } from '@noble/hashes/sha256';
+import { snakeCase } from '../../utils';
+import * as nodes from '../../nodes';
+import { BaseNodeVisitor } from '../BaseNodeVisitor';
+
+export class AutoSetAnchorDiscriminatorsVisitor extends BaseNodeVisitor {
+  protected program: nodes.ProgramNode | null = null;
+
+  visitProgram(program: nodes.ProgramNode): nodes.Node {
+    this.program = program;
+    const visitedProgram = new nodes.ProgramNode(
+      program.metadata,
+      program.accounts
+        .map((account) => account.accept(this))
+        .filter(nodes.assertNodeFilter(nodes.assertAccountNode)),
+      program.instructions
+        .map((instruction) => instruction.accept(this))
+        .filter(nodes.assertNodeFilter(nodes.assertInstructionNode)),
+      program.definedTypes,
+      program.errors
+    );
+    this.program = null;
+    return visitedProgram;
+  }
+
+  visitAccount(account: nodes.AccountNode): nodes.Node {
+    const shouldAddDiscriminator = this.program?.metadata.origin === 'anchor';
+    if (!shouldAddDiscriminator) return account;
+
+    const idlName = snakeCase(account.metadata.idlName);
+    const hash = sha256(`global:${idlName}`).slice(0, 8);
+
+    const discriminatorField = new nodes.TypeStructFieldNode(
+      {
+        name: 'discriminator',
+        docs: [],
+        defaultsTo: {
+          strategy: 'omitted',
+          value: getValueNodeFromBytes(hash),
+        },
+      },
+      new nodes.TypeArrayNode(new nodes.TypeLeafNode('u8'), 8)
+    );
+
+    return new nodes.AccountNode(
+      {
+        ...account.metadata,
+        discriminator: { kind: 'field', name: 'discriminator' },
+      },
+      new nodes.TypeStructNode(account.type.name, [
+        discriminatorField,
+        ...account.type.fields,
+      ])
+    );
+  }
+
+  visitInstruction(instruction: nodes.InstructionNode): nodes.Node {
+    const shouldAddDiscriminator = this.program?.metadata.origin === 'anchor';
+    if (!shouldAddDiscriminator) return instruction;
+
+    const idlName = snakeCase(instruction.metadata.idlName);
+    const hash = sha256(`global:${idlName}`).slice(0, 8);
+
+    const discriminatorField = new nodes.TypeStructFieldNode(
+      {
+        name: 'discriminator',
+        docs: [],
+        defaultsTo: {
+          strategy: 'omitted',
+          value: getValueNodeFromBytes(hash),
+        },
+      },
+      new nodes.TypeArrayNode(new nodes.TypeLeafNode('u8'), 8)
+    );
+
+    return new nodes.InstructionNode(
+      instruction.metadata,
+      instruction.accounts,
+      new nodes.TypeStructNode(instruction.args.name, [
+        discriminatorField,
+        ...instruction.args.fields,
+      ]),
+      instruction.subInstructions
+    );
+  }
+}
+
+function getValueNodeFromBytes(bytes: Uint8Array): nodes.ListValueNode {
+  return nodes.vList([...bytes].map((byte) => nodes.vScalar(byte)));
+}

package/src/visitors/transformers/AutoSetFixedAccountSizesVisitor.ts

@@ -0,0 +1,31 @@
+import * as nodes from '../../nodes';
+import { GetByteSizeVisitor } from '../aggregators';
+import { BaseThrowVisitor } from '../BaseThrowVisitor';
+import { TransformNodesVisitor } from './TransformNodesVisitor';
+
+export class AutoSetFixedAccountSizesVisitor extends BaseThrowVisitor<nodes.RootNode> {
+  visitRoot(root: nodes.RootNode): nodes.RootNode {
+    // Prepare the visitor that gets the byte size of a type.
+    const byteSizeVisitor = new GetByteSizeVisitor();
+    byteSizeVisitor.registerDefinedTypes(root.allDefinedTypes);
+
+    // Prepare the visitor that transforms account nodes.
+    const transformVisitor = new TransformNodesVisitor([
+      {
+        selector: (node) =>
+          nodes.isAccountNode(node) && node.metadata.size === null,
+        transformer: (node) => {
+          nodes.assertAccountNode(node);
+          const size = node.type.accept(byteSizeVisitor);
+          if (size === null) return node;
+          return new nodes.AccountNode({ ...node.metadata, size }, node.type);
+        },
+      },
+    ]);
+
+    // Execute the transform visitor on the Root node.
+    const transformedRoot = root.accept(transformVisitor);
+    nodes.assertRootNode(transformedRoot);
+    return transformedRoot;
+  }
+}

package/src/visitors/transformers/CreateSubInstructionsFromEnumArgsVisitor.ts

@@ -0,0 +1,117 @@
+import { mainCase } from '../../utils';
+import { logWarn } from '../../logs';
+import * as nodes from '../../nodes';
+import { NodeTransform, TransformNodesVisitor } from './TransformNodesVisitor';
+import { unwrapStruct } from './UnwrapStructVisitor';
+
+export class CreateSubInstructionsFromEnumArgsVisitor extends TransformNodesVisitor {
+  protected allDefinedTypes = new Map<string, nodes.DefinedTypeNode>();
+
+  constructor(readonly map: Record<string, string>) {
+    const transforms = Object.entries(map).map(
+      ([selector, argNameInput]): NodeTransform => {
+        const selectorStack = selector.split('.');
+        const name = selectorStack.pop();
+        return {
+          selector: { type: 'instruction', stack: selectorStack, name },
+          transformer: (node) => {
+            nodes.assertInstructionNode(node);
+            const argName = mainCase(argNameInput);
+            const argFieldIndex = node.args.fields.findIndex(
+              (field) => field.name === argName
+            );
+            const argField =
+              argFieldIndex >= 0 ? node.args.fields[argFieldIndex] : null;
+            if (!argField) {
+              logWarn(`Could not find instruction argument [${argName}].`);
+              return node;
+            }
+
+            let argType: nodes.TypeEnumNode;
+            if (nodes.isTypeEnumNode(argField.type)) {
+              argType = argField.type;
+            } else if (
+              nodes.isTypeDefinedLinkNode(argField.type) &&
+              this.allDefinedTypes.has(argField.type.name)
+            ) {
+              const linkedType =
+                this.allDefinedTypes.get(argField.type.name)?.type ?? null;
+              nodes.assertTypeEnumNode(linkedType);
+              argType = linkedType;
+            } else {
+              logWarn(
+                `Could not find an enum type for ` +
+                  `instruction argument [${argName}].`
+              );
+              return node;
+            }
+
+            const subInstructions = argType.variants.map(
+              (variant, index): nodes.InstructionNode => {
+                const subName = mainCase(`${node.name} ${variant.name}`);
+                const subFields = node.args.fields.slice(0, argFieldIndex);
+                subFields.push(
+                  new nodes.TypeStructFieldNode(
+                    {
+                      name: `${subName}Discriminator`,
+                      docs: [],
+                      defaultsTo: {
+                        strategy: 'omitted',
+                        value: nodes.vScalar(index),
+                      },
+                    },
+                    new nodes.TypeLeafNode('u8')
+                  )
+                );
+                if (nodes.isTypeEnumStructVariantNode(variant)) {
+                  subFields.push(
+                    new nodes.TypeStructFieldNode(
+                      argField.metadata,
+                      variant.struct
+                    )
+                  );
+                } else if (nodes.isTypeEnumTupleVariantNode(variant)) {
+                  subFields.push(
+                    new nodes.TypeStructFieldNode(
+                      argField.metadata,
+                      variant.tuple
+                    )
+                  );
+                }
+                subFields.push(...node.args.fields.slice(argFieldIndex + 1));
+
+                return new nodes.InstructionNode(
+                  { ...node.metadata, name: subName },
+                  node.accounts,
+                  unwrapStruct(
+                    new nodes.TypeStructNode(
+                      `${subName}InstructionArgs`,
+                      subFields
+                    )
+                  ),
+                  []
+                );
+              }
+            );
+
+            return new nodes.InstructionNode(
+              node.metadata,
+              node.accounts,
+              node.args,
+              [...node.subInstructions, ...subInstructions]
+            );
+          },
+        };
+      }
+    );
+
+    super(transforms);
+  }
+
+  visitRoot(root: nodes.RootNode): nodes.Node | null {
+    root.allDefinedTypes.forEach((type) => {
+      this.allDefinedTypes.set(type.name, type);
+    });
+    return super.visitRoot(root);
+  }
+}