index.ts

Overview

This file serves as the Pulumi deployment entrypoint script for the **Arbitrum** blockchain coinstack within the ShapeShift Unchained platform. It automates the provisioning of Kubernetes resources required to run Arbitrum's blockchain node ("daemon") and indexer services by:

• Reading environment and configuration files.

• Fetching the Kubernetes context and namespace.

• Mapping configured blockchain services (daemon and indexer) to deployment arguments with appropriate ports, environment variables, probes, and volume mounts.

• Invoking a shared deployment utility (deployCoinstack) to create Kubernetes StatefulSets, Services, and ConfigMaps.

The script tailor-fits the deployment parameters specifically for the Arbitrum blockchain node and its indexer, enabling reliable, scalable, and maintainable infrastructure management.

Detailed Explanation

Exported Asynchronous Default Function

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

• Purpose:
  Acts as the Pulumi entrypoint function that Pulumi calls to provision all necessary resources for the Arbitrum coinstack.

• Returns:
  A Promise resolving to an Outputs object, representing the results of the deployment (e.g., service endpoints, resource IDs).

• Workflow:

  1. Initialization:

     • Sets application and coinstack identifiers (appName = 'unchained', coinstack = 'arbitrum').

     • Reads the sample environment file (../sample.env) into memory.

     • Calls getConfig() to retrieve Kubernetes configuration (kubeconfig), Pulumi config object (config), and Kubernetes namespace (namespace).

  2. Service Argument Mapping:

     • Iterates over services defined in config.statefulService?.services.

     • For each service, performs a switch on service.name to generate a customized CoinServiceArgs object:

       • daemon service:

         • Defines RPC and WebSocket ports used by the Arbitrum daemon.

         • Sets environment variables pointing to Ethereum L1 endpoints for RPC and beacon nodes.

         • Reads and mounts critical config files (jwt.hex, evm.sh) as ConfigMaps and volume mounts.

         • Configures Kubernetes probes for startup, liveness, and readiness with specific timing parameters.

       • indexer service:

         • Extends the service with default Blockbook indexer arguments.

         • Reads indexer configuration from ../indexer/config.json and injects it as a ConfigMap.

       • default:

         • Throws an error if an unknown service name is encountered, enforcing strict service support.

  3. Deployment Invocation:

     • Calls deployCoinstack() with all prepared arguments including app name, service arguments, coinstack name, Kubernetes config, namespace, and environment file.

     • Returns the deployment outputs.

Key Imported Entities

• readFileSync (from 'fs'): Synchronously reads content of local files (e.g., environment and config files).

• deployCoinstack (from '../../../../pulumi/src/coinstack'): Core function that performs Kubernetes resource provisioning based on provided coinstack deployment arguments.

• Outputs, CoinServiceArgs, getConfig (from '../../../../pulumi/src'):

  • Outputs: Type representing deployment results.

  • CoinServiceArgs: Interface describing the deployment parameters for each blockchain service.

  • getConfig(): Async function that retrieves Kubernetes context and Pulumi configuration.

• defaultBlockbookServiceArgs (from '../../../packages/blockbook/src/constants'): Default configuration constants for Blockbook indexer services.

Important Implementation Details

• Service Configuration via map() and switch:
  The configuration for each service within the Arbitrum coinstack is dynamically composed by iterating over the statefulService.services array from the Pulumi config. This allows flexible addition or modification of services without changing the deployment logic.

• Custom Port and Environment Variable Setup for the Daemon:
  The daemon service exposes two ports:

  • HTTP RPC on port 8547.

  • WebSocket RPC on port 8548 with path prefix and stripping enabled for WebSocket connection routing.

  Additionally, environment variables `L1_RPC_ENDPOINT` and `L1_BEACON_ENDPOINT` are set to point to Ethereum L1 RPC and beacon services in the Kubernetes cluster, indicating the Arbitrum node depends on these upstream Ethereum nodes.

• ConfigMaps and Volume Mounts:
  Critical files such as jwt.hex (for authenticated RPC calls) and evm.sh (likely a helper script for Ethereum Virtual Machine operations) are read from the filesystem and injected into the pod via Kubernetes ConfigMaps and volume mounts. This decouples configuration from container images, allowing runtime modifications.

• Health Probes:
  Startup, liveness, and readiness probes are finely tuned with specific timeouts and thresholds, ensuring Kubernetes can effectively monitor the health of the daemon and restart it if necessary.

• Indexer Service Setup:
  The indexer uses default Blockbook settings and injects its own indexer-config.json configuration.

• Error Handling:
  The script explicitly throws an error if an unsupported service name is encountered, which prevents accidental deployment misconfigurations.

Usage Example

This file is not directly invoked by developers but is executed by Pulumi during infrastructure deployment:

pulumi up

The Pulumi CLI discovers this `index.ts` file as the deployment entrypoint for the Arbitrum coinstack, runs the exported async function, and provisions all Kubernetes resources accordingly.

Interaction with Other System Components

• Pulumi Core Library:
  This file depends on the shared Pulumi deployment framework (deployCoinstack, getConfig, etc.) that encapsulates Kubernetes resource creation logic. It only defines coinstack-specific configuration.

• Configuration Files:
  Reads local files (sample.env, jwt.hex, evm.sh, indexer/config.json) to inject environment variables and ConfigMaps into pods.

• Kubernetes Cluster:
  Deploys StatefulSets, Services, and ConfigMaps into the target Kubernetes cluster using the provided kubeconfig and namespace.

• Related Services:

  • The Arbitrum daemon relies on Ethereum L1 services running within the cluster (ethereum-svc.unchained.svc.cluster.local).

  • The indexer service (Blockbook-based) provides indexed blockchain data for API servers and clients.

• Scripts and Utilities:
  The mounted evm.sh script is likely invoked by the daemon container for lifecycle tasks.

Mermaid Diagram: Flowchart of index.ts Deployment Workflow

flowchart TD
  A[Start Pulumi Deployment] --> B[Read sample.env file]
  B --> C[Retrieve Kubernetes config, namespace via getConfig()]
  C --> D[Map statefulService.services to CoinServiceArgs]
  D --> E{Service Name}
  E -->|daemon| F[Configure daemon ports, env vars, ConfigMaps, volume mounts, probes]
  E -->|indexer| G[Apply defaultBlockbookServiceArgs and indexer config]
  E -->|other| H[Throw Error: Unsupported service]
  F --> I[Collect all CoinServiceArgs]
  G --> I
  I --> J[Invoke deployCoinstack with deployment args]
  J --> K[Deploy StatefulSets, Services, ConfigMaps to Kubernetes]
  K --> L[Pods start, run probes, mount volumes]
  L --> M[Daemon connects to L1 Ethereum RPC & Beacon]
  L --> N[Indexer indexes blockchain data]
  M & N --> O[Deployment complete, Outputs returned]

Summary

The `index.ts` file is the Arbitrum blockchain coinstack Pulumi deployment script that orchestrates the setup of daemon and indexer services in Kubernetes. It leverages shared deployment infrastructure, applies Arbitrum-specific configurations, and ensures robust service health management. This modular approach fits into the broader Multi-Blockchain Coinstacks system, enabling consistent multi-chain infrastructure provisioning on the ShapeShift Unchained platform.