From d6af08a7ae4812df60b4d7951840aabc8adb9d6a Mon Sep 17 00:00:00 2001 From: Hamza Khalid Date: Sat, 26 Sep 2026 18:34:08 +0500 Subject: [PATCH] chore(docs): add CLI, configuration, contracts, and glossary pages Add the Reference section: - cli: every interfold and interfoldup command and flag, from the clap definitions, checked against the 0.18.0 binary. - configuration: every config key with its type and default, the file discovery order, and E3_* overrides. - contracts: mainnet and Sepolia addresses from deployments/ manifest.json, the live mainnet verifiers with their history, enums, and key events. - glossary: about 70 protocol terms with anchors. Register reference/contracts.mdx as an address consumer, and allow the live mainnet verifier addresses (and the image-ID prefix that the address pattern matches) in scripts/check-addresses.ts. Point the docs MCP fallback list and llms.txt at the new paths. --- docs/pages/_meta.json | 3 + docs/pages/reference/_meta.json | 14 + docs/pages/reference/cli.mdx | 746 +++++++++++++++++++++++++ docs/pages/reference/configuration.mdx | 507 +++++++++++++++++ docs/pages/reference/contracts.mdx | 335 +++++++++++ docs/pages/reference/glossary.mdx | 419 ++++++++++++++ docs/public/llms.txt | 62 +- packages/interfold-mcp/src/index.ts | 68 ++- scripts/check-addresses.ts | 10 +- 9 files changed, 2116 insertions(+), 48 deletions(-) create mode 100644 docs/pages/reference/_meta.json create mode 100644 docs/pages/reference/cli.mdx create mode 100644 docs/pages/reference/configuration.mdx create mode 100644 docs/pages/reference/contracts.mdx create mode 100644 docs/pages/reference/glossary.mdx diff --git a/docs/pages/_meta.json b/docs/pages/_meta.json index 82b3b4f845..0969d7a053 100644 --- a/docs/pages/_meta.json +++ b/docs/pages/_meta.json @@ -24,6 +24,9 @@ "internals": { "title": "Protocol Internals" }, + "reference": { + "title": "Reference" + }, "-- FOLD & Governance": { "type": "separator", "title": "FOLD & Governance" diff --git a/docs/pages/reference/_meta.json b/docs/pages/reference/_meta.json new file mode 100644 index 0000000000..b67013b73e --- /dev/null +++ b/docs/pages/reference/_meta.json @@ -0,0 +1,14 @@ +{ + "cli": { + "title": "CLI" + }, + "configuration": { + "title": "Node Configuration" + }, + "contracts": { + "title": "Contracts & Addresses" + }, + "glossary": { + "title": "Glossary" + } +} diff --git a/docs/pages/reference/cli.mdx b/docs/pages/reference/cli.mdx new file mode 100644 index 0000000000..b0db107d7c --- /dev/null +++ b/docs/pages/reference/cli.mdx @@ -0,0 +1,746 @@ +--- +title: 'CLI Reference' +description: + 'Every interfold and interfoldup command, with its flags, default values, and behavior, grouped by + task.' +--- + +import { Callout } from 'nextra/components' +import { Badge, LinkCard, LinkCards } from '@/components/ui' + +# CLI Reference + +This page lists every command of the `interfold` CLI and the `interfoldup` installer in release +0.18.0. It is for developers who build E3 programs and for operators who run ciphernodes. Each entry +gives the purpose, the usage line, and a table of flags with their default values. The source of +truth is the clap definitions in `crates/cli/src` and `crates/interfoldup/src/main.rs`. + +## Commands at a glance + +| Task | Commands | +| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Install and update](#install-and-update) | `interfoldup install`, `interfoldup update`, `interfoldup uninstall` | +| [Project](#project-commands) | `init`, `compile`, `program`, `print-env` | +| [Node](#node-commands) | `ciphernode setup`, `start`, `nodes`, `noir`, `events query`, `config get` | +| [Operator on-chain lifecycle](#operator-on-chain-lifecycle) | `ciphernode set-bond-owner`, `propose-bond-owner`, `accept-bond-owner`, `bond`, `tickets`, `register`, `deregister`, `activate`, `deactivate`, `status`, `faucet` | +| [Keys and secrets](#keys-and-secrets) | `password set`, `password delete`, `wallet set`, `wallet get` | +| [Network](#network-commands) | `net get-peer-id` | +| [Maintenance](#maintenance-commands) | `node validate`, `node reset-data`, `config check`, `rev`, `purge-all` | + +Run `interfold --help` to print the help text of one command. Run `interfold --version` to +print the release version. + +## Global options + +These options apply to every `interfold` command. You can put them before or after the command name. + +| Flag | Value | Default | Description | +| ----------------- | ---------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `-c`, `--config` | `` | [Discovery order](/reference/configuration#config-file-location) | Path to the configuration file. A relative path starts from the current directory. | +| `-v`, `--verbose` | Count | `WARN` | Increases the log level. `-v` is `INFO`, `-vv` is `DEBUG`, and `-vvv` is `TRACE`. | +| `-q`, `--quiet` | None | Off | Shows errors only. You cannot use it together with `-v`. | +| `--name` | `` | `_default` | Selects the node profile `nodes.`. The name `_default` selects the `node` key. Logs and telemetry use this name. | +| `--otel` | `` | None | OpenTelemetry collector gRPC endpoint, for example `http://localhost:4317`. The value must be a valid URL. | +| `-h`, `--help` | None | None | Prints help. | +| `-V`, `--version` | None | None | Prints the version. This flag is available on `interfold` only, not on subcommands. | + +The node profile also sets the storage paths. Each profile keeps its keys and data in folders named +after the profile. See [storage paths](/reference/configuration#storage-paths). + +## Behavior common to all commands + +### Configuration file + +Most commands need a configuration file. The CLI looks for the file in the order that +[Node Configuration](/reference/configuration#config-file-location) describes. When the CLI finds no +file, only these commands run: + +| Command | Behavior without a configuration file | +| --------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `init` | Makes a project. | +| `rev` | Prints the build revision. | +| `ciphernode setup` | Writes a configuration file and stores the password and wallet key. | +| `start` | Runs `ciphernode setup` with the `sepolia` profile and stops. Run `interfold start` again to start the node. | +| `noir status`, `noir setup` | Use the folder `~/.interfold/noir`. | + +All other commands stop with this error: + +```text +Configuration file not found. Run `interfold ciphernode setup` to create a configuration. +``` + +`init` and `ciphernode setup` do the opposite. They stop with an error when the CLI finds a +configuration file. + +When the configuration sets `autopassword: true` or `autowallet: true`, every command that loads the +file first creates a missing password or wallet key. See +[node keys](/reference/configuration#node-keys). + +### Commands that run inside a running node + +`interfold start` opens a control port on `127.0.0.1` at `ctrl_port` (default `50505`). Before a +command runs, the CLI sends a request to that port and waits up to 1 second. When a node answers, +these read-only commands run inside that node and print its answer: + +- `config get` +- `ciphernode status` +- `events query` +- `net get-peer-id` +- `noir status` +- `print-env` +- `rev` (without `--features`) +- `wallet get` + +All other commands run in the local process. + +### Exit status + +A command that fails prints the error in red and exits with status `1`. + +## Install and update + +### Install script + +The `install` script at the repository root installs `interfoldup` in `~/.local/bin`. It supports +Linux on `x86_64` and `aarch64`, and macOS. On an Intel Mac, it installs the Apple Silicon build, +which runs through Rosetta 2. + +```bash +curl -fsSL https://raw.githubusercontent.com/theinterfold/interfold/main/install | bash +``` + +| Flag | Value | Default | Description | +| -------------- | ------- | -------------- | -------------------------------------------------------------------------------------------------- | +| `--version` | `` | Latest release | Release tag of `interfoldup` to install, for example `v0.18.0`. A tag without `v` gets the prefix. | +| `-h`, `--help` | None | None | Prints the usage text. | + +The environment variable `INTERFOLDUP_VERSION` sets the same value as `--version`. To pass the flag +through the pipe, give it to `bash -s --`: + +```bash +curl -fsSL https://raw.githubusercontent.com/theinterfold/interfold/main/install | bash -s -- --version v0.18.0 +``` + +### `interfoldup install` + +Downloads the `interfold` binary for this platform from a GitHub release and installs it. + +```bash +interfoldup install [--system] [--version ] +``` + +| Flag | Value | Default | Description | +| ----------- | ------- | -------------- | ------------------------------------------------------------------- | +| `--system` | None | Off | Installs to `/usr/local/bin` instead of `~/.local/bin`. | +| `--version` | `` | Latest release | Release tag to install. The command accepts `0.18.0` and `v0.18.0`. | + +The command prints a warning when the install folder is not in `PATH`. + +### `interfoldup update` + +Replaces the installed binary with the requested release. When no binary is installed, the command +runs `install`. When the installed version already matches, the command does nothing. + +```bash +interfoldup update [--system] [--version ] +``` + +| Flag | Value | Default | Description | +| ----------- | ------- | -------------- | ----------------------------------------------------------------------- | +| `--system` | None | Off | Updates `/usr/local/bin/interfold` instead of `~/.local/bin/interfold`. | +| `--version` | `` | Latest release | Release tag to move to. | + +### `interfoldup uninstall` + +Removes the installed `interfold` binary. It does not remove configuration files or node data. + +```bash +interfoldup uninstall [--system] +``` + +| Flag | Value | Default | Description | +| ---------- | ----- | ------- | -------------------------------------------------------- | +| `--system` | None | Off | Removes from `/usr/local/bin` instead of `~/.local/bin`. | + +## Project commands + +These commands make and run an E3 project from the template. For a walkthrough, see +[Quick Start](/build/quick-start). + +### `interfold init` + +Makes a new Interfold project from a template. The command clones the template, copies the support +scripts to `.interfold/support`, adds the `lib/risc0-ethereum` submodule, runs `pnpm install`, and +makes the first Git commit. It needs `git` and `pnpm`. + +```bash +interfold init [PATH] [--template