@tokamak-zk-evm/synthesizer-node

File-based Node.js adapter for converting one Tokamak L2 transaction snapshot into circuit-ready JSON artifacts.

Install and run

npm install @tokamak-zk-evm/synthesizer-node
npx synthesizer tokamak-ch-tx \
  --previous-state ./L2StateChannel/previous_state_snapshot.json \
  --transaction ./L2StateChannel/transaction.json \
  --block-info ./L2StateChannel/block_info.json \
  --contract-code ./L2StateChannel/contract_codes.json

Use this package when inputs and outputs belong on the local filesystem. Use @tokamak-zk-evm/synthesizer-web for browser applications.

Required input files

The command accepts four explicit JSON file paths. The files must describe the same pre-transaction state and block context; their directory and filenames are otherwise application choices.

| File | Role | Format and owner | How to obtain it | Example | | ------------------------------ | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | previous_state_snapshot.json | Reconstructs state immediately before execution | tokamak-l2js StateSnapshot | Call TokamakL2StateManager.captureStateSnapshot() before executing the transaction | File | | transaction.json | Supplies the signed Tokamak L2 transaction | tokamak-l2js TxSnapshot | Call TokamakL2Tx.captureTxSnapshot() | File | | block_info.json | Supplies block-opcode and execution-environment values | Synthesizer BlockInfo JSON | Normalize the trusted application or L2 RPC block context | File | | contract_codes.json | Supplies deployed bytecode reached by the supported call flow | Synthesizer ContractCodeEntry[] JSON | Export deployment/state data or query the trusted state source | File |

StateSnapshot and TxSnapshot are defined by the tokamak-l2js version recorded in this package's buildMetadata. Use those exported types and capture methods instead of recreating compatibility interfaces.

File formats

previous_state_snapshot.json contains:

| Field | JSON shape | Meaning | | ------------------ | ---------------------------------------- | ---------------------------------------------- | | stateRoots | string[] | Tokamak state roots before execution | | storageAddresses | string[] | Storage-bearing contract addresses | | storageKeys | string[][] | Original storage-slot keys grouped by address | | storageTrieRoots | string[] | Ethereum storage-trie roots grouped by address | | storageTrieDb | { "key": string, "value": string }[][] | Trie records used to rebuild storage | | channelId | number | Tokamak L2 channel identifier |

The address-indexed arrays must stay aligned. storageKeys values are storage slots; storageTrieDb[*][*].key values are trie database keys.

transaction.json contains nonce, to, hex calldata in data, senderPubKey, and optional signature strings v, r, and s.

block_info.json contains 0x-prefixed coinBase, timeStamp, blockNumber, prevRanDao, gasLimit, chainId, selfBalance, and baseFee values plus the prevBlockHashes array.

contract_codes.json is an array of deployed bytecode entries:

[
  {
    "address": "0x...",
    "code": "0x..."
  }
]

Commands

npx synthesizer tokamak-ch-tx \
  --previous-state ./inputs/previous_state_snapshot.json \
  --transaction ./inputs/transaction.json \
  --block-info ./inputs/block_info.json \
  --contract-code ./inputs/contract_codes.json

# Include supplementary execution analysis
npx synthesizer tokamak-ch-tx \
  --previous-state ./inputs/previous_state_snapshot.json \
  --transaction ./inputs/transaction.json \
  --block-info ./inputs/block_info.json \
  --contract-code ./inputs/contract_codes.json \
  --output-supplement

Relative paths are resolved from the current working directory. The Synthesizer rejects incomplete or incoherent inputs rather than fetching missing state.

Outputs

By default, the command creates outputs/ under the detected application root, normally the current project root. The command prints each absolute output path as it writes the file.

| File | Purpose | | --------------------------- | ----------------------------------------------------- | | placementVariables.json | Placement subcircuit IDs, offsets, and witness values | | instance.json | Public and function-instance field values | | instance_description.json | Human-readable instance descriptions | | permutation.json | Wire-equality cycles used by preprocess and prove | | state_snapshot.json | Post-transaction tokamak-l2js StateSnapshot |

--output-supplement additionally writes execution steps, expanded placements, and observed message-code addresses under supplement/. Keep placementVariables.json, instance.json, and permutation.json from the same run.

Transaction support follows the shared Synthesizer boundary.

npm publication

| Item | Value | | ----------------- | ---------------------------------------------------------------------------------------------------- | | Package | @tokamak-zk-evm/synthesizer-node | | Published version | npm view @tokamak-zk-evm/synthesizer-node version | | Release notes | Repository CHANGELOG.md |

Security and application responsibilities

Validate that all four files came from the same trusted state source. Keep RPC credentials and signing keys out of input files, terminal history, outputs, and source control. Snapshots, witnesses, and execution logs may contain sensitive application data. Successful synthesis establishes artifact generation, not the security of the application, circuit library, setup, or surrounding protocol.

Project and license

• Source
• Issues
• Workspace overview

Dual-licensed under MIT OR Apache-2.0.