Relevant source files

The following files were used as context for generating this wiki page: - [src/cli/commands/bootstrap/bootstrap.command.ts](https://github.com/settlemint/network-bootstrapper/blob/main/src/cli/commands/bootstrap/bootstrap.command.ts) - [src/cli/commands/bootstrap/bootstrap.output.ts](https://github.com/settlemint/network-bootstrapper/blob/main/src/cli/commands/bootstrap/bootstrap.output.ts) - [src/cli/commands/compile-genesis/compile-genesis.command.ts](https://github.com/settlemint/network-bootstrapper/blob/main/src/cli/commands/compile-genesis/compile-genesis.command.ts) - [src/cli/commands/download-abi/download-abi.command.ts](https://github.com/settlemint/network-bootstrapper/blob/main/src/cli/commands/download-abi/download-abi.command.ts) - [src/genesis/besu-genesis.service.ts](https://github.com/settlemint/network-bootstrapper/blob/main/src/genesis/besu-genesis.service.ts) - [src/index.ts](https://github.com/settlemint/network-bootstrapper/blob/main/src/index.ts) - [tools/version.ts](https://github.com/settlemint/network-bootstrapper/blob/main/tools/version.ts) - [package.json](https://github.com/settlemint/network-bootstrapper/blob/main/package.json) - [scripts/docs-cli.sh](https://github.com/settlemint/network-bootstrapper/blob/main/scripts/docs-cli.sh)

# Architectural Overview The `network-bootstrapper` is a command-line interface (CLI) tool built with TypeScript and Bun for generating configurations for Besu-based blockchain networks. Its primary purpose is to automate the creation of essential network artifacts, including node keys, a `genesis.json` file, and `static-nodes.json`. The tool is designed with a strong emphasis on Kubernetes integration, enabling it to directly create `ConfigMap` and `Secret` resources within a cluster, streamlining the deployment of blockchain nodes. The architecture is modular, separating concerns like key generation, genesis configuration, CLI command handling, and output formatting. It uses a combination of interactive prompts and command-line flags to gather configuration parameters, making it flexible for both manual and automated execution environments. The tool leverages modern libraries such as `commander` for the CLI structure, `@inquirer/prompts` for user interaction, and `@kubernetes/client-node` for its robust Kubernetes integration. ## Core Components & Technologies The project is built upon a modern TypeScript and Bun stack. The key dependencies define its core capabilities. | Technology / Library | Role | Source - | Bun | TypeScript runtime, bundler, test runner, and package manager. | [CLAUDE.md]() - | TypeScript | The primary programming language, providing static typing. | [package.json:42-42]() - | Commander.js | Framework for building the command-line interface. | [package.json:47-47]() - | @kubernetes/client-node | Library for interacting with the Kubernetes API to manage resources. | [package.json:46-46]() - | viem | Used for cryptographic operations, such as generating Ethereum keys and addresses. | [package.json:51-51]() - | @inquirer/prompts | Powers the interactive prompts for gathering user input when CLI flags are not provided. | [package.json:45-45]() - Sources: [package.json](), [CLAUDE.md]() ## Project Structure The repository follows a standard structure for a TypeScript project, with distinct modules for different functionalities. ```mermaid graph TD A[network-bootstrapper] --> B[src] A --> C[scripts] A --> D[tools] A --> E[charts] A --> F[package.json] B --> B1[cli] B --> B2[genesis] B --> B3[keys] B --> B4[constants] B --> B5[index.ts] B1 --> B1a[commands] C --> C1[docs-cli.sh] D --> D1[version.ts] ``` This diagram shows the high-level directory structure. - **`src/`**: Contains all the main TypeScript source code. - **`cli/`**: Manages the command-line interface, including command definitions and argument parsing. - **`genesis/`**: Responsible for constructing the `genesis.json` file. - **`keys/`**: Handles the generation of cryptographic keys for nodes. - **`index.ts`**: The main entry point of the application. - **`scripts/`**: Holds utility shell scripts, such as for generating CLI documentation. - **`tools/`**: Contains build-related TypeScript scripts, like the versioning script. - **`charts/`**: Helm charts for deploying the network. - **`package.json`**: Defines project metadata, dependencies, and scripts. Sources: [CLAUDE.md](), [AGENTS.md]() ## Command-Line Interface (CLI) The CLI is the user's primary interaction point with the tool. It is built using `commander.js` and exposes several commands to handle different stages of network configuration. The main entry point `src/index.ts` initializes the `commander` program and registers the subcommands. ```typescript // src/index.ts:10-14 #!/usr/bin/env bun import { createCliCommand } from "./cli/commands/bootstrap/bootstrap.command.ts"; const command = createCliCommand(); await command.parseAsync(Bun.argv); ``` Sources: [src/index.ts:10-14]() ### Command Hierarchy The tool organizes its functionality into a hierarchy of commands. ```mermaid graph TD subgraph CLI A[network-bootstrapper] --> B[generate] A --> C[compile-genesis] A --> D[download-abi] end ``` This diagram illustrates the main commands available. | Command | Description | Source File - | `generate` | The core command. Generates node keys, a genesis file, and other artifacts based on user input. | [src/cli/commands/bootstrap/bootstrap.command.ts:405-411]() - | `compile-genesis` | Merges a base genesis ConfigMap with allocation ConfigMaps to produce a complete, single genesis file. | [src/cli/commands/bootstrap/bootstrap.command.ts:553-554]() - | `download-abi` | Downloads ABI files from annotated ConfigMaps in a Kubernetes cluster to a local directory. | [src/cli/commands/download-abi/download-abi.command.ts:168-172]() - The `docs:cli` script in `package.json` uses `scripts/docs-cli.sh` to automatically generate help text for each command and append it to the main `README.md` file, ensuring documentation stays in sync with the CLI's surface area. Sources: [src/cli/commands/bootstrap/bootstrap.command.ts:553-555](), [scripts/docs-cli.sh:23-27](), [package.json:28-28]() ## `generate` Command Workflow The `generate` command is the core of the bootstrapper. It orchestrates the entire process of creating network artifacts from user-provided parameters or interactive prompts. This flowchart shows the logical flow of the `generate` command. ```mermaid flowchart TD A[Start `generate` command] --> B{Parse CLI Options}; B --> C{Accept Defaults?}; C -- No --> D[Prompt for missing values]; C -- Yes --> E[Use default values]; D --> E; E --> F[Generate Validator & Faucet Keys]; F --> G[Create Static Node Entries]; G --> H{Allocations file provided?}; H -- Yes --> I[Load Allocation Overrides]; H -- No --> J; I --> J; J --> K{ABI directory provided?}; K -- Yes --> L[Load ABI Artifacts]; K -- No --> M; L --> M; M --> N{Subgraph hash file provided?}; N -- Yes --> O[Load Subgraph Hash]; N -- No --> P; O --> P; P --> Q[Generate Besu Genesis JSON]; Q --> R[Construct OutputPayload]; R --> S{Output Type?}; S -- screen --> T[Print to STDOUT]; S -- file --> U[Write to files in `out/`]; S -- kubernetes --> V[Create K8s ConfigMaps & Secrets]; ``` Sources: [src/cli/commands/bootstrap/bootstrap.command.ts:241-360]() ### Key Generation The `NodeKeyFactory` is used to generate secp256k1 key pairs for validators and the faucet account. Sources: [src/cli/commands/bootstrap/bootstrap.command.ts:241-360]() ### Genesis Configuration The `BesuGenesisService` is responsible for assembling the `genesis.json` file. It takes parameters like the consensus algorithm, chain ID, block period, and initial account allocations. Sources: [src/genesis/besu-genesis.service.ts]() ### Static Node Generation The tool constructs `enode://` URIs for each validator. These URIs are crucial for peer discovery. The hostnames are formatted to align with Kubernetes StatefulSet pod naming conventions (e.g., `-...`). Sources: [src/cli/commands/bootstrap/bootstrap.command.ts:187-239]() ### Output Payload After all artifacts are generated in memory, they are bundled into a single `OutputPayload` object, which is then passed to the output handler. ```typescript // src/cli/commands/bootstrap/bootstrap.output.ts:40-49 type OutputPayload = { faucet: GeneratedNodeKey; genesis: BesuGenesis; validators: readonly IndexedNode[]; staticNodes: readonly string[]; artifactNames: ArtifactNames; abiArtifacts: readonly AbiArtifact[]; subgraphHash?: string; }; ``` Sources: [src/cli/commands/bootstrap/bootstrap.output.ts:40-49]() ## Output Handling The `outputResult` function in `bootstrap.output.ts` directs the generated artifacts to one of three destinations based on the `--outputType` flag. ```mermaid graph TD A[outputResult(type, payload)] --> B{Switch on type}; B -- "screen" --> C[outputToScreen(payload)]; B -- "file" --> D[outputToFile(payload)]; B -- "kubernetes" --> E[outputToKubernetes(payload)]; ``` This diagram shows the branching logic for handling different output types. ### Screen Output Prints a summary of the generated genesis file, validator nodes, static nodes, and faucet account directly to the console. This is the default behavior and is useful for quick inspection. Sources: [src/cli/commands/bootstrap/bootstrap.output.ts:145-151]() ### File Output Writes all generated artifacts as individual JSON files into a new, timestamped subdirectory within the `out/` directory. This is ideal for local development or for committing artifacts to a repository. Sources: [src/cli/commands/bootstrap/bootstrap.output.ts:172-231]() ### Kubernetes Output Directly creates Kubernetes resources (`ConfigMap` and `Secret`) in the cluster where the command is run. This is the most powerful feature for automated deployments. It intelligently splits large genesis files to stay within Kubernetes resource size limits. Sources: [src/cli/commands/bootstrap/bootstrap.output.ts:233-303]() ## Kubernetes Integration The bootstrapper is deeply integrated with Kubernetes, treating it as a first-class deployment target. This integration is handled by functions in `kubernetes.client.ts` and orchestrated by the output and subcommand modules. ### Resource Creation (`generate` command) When using `outputType: kubernetes`, the `generate` command creates several resources. This sequence diagram shows the flow of creating Kubernetes resources. ```mermaid sequenceDiagram participant CLI as "generate command" participant K8sClient as "KubernetesClient" participant K8sAPI as "Kubernetes API" CLI->>K8sClient: createKubernetesClient() K8sClient-->>CLI: context (client, namespace) Note over CLI: Prepares ConfigMap & Secret specs CLI->>K8sClient: createConfigMap(spec) K8sClient->>K8sAPI: POST /api/v1/namespaces/{ns}/configmaps K8sAPI-->>K8sClient: Response K8sClient-->>CLI: Success/Failure CLI->>K8sClient: createSecret(spec) K8sClient->>K8sAPI: POST /api/v1/namespaces/{ns}/secrets K8sAPI-->>K8sClient: Response K8sClient-->>CLI: Success/Failure ``` A key architectural decision is the handling of the `genesis.alloc` section. To avoid creating a single massive `ConfigMap` that could exceed Kubernetes's 1MB limit, the tool creates: 1. A "sparse" genesis `ConfigMap` containing all configuration but only the faucet's balance in the `alloc` block. Other accounts are given a `balance` of `0x0`. 2. A separate `ConfigMap` for each additional pre-funded account, named `alloc-

`. These are annotated with `settlemint.com/artifact: alloc`. This allows a separate `compile-genesis` process to reassemble the full genesis file within the cluster. Sources: [src/cli/commands/bootstrap/bootstrap.output.ts:77-96](), [src/cli/commands/bootstrap/bootstrap.output.ts:245-253]() ### Resource Consumption (`download-abi` and `compile-genesis`) Other commands consume resources created by `generate`: - **`download-abi`**: Lists all `ConfigMap`s in a namespace, filters for those with the `settlemint.com/artifact: abi` annotation, and writes their contents to a local directory. It includes logic for pagination, retries on rate limiting, and handling of expired resource snapshots from the Kubernetes API. - **`compile-genesis`**: Reads the sparse genesis `ConfigMap` and all `alloc-*` `ConfigMap`s, then merges them to reconstruct the complete `genesis.json` file locally. This is typically run in an init container. Sources: [src/cli/commands/download-abi/download-abi.command.ts:133-201](), [src/cli/commands/compile-genesis/compile-genesis.command.test.ts:110-136]() ## Build and Versioning The project uses a sophisticated versioning script, `tools/version.ts`, to manage application and Helm chart versions. - **Version Generation**: The script determines the version string based on the Git context (`GITHUB_REF_SLUG`, `GITHUB_REF_NAME`). - **Release Tag (e.g., `v1.2.3`):** Uses the tag as the version (e.g., `1.2.3`). - **`main` branch:** Appends a pre-release identifier, like `1.2.3-main.12345`. - **Pull Request branch:** Appends a PR identifier, like `1.2.3-pr.12345`. - **File Updates**: The script automatically updates the `version` and `appVersion` fields in all `package.json` and `charts/**/Chart.yaml` files. - **CI/CD Integration**: It exports the generated version and tag to `GITHUB_OUTPUT` and `GITHUB_ENV`, making them available for subsequent steps in a GitHub Actions workflow. This ensures that all artifacts (NPM package, container images, Helm charts) are consistently versioned based on the state of the source code. Sources: [tools/version.ts:130-161](), [tools/version.ts:409-421]()