@0xsequence/catapult 1.1.0

package/src/lib/types/__tests__/read-json-value.spec.ts

@@ -0,0 +1,264 @@
+import { ReadJsonValue } from '../values'
+
+describe('ReadJsonValue', () => {
+  describe('type definition', () => {
+    it('should have correct type structure for basic path', () => {
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: { name: 'John', age: 30 },
+          path: 'name'
+        }
+      }
+      
+      expect(value.type).toBe('read-json')
+      expect(value.arguments.json).toEqual({ name: 'John', age: 30 })
+      expect(value.arguments.path).toBe('name')
+    })
+
+    it('should support nested path access', () => {
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: {
+            txs: {
+              to: '0x596aF90CecdBF9A768886E771178fd5561dD27Ab',
+              data: '0x1234'
+            }
+          },
+          path: 'txs.data'
+        }
+      }
+      
+      expect(value.arguments.path).toBe('txs.data')
+    })
+
+    it('should support deeply nested path access', () => {
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: {
+            user: {
+              profile: {
+                personal: {
+                  name: 'Alice'
+                }
+              }
+            }
+          },
+          path: 'user.profile.personal.name'
+        }
+      }
+      
+      expect(value.arguments.path).toBe('user.profile.personal.name')
+    })
+
+    it('should support array index access', () => {
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: {
+            transactions: [
+              { hash: '0xabc123' },
+              { hash: '0xdef456' }
+            ]
+          },
+          path: 'transactions.0.hash'
+        }
+      }
+      
+      expect(value.arguments.path).toBe('transactions.0.hash')
+    })
+
+    it('should support template variables in json', () => {
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: '{{apiResponse}}',
+          path: 'result.data'
+        }
+      }
+      
+      expect(value.arguments.json).toBe('{{apiResponse}}')
+    })
+
+    it('should support template variables in path', () => {
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: { data: { field1: 'value1', field2: 'value2' } },
+          path: '{{fieldPath}}'
+        }
+      }
+      
+      expect(value.arguments.path).toBe('{{fieldPath}}')
+    })
+
+    it('should support both json and path as template variables', () => {
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: '{{responseData}}',
+          path: '{{extractionPath}}'
+        }
+      }
+      
+      expect(value.arguments.json).toBe('{{responseData}}')
+      expect(value.arguments.path).toBe('{{extractionPath}}')
+    })
+
+    it('should work with complex JSON structures', () => {
+      const complexJson = {
+        blockchain: {
+          ethereum: {
+            mainnet: {
+              contracts: {
+                erc20: [
+                  {
+                    address: '0xA0b86a33E6441e6e80D0c4C6C7527d72e1d7e4e1',
+                    symbol: 'USDC',
+                    decimals: 6
+                  },
+                  {
+                    address: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
+                    symbol: 'DAI',
+                    decimals: 18
+                  }
+                ]
+              }
+            }
+          }
+        }
+      }
+
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: complexJson,
+          path: 'blockchain.ethereum.mainnet.contracts.erc20.1.symbol'
+        }
+      }
+      
+      expect(value.arguments.json).toEqual(complexJson)
+      expect(value.arguments.path).toBe('blockchain.ethereum.mainnet.contracts.erc20.1.symbol')
+    })
+
+    it('should work with the example from the task description', () => {
+      const exampleJson = {
+        txs: {
+          to: '0x596aF90CecdBF9A768886E771178fd5561dD27Ab',
+          data: '0x1234'
+        }
+      }
+
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: exampleJson,
+          path: 'txs.data'
+        }
+      }
+      
+      expect(value.arguments.json).toEqual(exampleJson)
+      expect(value.arguments.path).toBe('txs.data')
+    })
+
+    it('should support root level access', () => {
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: 'simple string value',
+          path: ''
+        }
+      }
+      
+      expect(value.arguments.json).toBe('simple string value')
+      expect(value.arguments.path).toBe('')
+    })
+
+    it('should support accessing array elements directly', () => {
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: ['first', 'second', 'third'],
+          path: '1'
+        }
+      }
+      
+      expect(value.arguments.json).toEqual(['first', 'second', 'third'])
+      expect(value.arguments.path).toBe('1')
+    })
+
+    it('should support mixed object and array access', () => {
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: {
+            results: [
+              { id: 1, data: { value: 'first' } },
+              { id: 2, data: { value: 'second' } }
+            ]
+          },
+          path: 'results.0.data.value'
+        }
+      }
+      
+      expect(value.arguments.path).toBe('results.0.data.value')
+    })
+
+    it('should support boolean and number values in JSON', () => {
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: {
+            config: {
+              enabled: true,
+              maxRetries: 5,
+              timeout: 30.5
+            }
+          },
+          path: 'config.enabled'
+        }
+      }
+      
+      expect(value.arguments.json).toEqual({
+        config: {
+          enabled: true,
+          maxRetries: 5,
+          timeout: 30.5
+        }
+      })
+    })
+
+    it('should support null values in JSON', () => {
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: {
+            user: {
+              name: 'John',
+              avatar: null
+            }
+          },
+          path: 'user.avatar'
+        }
+      }
+      
+      expect(value.arguments.json.user.avatar).toBeNull()
+    })
+
+    it('should work with response from json-request action', () => {
+      // This simulates using the result of a json-request action
+      const value: ReadJsonValue = {
+        type: 'read-json',
+        arguments: {
+          json: '{{apiCall.response}}', // Reference to a json-request action output
+          path: 'data.transactions.0.hash'
+        }
+      }
+      
+      expect(value.arguments.json).toBe('{{apiCall.response}}')
+      expect(value.arguments.path).toBe('data.transactions.0.hash')
+    })
+  })
+})

