index.ts

Overview

This file defines the Pulumi deployment entrypoint for the **Base Ethereum Layer 1 coinstack** within the ShapeShift Unchained multi-blockchain infrastructure. It orchestrates the configuration and deployment of blockchain node services—specifically the daemon node, the optimistic rollup node (`op-node`), and the indexer service—by preparing service-specific deployment parameters and invoking the shared `deployCoinstack` function.

Key aspects include:

• Reading local environment and configuration files.

• Fetching Kubernetes cluster context and namespace.

• Mapping configured stateful services (daemon, op-node, and indexer) to detailed deployment argument objects with custom environment variables, ports, health probes, and volume mounts.

• Throwing an error for unsupported services to enforce strict service definitions.

• Initiating the deployment process for the entire coinstack using Pulumi.

This file facilitates automated, reproducible Kubernetes deployment of the Ethereum base chain node stack as part of the ShapeShift Unchained platform.

Detailed Explanation

Exported Function (Default Export)

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

• Purpose: Acts as the Pulumi program entrypoint for deploying the Base Ethereum coinstack.

• Returns: A Promise resolving to Outputs, which is the deployment output type from the shared Pulumi deployment library.

• Usage: Invoked by the Pulumi CLI during deployment to provision Kubernetes resources.

Internal Workflow Steps

1. Constants Initialization

const appName = 'unchained'
const coinstack = 'base'

• appName identifies the application or platform name.

• coinstack identifies the blockchain coinstack being deployed (Ethereum base L1 here).

2. Read Environment Sample

const sampleEnv = readFileSync('../sample.env')

• Reads a sample environment variables file from the local filesystem.

• This file often contains environment variables or secrets used in deployment.

3. Fetch Kubernetes Configuration

const { kubeconfig, config, namespace } = await getConfig()

• Retrieves Kubernetes cluster config (kubeconfig), deployment configuration object (config), and target namespace.

• getConfig() is an async helper that abstracts cluster/environment discovery and config parsing.

4. Map Stateful Services to Deployment Arguments

const coinServiceArgs = config.statefulService?.services?.map((service): CoinServiceArgs => { ... })

• Iterates over each configured service in the statefulService.services array.

• Maps each service (e.g., daemon, op-node, indexer) to a CoinServiceArgs object with tailored properties:

Service-Specific Argument Construction

1. daemon Service

• Environment Variables:

  • SNAPSHOT: URL to a blockchain snapshot tarball used for fast sync.

• Ports:

  • daemon-rpc: 8545 (standard Ethereum JSON-RPC)

  • daemon-ws: 8546 (WebSocket with path prefix /websocket)

  • daemon-auth: 8551 (authentication endpoint, no ingress routing)

  • daemon-p2p: 30303 (Ethereum peer-to-peer port, no ingress routing)

• ConfigMap Data:

  • Injects jwt.hex (JWT token for auth) and evm.sh (lifecycle script).

• Volume Mounts:

  • Mounts the JWT and script files from ConfigMap into container paths /jwt.hex and /evm.sh.

• Probes:

  • Startup, liveness, and readiness probes configured with specific timeouts and thresholds to ensure proper pod health management.

2. op-node Service

• Environment Variables:

  • L1_RPC_ENDPOINT and L1_BEACON_ENDPOINT point to internal Kubernetes service endpoints for the Ethereum daemon.

• Ports:

  • op-node-rpc: 9545 (RPC endpoint without ingress routing)

  • op-node-p2p: 9222 (peer-to-peer port without ingress routing)

• ConfigMap Data:

  • Injects evm.sh lifecycle script.

• Volume Mounts:

  • Same as daemon: mounts jwt.hex and evm.sh.

• Probes:

  • Startup, liveness, readiness probes with similar parameters.

3. indexer Service

• Defaults:

  • Uses shared defaultBlockbookServiceArgs (common Blockbook indexer defaults).

• Additional Configurations:

  • Adds a command flag -processerc1155=false (custom indexer behavior).

  • Injects a JSON config file indexer-config.json via ConfigMap.

