index.ts

Overview

This file serves as the Pulumi deployment entrypoint for the **Binance Smart Chain (bnbsmartchain)** coinstack within the Unchained platform. Its primary role is to orchestrate the deployment of blockchain services—including daemon nodes and indexers—onto Kubernetes by:

• Loading configuration and environment files.

• Constructing service-specific deployment arguments based on the coinstack configuration.

• Invoking a shared deployment function to provision Kubernetes resources.

It encapsulates the service definitions and customization needed to run Binance Smart Chain node and indexer services with appropriate ports, environment variables, config maps, volume mounts, and Kubernetes health probes.

Detailed Explanation of the File Content

Imports

import { readFileSync } from 'fs'
import { deployCoinstack } from '../../../../pulumi/src/coinstack'
import { Outputs, CoinServiceArgs, getConfig } from '../../../../pulumi/src'
import { defaultBlockbookServiceArgs } from '../../../packages/blockbook/src/constants'

• readFileSync: Used to synchronously read local files such as environment and config files.

• deployCoinstack: Core Pulumi deployment function that provisions the coinstack services into Kubernetes.

• Outputs, CoinServiceArgs, getConfig: Types and helper function imported from the shared Pulumi source:

  • Outputs type represents deployment outputs.

  • CoinServiceArgs defines the shape of service deployment arguments.

  • getConfig() asynchronously obtains Kubernetes context, namespace, and configuration.

• defaultBlockbookServiceArgs: Default service parameters for Blockbook-based indexers.

Exported Async Function (Pulumi Entrypoint)

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

• This is the asynchronous main function Pulumi executes during deployment.

• It returns a Promise<Outputs>, representing the deployment results.

Variables and Configuration Loading

const appName = 'unchained'
const coinstack = 'bnbsmartchain'
const sampleEnv = readFileSync('../sample.env')
const { kubeconfig, config, namespace } = await getConfig()

• appName: Identifier for the application stack.

• coinstack: Name of the blockchain coinstack being deployed (Binance Smart Chain).

• sampleEnv: Reads a sample environment file to pass environment variables.

• getConfig(): Reads Kubernetes configuration, namespace, and coinstack configuration asynchronously.

Mapping Stateful Services to Deployment Arguments

const coinServiceArgs = config.statefulService?.services?.map((service): CoinServiceArgs => {
  switch (service.name) {
    case 'daemon':
      return {
        ...service,
        ports: {
          'daemon-rpc': { port: 8545 },
          'daemon-ws': { port: 8546, pathPrefix: '/websocket', stripPathPrefix: true },
        },
        env: {
          SNAPSHOT: 'https://pub-c0627345c16f47ab858c9469133073a8.r2.dev/geth-pbss-pebble-20231217.tar.lz4',
        },
        configMapData: { 'evm.sh': readFileSync('../../../scripts/evm.sh').toString() },
        volumeMounts: [{ name: 'config-map', mountPath: '/evm.sh', subPath: 'evm.sh' }],
        startupProbe: { periodSeconds: 30, failureThreshold: 60, timeoutSeconds: 10 },
        livenessProbe: { periodSeconds: 30, failureThreshold: 5, timeoutSeconds: 10 },
        readinessProbe: { periodSeconds: 30, failureThreshold: 10 },
      }
    case 'indexer':
      return {
        ...service,
        ...defaultBlockbookServiceArgs,
        configMapData: { 'indexer-config.json': readFileSync('../indexer/config.json').toString() },
      }
    default:
      throw new Error(`no support for coin service: ${service.name}`)
  }
})

• Iterates over each service defined in the coinstack configuration.

• Depending on the service name, returns a tailored CoinServiceArgs object describing deployment parameters:

Daemon service parameters:

• Ports:

  • daemon-rpc: JSON-RPC on port 8545.

  • daemon-ws: WebSocket endpoint on port 8546 with path prefix /websocket and path stripping.

• Environment Variables:

  • SNAPSHOT: URL to a snapshot archive used by the node for quick sync.

• ConfigMap Data:

  • Injects a shell script evm.sh (likely for node lifecycle management).

• Volume Mounts:

  • Mounts the evm.sh script into the container filesystem.

• Kubernetes Probes:

  • startupProbe, livenessProbe, readinessProbe with specific timing and thresholds for Kubernetes health checks.