package/src/lib/types/actions.ts

@@ -0,0 +1,127 @@
+import { AddressValue, BytesValue, Uint256Value, Value } from './values'
+import { Contract } from './contracts'
+import { Condition } from './conditions'
+
+// --- Primitive Actions ---
+// These are the basic building blocks that interact with the blockchain.
+
+export interface SendTransactionAction {
+  type: 'send-transaction';
+  arguments: {
+    to: AddressValue;
+    value?: Uint256Value;
+    data?: BytesValue;
+    gasMultiplier?: number;
+  };
+}
+
+export interface SendSignedTransactionAction {
+  type: 'send-signed-transaction';
+  arguments: {
+    transaction: BytesValue;
+  };
+}
+
+export interface VerifyContractAction {
+  type: 'verify-contract';
+  arguments: {
+    address: AddressValue;
+    contract: Value<Contract>; // The contract to verify
+    constructorArguments?: BytesValue; // Optional constructor args as hex string
+    platform?: Value<string | string[]>; // Platform(s) to verify on, defaults to "all" (tries all configured platforms)
+  };
+}
+
+export interface StaticAction {
+  type: 'static';
+  arguments: {
+    value: Value<any>;
+  };
+}
+
+export interface CreateContractAction {
+  type: 'create-contract';
+  arguments: {
+    data: BytesValue; // The contract bytecode (creation code)
+    value?: Uint256Value; // ETH to send with the contract creation
+    gasMultiplier?: number; // Optional gas multiplier
+  };
+}
+
+export interface TestNicksMethodAction {
+  type: 'test-nicks-method';
+  arguments: {
+    bytecode?: BytesValue;
+    gasPrice?: Uint256Value;
+    gasLimit?: Uint256Value;
+    fundingAmount?: Uint256Value;
+  };
+}
+
+export interface JsonRequestAction {
+  type: 'json-request';
+  arguments: {
+    url: Value<string>;
+    method?: Value<string>; // GET, POST, PUT, DELETE, etc. Defaults to GET
+    headers?: Value<Record<string, string>>; // Optional headers
+    body?: Value<any>; // JSON body for POST/PUT requests
+  };
+}
+
+// A union of all primitive action types.
+export type PrimitiveAction = SendTransactionAction | SendSignedTransactionAction | VerifyContractAction | StaticAction | CreateContractAction | TestNicksMethodAction | JsonRequestAction;
+
+const primitiveActionTypes = [
+  'send-transaction',
+  'send-signed-transaction',
+  'verify-contract',
+  'static',
+  'create-contract',
+  'test-nicks-method',
+  'json-request',
+] as const;
+
+/**
+ * A set of all built-in primitive action types.
+ * This is useful for efficiently checking if an action type is a primitive.
+ */
+export const PRIMITIVE_ACTION_TYPES = new Set<string>(primitiveActionTypes);
+
+/**
+ * A type guard to check if a given action `type` corresponds to a primitive action.
+ * @param type The action type string.
+ * @returns `true` if the type is a primitive action type.
+ */
+export function isPrimitiveActionType(type: string): type is (typeof primitiveActionTypes)[number] {
+  return PRIMITIVE_ACTION_TYPES.has(type);
+}
+
+// --- Template Call Action ---
+// In your YAML, using another template as an action is done by specifying its name
+// in the 'type' field (e.g., `type: 'min-balance'`). This type captures that pattern.
+
+export interface TemplateCallAction {
+  /**
+   * The name of the template to call, e.g., 'min-balance'.
+   * This property acts as a discriminator.
+   */
+  type: string;
+  arguments: Record<string, Value<any>>;
+}
+
+/**
+ * An Action is what appears in a `actions` array in your YAML.
+ * It's either a primitive action or a call to another template.
+ *
+ * The `type` field is used to discriminate. Your parser will need to have a list
+ * of known primitive action types (`send-transaction`, etc.) to distinguish them
+ * from template names.
+ */
+export type Action = (PrimitiveAction | TemplateCallAction) & {
+  /** An optional name for the action, allowing its outputs to be referenced. */
+  name?: string;
+  /** A list of conditions that, if any are met, will cause this action to be skipped. */
+  skip_condition?: Condition[];
+  /** A list of action names within the same job/template that must complete first. */
+  depends_on?: string[];
+};