• Probes:

  • Readiness probe configured with period and failure threshold.

Unsupported Service Handling

• Throws an error if a service name is not recognized, ensuring no accidental deployment of unknown services.

Final Deployment Invocation

return deployCoinstack({
  appName,
  coinServiceArgs,
  coinstack,
  coinstackType: 'node',
  config,
  kubeconfig,
  namespace,
  sampleEnv,
})

• Calls the shared deployCoinstack function with gathered parameters.

• This function takes care of creating Kubernetes StatefulSets, Services, ConfigMaps, and other resources required to run the coinstack.

• coinstackType set to 'node' indicates this coinstack deploys blockchain node services.

Parameters and Types

Usage Example

This file is typically executed by the Pulumi CLI during deployment:

pulumi up

Pulumi will:

• Load this file as the program entrypoint.

• Execute the default exported async function.

• Deploy the Ethereum base coinstack services to Kubernetes.

Implementation Details and Algorithms

• Service Mapping Logic: The file uses a switch statement on service.name to customize service parameters. This pattern provides clear, explicit configurations per service type.

• File Reads for ConfigMaps: Several files (e.g., jwt.hex, evm.sh, indexer-config.json) are read synchronously from the filesystem and injected as ConfigMap data, enabling dynamic configuration injection.

• Probe Configuration: Kubernetes health check probes are defined inline with custom timing parameters to ensure pods are properly monitored for startup, readiness, and liveness.

• Error Handling: The switch default case throws a runtime error for unsupported services to prevent misconfiguration.

• Asynchronous Configuration Fetching: getConfig() is awaited to asynchronously fetch cluster and deployment config, ensuring the deployment adapts to runtime environment.

Interaction with Other Parts of the System

• Pulumi Core Library (pulumi/src/coinstack): Imports deployCoinstack which encapsulates the deployment logic for Kubernetes resources.

• Shared Config and Constants: Imports getConfig and CoinServiceArgs types from the Pulumi core library, and shared constants (defaultBlockbookServiceArgs) from the Blockbook package.

• Filesystem Inputs: Reads local files in the repository (e.g., ../sample.env, ../daemon/jwt.hex, ../../../scripts/evm.sh, ../indexer/config.json) to inject configuration and lifecycle scripts.

• Kubernetes Cluster: Deploys resources into a Kubernetes cluster specified by kubeconfig and namespace.

• Service Dependencies: The op-node service depends on the daemon service endpoints for its environment variables.

• Deployment Outputs: Returns deployment outputs for further automation or inspection.

Mermaid Flowchart: Deployment Workflow in index.ts

flowchart TD
  A[Start Deployment] --> B[Read sample.env File]
  B --> C[Fetch kubeconfig, config, namespace]
  C --> D[Map statefulService.services to CoinServiceArgs]
  D --> E{Service Name}
  E -->|daemon| F[Configure daemon service args]
  E -->|op-node| G[Configure op-node service args]
  E -->|indexer| H[Configure indexer service args]
  E -->|unsupported| I[Throw Error]
  F --> J[Aggregate all service args]
  G --> J
  H --> J
  J --> K[Call deployCoinstack with args]
  K --> L[Provision Kubernetes Resources]
  L --> M[Deployment Complete]

Summary

This `index.ts` Pulumi program file automates deploying the Ethereum Base Layer 1 coinstack by:

• Reading environment and configuration files.

• Preparing detailed deployment arguments for each blockchain service (daemon, op-node, indexer).

• Applying custom environment variables, ports, volume mounts, and health checks.

• Invoking a shared deployment function to provision Kubernetes resources such as StatefulSets, Services, and ConfigMaps.

• Ensuring robust deployment with error handling on unrecognized services.

It is a critical piece in the modular multi-blockchain infrastructure, enabling reliable, repeatable, and scalable deployment of Ethereum base chain node services on Kubernetes.

Appendix: Key Imported Entities

End of Documentation for index.ts