Project Template

interfold init makes a project from the default template (templates/default in the Interfold repository). This page is for developers who change that project. It describes what interfold init does, the folders and scripts of the project, its configuration, and the file to edit for each part. To run the template first, see the Quick Start.

What interfold init does

interfold init [PATH] [--template <URL>] [--skip-install] [--skip-cleanup]

Without --template, the command uses tag v<CLI version> of https://github.com/theinterfold/interfold.git. For CLI 0.18.0, the tag is v0.18.0. The command does these operations in sequence:

1. It makes a shallow clone of the repository in /tmp/__interfold-tmp-folder.1.
2. It copies the template to the project folder. In each package.json, it replaces the workspace versions of @interfold/contracts, @interfold/react, and @interfold/sdk with the versions of the cloned release. In each Cargo.toml, including the guest's, it replaces every path dependency on an Interfold crate (e3-program-runner, e3-bfv-client, e3-fhe-params, e3-compute-provider, e3-openvm-types, and e3-safe) with a Git dependency at the cloned commit.
3. It replaces .gitignore with .gitignore.bak, renames pnpm-workspace.yaml.bak to pnpm-workspace.yaml, and deletes lib/.
4. It runs git init.
5. It runs pnpm install, unless you give --skip-install.
6. It commits all files with the message Initial Commit.

interfold init does not run when the CLI finds an interfold.config.yaml in the current folder, in a parent folder, or in the default configuration folder. In that case, it stops with Cannot run `interfold init` when a configuration exists.

Layout

The template copier uses e3-fs, a small async filesystem adapter. Production copying uses the physical filesystem; tests can use the same operations over an in-memory root. That test seam does not make copying or replacement an atomic filesystem transaction.

The scripts make more folders when they run:

• .interfold/config/ and .interfold/data/: the ciphernode keys and databases.
• .interfold/noir/: bb and the circuits that interfold noir setup installs.
• .interfold/data-availability/: the output ciphertexts that the coordination server serves.
• .interfold/caches/openvm/: the guest build, its proving keys, the receipt identity, and the worker configuration that interfold program compile writes.
• types/, artifacts/, and cache/: the Hardhat and TypeChain output.
• target/: the Cargo output.

The .gitignore of the project ignores .interfold/, artifacts/, cache/, target/, node_modules, and .env files.

Scripts

package.json in the project root defines these scripts. Run a script with pnpm run <name>, for example pnpm run dev:all. The other pages use the short form, for example pnpm dev:all.

The client package (client/package.json) has its own scripts: dev (vite --no-open --host), build, preview, format, and format:check.

interfold.config.yaml

interfold.config.yaml configures the local chain, the program mode, and the local ciphernodes. The CLI reads it from the current folder or from a parent folder. The template file has this structure. The contract addresses, the deploy blocks, and the node addresses are placeholders here. The deploy script writes the contract values.

chains:
  - name: 'localhost'
    rpc_url: 'ws://localhost:8545'
    ingestion_confirmations: 0
    rpc_poll_interval_ms: 250
    data_availability:
      mode: mock_http
      rpc_url: http://127.0.0.1:8080/availability
    contracts:
      e3_program:
        address: '<address>'
        deploy_block: <block>
      interfold:
        address: '<address>'
        deploy_block: <block>
      # ciphernode_registry, bonding_registry, slashing_manager, and fee_token
      # have the same two keys.
program:
  dev: false
nodes:
  cn1:
    address: '<Anvil account 1>'
    quic_port: 9201
    ctrl_port: 50501
    autonetkey: true
    autopassword: true
    dashboard_port: 8004
  cn2:
    address: '<Anvil account 2>'
    quic_port: 9202
    ctrl_port: 50502
    autonetkey: true
    autopassword: true
  # cn3, cn4, and cn5 follow the same pattern (ports 9203 to 9205 and 50503 to 50505).

interfold program compile and interfold program start also accept --dev true or --dev false. The flag overrides program.dev for that one command. The local scripts load scripts/lib/dev_config.sh, which sets E3_PROGRAM__DEV=true and TEMPLATE_UNPROVED_TEST=1 unless TEMPLATE_REAL_PROOFS=1. TEMPLATE_UNPROVED_TEST=1 makes deployTemplate deploy MockOpenVmReceiptVerifier, and it works only on chain ID 31337.

The CLI keeps the node data next to this file: keys in .interfold/config/<node>, databases in .interfold/data/<node>, and the prover files in .interfold/noir/. An environment variable with the E3_ prefix overrides a key. Two underscores separate the levels, for example E3_NODES__CN1__SKIP_PROOF_AGGREGATION=true. For every key, see the configuration reference.

Environment variables

The template ships no .env files. The scripts set the environment when they start each process.

Client. scripts/dev_frontend.sh exports the output of interfold print-env --vite --chain localhost. If a required variable is missing, the client shows Environment Configuration Required. You can also set these variables in client/.env.

Coordination server. scripts/dev_server.sh sets PRIVATE_KEY (Anvil account 0), CHAIN_ID=31337, and the output of interfold print-env --chain localhost: INTERFOLD_ADDRESS, RPC_URL, REGISTRY_ADDRESS, BONDING_REGISTRY_ADDRESS, E3_PROGRAM_ADDRESS, and FEE_TOKEN_ADDRESS. Then it sets RPC_URL=http://localhost:8545. These optional variables have defaults:

Hardhat. hardhat.config.ts loads a .env file from the project root. It reads MNEMONIC (default: the Anvil test mnemonic), PRIVATE_KEY, RPC_URL, and block explorer API keys, for example ETHERSCAN_API_KEY.

Dev scripts. scripts/lib/dev_config.sh reads BFV_PRESET (insecure-64 or secure-8192, default insecure-64) and COMMITTEE (default minimum). These variables have an effect only when the template is inside an Interfold repository checkout, where the scripts build the circuits. scripts/anvil-automine.mjs reads ANVIL_RPC_URL (default http://127.0.0.1:8545).

Where to change things

Change the ciphernode set

scripts/dev_ciphernodes.sh has one private key per node (PRIVATE_KEY_CN1 to PRIVATE_KEY_CN5). It reads each node address from interfold.config.yaml, expects five nodes to start (EXPECTED_NODES=5), and registers each address with ciphernode:admin-add. To add or remove a node, change all of these items together with the nodes section of interfold.config.yaml.

Next steps