package/src/lib/types/artifacts.ts

@@ -0,0 +1,21 @@
+export interface CompilerInfo {
+  version: string
+  // Future settings like optimizer runs can be added here
+}
+
+export interface Artifact {
+  // --- Core Information ---
+  contractName: string
+  abi: any[]
+  bytecode: string // aka creationCode, initCode
+
+  // --- Optional Information for Verification & Debugging ---
+  deployedBytecode?: string // aka runtimeBytecode
+  sourceName?: string       // e.g., "contracts/MyContract.sol"
+  source?: string           // The full source code content for verification
+  compiler?: CompilerInfo
+
+  // --- Internal Management Properties (added by the loader) ---
+  _path: string // The absolute path to the artifact file
+  _hash: string // A hash of the artifact file's content (e.g., MD5)
+}

package/src/lib/types/buildinfo.ts

@@ -0,0 +1,116 @@
+export interface BuildInfoSource {
+  content?: string
+  urls?: string[]
+  keccak256?: string
+}
+
+export interface BuildInfoInput {
+  language: string
+  sources: Record<string, BuildInfoSource>
+  settings: {
+    optimizer?: {
+      enabled: boolean
+      runs: number
+    }
+    evmVersion?: string
+    remappings?: string[]
+    viaIR?: boolean
+    libraries?: Record<string, Record<string, string>>
+    outputSelection: Record<string, Record<string, string[]>>
+    [key: string]: any
+  }
+}
+
+export interface BuildInfoError {
+  component?: string
+  errorCode?: string
+  formattedMessage?: string
+  message?: string
+  severity?: 'error' | 'warning' | 'info'
+  sourceLocation?: {
+    file: string
+    start: number
+    end: number
+  }
+  type?: string
+}
+
+export interface BuildInfoBytecode {
+  functionDebugData?: Record<string, any>
+  generatedSources?: any[]
+  linkReferences?: Record<string, Record<string, Array<{ length: number; start: number }>>>
+  object: string
+  opcodes?: string
+  sourceMap?: string
+}
+
+export interface BuildInfoContract {
+  abi: any[]
+  metadata?: string
+  storageLayout?: {
+    storage: Array<{
+      astId: number
+      contract: string
+      label: string
+      offset: number
+      slot: string
+      type: string
+    }>
+    types: Record<string, {
+      encoding: string
+      label: string
+      numberOfBytes: string
+      [key: string]: any
+    }>
+  }
+  userdoc?: any
+  devdoc?: any
+  ir?: string
+  irOptimized?: string
+  evm: {
+    assembly?: string
+    legacyAssembly?: any
+    bytecode: BuildInfoBytecode
+    deployedBytecode: BuildInfoBytecode
+    methodIdentifiers?: Record<string, string>
+    gasEstimates?: any
+  }
+}
+
+export interface BuildInfoOutput {
+  errors?: BuildInfoError[]
+  sources: Record<string, {
+    id: number
+    ast?: any
+  }>
+  contracts: Record<string, Record<string, BuildInfoContract>>
+}
+
+export interface BuildInfo {
+  _format?: 'hh-sol-build-info-1' | 'ethers-rs-sol-build-info-1' // Optional for factory-style formats
+  id: string
+  solcVersion: string
+  solcLongVersion?: string // Optional for factory-style formats
+  input: BuildInfoInput
+  output: BuildInfoOutput
+  // Optional extension keys for zkSync/zkEVM
+  zksolcVersion?: string
+  eraVersion?: string
+  zkevmVersion?: string
+  [key: string]: any // Allow additional unknown keys for forward compatibility
+}
+
+export interface ExtractedContract {
+  contractName: string
+  sourceName: string
+  fullyQualifiedName: string // e.g., "src/Counter.sol:Counter"
+  abi: any[]
+  bytecode: string
+  deployedBytecode?: string
+  source?: string
+  compiler: {
+    version: string
+  }
+  buildInfoId: string
+  buildInfoPath?: string
+} 

