index.ts

Overview

The `index.ts` file serves as the Pulumi deployment entrypoint script for the **Arbitrum Nova** coinstack within the Unchained multi-blockchain infrastructure. Its primary responsibility is to orchestrate the deployment of blockchain node services — specifically the **daemon node** and **indexer service** — into a Kubernetes cluster using Pulumi infrastructure-as-code.

This script dynamically reads service configurations from environment and JSON files, adapts service-specific deployment parameters (such as ports, environment variables, probes, and volume mounts), and invokes a shared deployment utility (`deployCoinstack`) which manages the actual provisioning of Kubernetes resources.

Detailed Explanation

Exported Function (default async export)

export = async (): Promise<Outputs> => { ... }

• Purpose:
  As the Pulumi entrypoint, this async function prepares deployment parameters and triggers the coinstack deployment process.

• Returns:
  A Promise resolving to Outputs — the deployment result object defined in the Pulumi types, typically including references to created Kubernetes resources and service endpoints.

• Function Workflow:

  1. Define constants:

     • appName: Static string "unchained", representing the overarching application or deployment name.

     • coinstack: "arbitrum-nova", identifying the blockchain coinstack being deployed.

  2. Read environment file:
     Reads the contents of ../sample.env into sampleEnv (a Buffer) which can be injected into the deployment for environment variable configuration.

  3. Fetch Kubernetes configuration:
     Calls getConfig() to asynchronously retrieve:

     • kubeconfig: Kubernetes cluster connection config.

     • config: JSON configuration object, expected to include statefulService with a list of service definitions.

     • namespace: Kubernetes namespace string to deploy into.

  4. Map configured services to CoinServiceArgs:
     Iterates over each service declared in config.statefulService?.services and generates deployment parameters based on the service name:

     • For daemon service:
       Extends the base config with:

       • Ports:

         • HTTP RPC on port 8547

         • WebSocket RPC on port 8548 with path prefix /websocket (and path prefix stripping enabled)

       • Environment variables for L1 Ethereum RPC and Beacon endpoints, targeting internal Kubernetes service URLs.

       • ConfigMap data including:

         • jwt.hex (a JWT authentication token file read from ../daemon/jwt.hex)

         • evm.sh (a shell script read from ../../../scripts/evm.sh)

       • Volume mounts to inject these config files into the container filesystem.

       • Kubernetes health probes: startup, liveness, and readiness with specific timing parameters.

     • For indexer service:
       Extends the base config by merging default Blockbook service arguments (defaultBlockbookServiceArgs) and adding a ConfigMap containing an indexer config JSON (read from ../indexer/config.json).

     • For any other service:
       Throws an error indicating unsupported service types.

  5. Deploy the coinstack:
     Calls deployCoinstack() with the assembled parameters:

     • appName, coinstack, coinstackType (fixed to 'node'), config, kubeconfig, namespace, sampleEnv, and the constructed coinServiceArgs.

  6. Return the deployment outputs.

Important Types and Imports

• deployCoinstack
  Imported from the shared Pulumi coinstack library. This function encapsulates the logic to create Kubernetes StatefulSets, Services, ConfigMaps, and IngressRoutes for the given coin services.

• Outputs
  Type representing the deployment output structure returned by deployCoinstack.

• CoinServiceArgs
  Interface describing arguments needed to deploy a service: ports, environment variables, ConfigMaps, volume mounts, probes, etc.

• getConfig
  Asynchronously fetches Kubernetes context, configuration, and namespace for deployment.

• defaultBlockbookServiceArgs
  Default deployment arguments for Blockbook-based indexer services (ports, probes, etc.), imported from a shared constants file.

Usage Example

This file is intended to be executed by Pulumi CLI as the deployment entrypoint for the Arbitrum Nova coinstack:

pulumi up --cwd path/to/arbitrum-nova/pulumi

Pulumi will run this script, which:

• Reads configs and env files,

• Prepares deployment arguments for daemon and indexer services,

• Deploys the services into Kubernetes,

• Returns deployment outputs.

Implementation Details and Algorithms

• Service Configuration Mapping:
  The script dynamically maps service definitions in the configuration JSON to deployment arguments. It uses a switch statement keyed on the service name, allowing specific customization for each service type.

• Deployment Parameters:
  Each service is configured with Kubernetes health probes (startup, liveness, readiness) with tailored timing to ensure proper pod health monitoring and restart policies.

• ConfigMap Injection:
  Sensitive and operational files (jwt.hex, evm.sh, indexer-config.json) are injected into pods via Kubernetes ConfigMaps and volume mounts, decoupling configuration from container images.

• Internal Service URLs:
  Environment variables use Kubernetes internal DNS names (e.g., ethereum-svc.unchained.svc.cluster.local) to enable inter-service communication within the cluster.

• Error Handling:
  Unsupported services explicitly throw errors, preventing silent misconfigurations.

Interaction with Other System Components

• Pulumi Core Libraries:
  Uses shared Pulumi deployment utilities (deployCoinstack, types, and config functions) to unify deployment logic across coinstacks.

• Kubernetes Cluster:
  Deploys resources into a cluster referenced by the retrieved kubeconfig and namespace.

• Filesystem:
  Reads environment and configuration files (sample.env, jwt.hex, evm.sh, indexer/config.json) from relative paths on disk to supply necessary configuration content.

• Blockbook Package:
  Utilizes default Blockbook constants for indexer service deployment parameters.

• Other Coinstacks:
  This file follows the same deployment pattern established for other coinstacks (e.g., Litecoin, Ethereum), enabling consistent multi-chain deployment management.

Mermaid Diagram: Flowchart of index.ts Deployment Workflow

flowchart TD
  A[Start Deployment Function] --> B[Read sample.env File]
  B --> C[Call getConfig() to Retrieve kubeconfig, config, namespace]
  C --> D{For Each Service in config.statefulService.services}
  D -->|daemon| E[Configure daemon Service Args]
  D -->|indexer| F[Configure indexer Service Args]
  D -->|other| G[Throw Unsupported Service Error]
  E --> H[Assemble coinServiceArgs Array]
  F --> H
  G --> I[Abort Deployment]
  H --> J[Call deployCoinstack() with Parameters]
  J --> K[Deploy Kubernetes Resources]
  K --> L[Return Deployment Outputs]

Summary

This `index.ts` file is a crucial automation script for deploying the Arbitrum Nova blockchain node and its indexer into Kubernetes via Pulumi. It reads configuration files and environment variables, maps services to detailed deployment parameters including ports, environment variables, probes, and ConfigMaps, and delegates the actual Kubernetes resource creation to a shared deployment function. The design follows a modular, extensible pattern consistent with other coinstacks in the multi-blockchain Unchained platform, ensuring scalable and maintainable infrastructure management.

End of Documentation for index.ts