Indexer service parameters:

• Extends the service with default Blockbook arguments for indexers.

• Injects the indexer-config.json configuration file via ConfigMap.

Error Handling:

• Throws an error if the service name is unrecognized to prevent invalid deployments.

Deployment Invocation

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

• Calls the shared deployCoinstack function with the prepared arguments.

• This function handles creating Kubernetes StatefulSets, Services, ConfigMaps, and other resources based on these parameters.

• Returns the deployment outputs.

Usage Example

This file is not directly invoked by users but executed by the Pulumi CLI during deployment.

Typical usage flow:

pulumi up -s <stack-name>

Pulumi runs this script, which:

• Reads configuration files and environment variables.

• Prepares deployment parameters for the Binance Smart Chain coinstack.

• Deploys daemon and indexer services with defined ports, environment, and health probes.

• Returns deployment outputs indicating success or failure.

Important Implementation Details and Algorithms

• Service Configuration Mapping:

  The script dynamically adapts deployment parameters based on the service name, enabling reuse of a common deployment function for different services with specific overrides.

• Health Probes Setup:

  Kubernetes probes (startupProbe, livenessProbe, readinessProbe) are carefully configured to ensure the daemon node's stability and timely recovery. These probes help detect issues such as node crashes, slow startups, or unready states.

• Snapshot Environment Variable:

  The daemon service is bootstrapped with a snapshot URL, which accelerates node synchronization by initializing from a pre-synced blockchain state archive.

• ConfigMap Usage:

  External scripts (evm.sh) and config files (indexer-config.json) are injected into containers via ConfigMaps and volume mounts, supporting configuration-as-code and facilitating updates without container image rebuilds.

• Error Handling:

  The script proactively throws errors if unknown services are encountered, safeguarding against misconfiguration.

Interaction with Other System Components

• Pulumi Core Library:

  Utilizes shared Pulumi deployment utilities from pulumi/src/coinstack and pulumi/src to create Kubernetes resources.

• Kubernetes Cluster:

  Deploys coinstack services as StatefulSets and Services into the configured Kubernetes namespace using the provided kubeconfig.

• Config Files and Scripts:

  Reads local files such as sample.env, indexer/config.json, and evm.sh to configure services.

• Blockbook:

  Uses default Blockbook service defaults for the indexer service, integrating with the Blockbook infrastructure for blockchain data indexing.

• Other Coinstacks:

  This file follows a standardized pattern shared across multiple blockchain coinstacks enabling consistent deployment and management.

Mermaid Diagram: Flowchart of the Deployment Workflow in index.ts

flowchart TD
  A[Start Deployment] --> B[Read sample.env file]
  B --> C[Call getConfig() to load kubeconfig, config, namespace]
  C --> D[Iterate over config.statefulService.services]
  D --> E{Service Name?}
  E -->|daemon| F[Construct Daemon Deployment Args
  (Ports, Env, ConfigMap, Probes, Volumes)]
  E -->|indexer| G[Construct Indexer Deployment Args
  (Default Blockbook Args, ConfigMap)]
  E -->|Other| H[Throw Error: Unsupported Service]
  F --> I[Collect all CoinServiceArgs]
  G --> I
  I --> J[Call deployCoinstack() with all args]
  J --> K[Provision Kubernetes resources]
  K --> L[Deploy StatefulSets, Services, ConfigMaps]
  L --> M[Daemon and Indexer Pods start with health probes]
  M --> N[Deployment complete with Outputs returned]

Summary

The **index.ts** file is the deployment script for the Binance Smart Chain coinstack in Unchained’s multi-blockchain infrastructure. Its key responsibilities are:

• Loading configuration and environment files.

• Mapping defined coinstack services to detailed deployment parameters.

• Applying blockchain-specific customization such as ports, snapshots, health probes, and config maps.

• Calling a shared deployment function that manages Kubernetes resource provisioning.

• Ensuring robust health and readiness monitoring through Kubernetes probes.

This script fits into the larger Pulumi-based infrastructure automation framework enabling consistent, scalable, and maintainable deployments of blockchain nodes and indexers across different chains.

If you require further detail on related modules or deployment workflows, please refer to the **Multi-Blockchain Coinstacks** documentation and the shared Pulumi libraries.