package/src/lib/types/conditions.ts

@@ -0,0 +1,50 @@
+import { AddressValue, BooleanValue } from './values'
+
+/**
+ * A condition that checks if a contract has code at a given address.
+ */
+export interface ContractExistsCondition {
+    type: 'contract-exists';
+    arguments: {
+        address: AddressValue;
+    };
+}
+
+export function isContractExistsCondition(obj: any): obj is ContractExistsCondition {
+    return (
+        obj &&
+        typeof obj === 'object' &&
+        obj.type === 'contract-exists' &&
+        obj.arguments &&
+        typeof obj.arguments === 'object' &&
+        'address' in obj.arguments
+    );
+}
+
+/**
+ * A condition that checks if a dependency job has been successfully completed.
+ */
+export interface JobCompletedCondition {
+    type: 'job-completed';
+    arguments: {
+        job: string;
+    };
+}
+
+export function isJobCompletedCondition(obj: any): obj is JobCompletedCondition {
+    return (
+        obj &&
+        typeof obj === 'object' &&
+        obj.type === 'job-completed' &&
+        obj.arguments &&
+        typeof obj.arguments === 'object' &&
+        typeof obj.arguments.job === 'string'
+    );
+}
+
+/**
+ * A condition is something that resolves to a boolean. It can be a specific
+ * check type like 'contract-exists', or any ValueResolver that produces a
+ * boolean result (e.g., `basic-arithmetic` with an 'eq' operation).
+ */
+export type Condition = BooleanValue | ContractExistsCondition | JobCompletedCondition;

package/src/lib/types/contracts.ts

@@ -0,0 +1,23 @@
+import { CompilerInfo } from './artifacts'
+
+export interface Contract {
+  // The ultimate, unambiguous identifier
+  uniqueHash: string
+
+  // Core Information - Only creationCode is truly required
+  creationCode: string
+  runtimeBytecode?: string
+  abi?: any[]
+
+  // Source Information
+  sourceName?: string // e.g., "contracts/MyToken.sol"
+  contractName?: string
+  source?: string // The full source code
+
+  // Compilation Information
+  compiler?: CompilerInfo
+  buildInfoId?: string // The ID from the build-info file it was found in
+
+  // Internal Management - tracks all file paths from which this contract's data was hydrated
+  _sources: Set<string>
+}

package/src/lib/types/definitions.ts

@@ -0,0 +1,68 @@
+import { Action } from './actions'
+import { Condition } from './conditions'
+import { Value } from './values'
+
+// --- Template Definition ---
+
+export interface TemplateArgument {
+    type: string; // e.g., 'address', 'bytes32', 'uint256'
+    description?: string;
+}
+
+export interface Template {
+    /** Optional discriminator to explicitly mark this document as a template */
+    type?: 'template';
+    name: string;
+    description?: string;
+    arguments?: Record<string, TemplateArgument>;
+    returns?: Record<string, TemplateArgument>;
+    setup?: {
+        skip_condition?: Condition[];
+        actions?: Action[];
+    };
+    actions: Action[];
+    skip_condition?: Condition[];
+    outputs?: Record<string, Value<any>>;
+    _path?: string; // Path to the template file for relative artifact resolution
+}
+
+// --- Job Definition ---
+
+export interface JobAction {
+    name: string; // Unique name for this action within the job
+    template?: string; // Name of the template to use (for template actions)
+    type?: string; // Type of primitive action (for primitive actions)
+    arguments: Record<string, Value<any>>;
+    skip_condition?: Condition[];
+    depends_on?: string[];
+    /**
+     * Output selection/override for this action when writing job outputs.
+     * - boolean: legacy flag. true marks the whole action for inclusion, false excludes.
+     * - object: custom output map. Keys become output keys under this action's name,
+     *           values are Value<any> that will be resolved at job time, overriding template outputs.
+     */
+    output?: boolean | Record<string, Value<any>>;
+}
+
+export interface Job {
+    name: string;
+    version: string;
+    description?: string;
+    depends_on?: string[]; // Names of other jobs this job depends on
+    actions: JobAction[];
+    only_networks?: number[]
+    skip_networks?: number[]
+    skip_condition?: Condition[];
+    constants?: Record<string, Value<any>>; // Optional job-level constants
+    deprecated?: boolean; // Optional flag to mark the job as deprecated
+    _path?: string; // Path to the job file for relative artifact resolution
+}
+
+// --- Constants Definition (top-level documents) ---
+
+export interface ConstantsDocument {
+    type: 'constants';
+    name?: string;
+    constants: Record<string, Value<any>>;
+    _path?: string; // Source file path
+}

package/src/lib/types/index.ts

@@ -0,0 +1,8 @@
+export * from './network'
+export * from './project'
+export * from './values'
+export * from './conditions'
+export * from './actions'
+export * from './definitions'
+export * from './artifacts'
+export * from './buildinfo'

package/src/lib/types/network.ts

@@ -0,0 +1,22 @@
+/**
+ * Represents a blockchain network configuration
+ */
+export interface Network {
+  /** The human-readable name of the network */
+  name: string
+  
+  /** The chain ID of the network */
+  chainId: number
+  
+  /** The RPC URL endpoint for the network */
+  rpcUrl: string
+
+  /** Supported verification platforms */
+  supports?: string[]
+
+  /** Optional gas limit to use for all transactions on this network */
+  gasLimit?: number
+  
+  /** Whether this is a test network */
+  testnet?: boolean
+}