index.ts

Overview

This file serves as the Pulumi deployment entrypoint script for the Dogecoin coinstack within the **Multi-Blockchain Coinstacks** system. Its primary role is to orchestrate the deployment of Dogecoin blockchain node services—specifically the daemon and indexer—into a Kubernetes cluster, using Pulumi infrastructure-as-code constructs.

The script reads configuration data and environment files, maps configured blockchain services to deployment arguments, and invokes a shared `deployCoinstack()` function to provision Kubernetes resources such as StatefulSets, Services, and ConfigMaps. It handles blockchain-specific customization for ports, environment variables, readiness probes, and configuration injection.

Detailed Explanation

Imported Modules

• readFileSync from fs: Reads files synchronously (used to load environment variables and config files).

• deployCoinstack from '../../../../pulumi/src/coinstack': Core function that provisions blockchain services on Kubernetes.

• Outputs, CoinServiceArgs, getConfig from '../../../../pulumi/src': Types and utilities for configuration and deployment.

• defaultBlockbookServiceArgs from '../../../packages/blockbook/src/constants': Shared default arguments for Blockbook-based indexer services.

Exported Asynchronous Function (Default Export)

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

Purpose

This anonymous async function acts as the Pulumi program entrypoint. Pulumi invokes this function to execute the deployment logic and return an `Outputs` object describing the deployed resources.

Workflow

1. Initialize Constants:

   • appName: Fixed application name string 'unchained'.

   • coinstack: Fixed blockchain identifier string 'dogecoin'.

   • sampleEnv: Reads the sample.env file from a relative path to load environment variables used in the deployment.

2. Load Kubernetes & Application Configuration:

   Calls getConfig(), an async utility that returns:

   • kubeconfig: Kubernetes cluster connection configuration.

   • config: Application-specific deployment configuration object.

   • namespace: Kubernetes namespace where resources will be deployed.

3. Map Configured Stateful Services to Deployment Arguments:

   The function reads the array of services configured at config.statefulService?.services and maps each service into a CoinServiceArgs object based on its name:

   • Daemon Service:

     • Ports: Exposes daemon RPC on port 8332 (Dogecoin standard RPC port).

     • Environment variable NETWORK set to config.network.

     • Readiness probe configured with a 30-second period and 10 failure threshold.

     • Inherits other service properties via spread syntax (...service).

   • Indexer Service:

     • Inherits all properties from the service config and merges default Blockbook indexer args (defaultBlockbookServiceArgs).

     • Injects an indexer-config.json file into a ConfigMap by reading it from ../indexer/config.json.

   • Any Other Service:

     • Throws an error indicating unsupported coin service.

4. Call deployCoinstack() with Constructed Arguments:

   Passes all relevant data to the deployment function:

   • appName, coinstack, coinServiceArgs

   • coinstackType fixed to 'node'

   • Kubernetes config, namespace, and sample environment variables.

5. Returns the deployment outputs (Outputs) from deployCoinstack().

Types and Interfaces

• CoinServiceArgs (imported):

  Represents the argument structure describing each blockchain service to deploy. It includes properties such as:

  • name: Service name (e.g., 'daemon', 'indexer').

  • ports: Ports to expose, with optional ingress routing rules.

  • env: Environment variables for the container.

  • readinessProbe, livenessProbe, startupProbe: Kubernetes health probe configurations.

  • configMapData: Key-value pairs of files to mount as ConfigMaps.

  • Other Kubernetes deployment customization options.

• Outputs:

  Returned by the deployment process, containing references to created Kubernetes resources and any other relevant deployment metadata.

• getConfig():

  Async function returning Kubernetes and deployment config, including:

  • kubeconfig: Cluster connection info.

  • config: Application config including stateful service definitions.

  • namespace: Deployment namespace.

Usage Example

This file is typically not imported or called directly by users. Instead, Pulumi invokes it automatically during deployment runs. However, conceptually:

pulumi up

This command triggers Pulumi to execute the exported async function, which reads configuration, prepares service arguments, and deploys the Dogecoin coinstack services into the specified Kubernetes cluster.

Important Implementation Details

• Service Mapping Logic:

  The switch-case on service.name allows flexible customization per service type to accommodate blockchain-specific deployment needs, e.g., ports and probes.

• ConfigMap Injection:

  The indexer service requires configuration from a JSON file (indexer-config.json), injected as a ConfigMap. This enables dynamic configuration without baking it into container images.

• Health Probes:

  Readiness probes ensure Kubernetes only routes traffic to pods that are ready to serve requests, improving deployment stability.

• Error Handling:

  Throws an error if an unrecognized service name is encountered, preventing unsupported or misconfigured services from deploying silently.

• Integration with Pulumi Core:

  Calls deployCoinstack() from a centralized Pulumi library, abstracting away Kubernetes resource creation details and standardizing deployment patterns across blockchains.

Interaction with Other System Components

• Pulumi Core Library (pulumi/src/coinstack):

  This file depends on the core Pulumi deployment library to manage Kubernetes resource creation.

• Configuration Utilities (pulumi/src):

  Uses getConfig() to obtain cluster context and deployment parameters.

• Blockbook Package (packages/blockbook):

  Imports default arguments for indexer services, since Dogecoin indexer is Blockbook-based.

• File System:

  Reads environment and indexer configuration files from relative directories, allowing configuration to be managed outside of the deployment code.

• Kubernetes Cluster:

  Deploys StatefulSets and Services representing Dogecoin daemon and indexer pods, integrating with cluster networking, storage, and monitoring.

• Other Coinstack Deployment Scripts:

  This file follows the same pattern as other coinstack entrypoints (e.g., Litecoin, Ethereum) and fits into the multi-blockchain deployment framework.

Mermaid Diagram: Flowchart of index.ts Deployment Structure

flowchart TD
  A[Start Pulumi Deployment] --> B[Read sample.env file]
  B --> C[Call getConfig() to get kubeconfig, config, namespace]
  C --> D[Map config.statefulService.services to CoinServiceArgs]
  D --> E{Service Name}
  E -->|daemon| F[Configure daemon service args: ports(8332), env, readinessProbe]
  E -->|indexer| G[Configure indexer service args: defaultBlockbookServiceArgs, configMapData]
  E -->|others| H[Throw error: unsupported service]
  F & G --> I[Aggregate coinServiceArgs array]
  I --> J[Call deployCoinstack() with appName, coinstack, coinServiceArgs, config, kubeconfig, namespace, sampleEnv]
  J --> K[Deploy Kubernetes resources for Dogecoin services]
  K --> L[Return deployment Outputs]

Summary

The `index.ts` file is a deployment script that automates the provisioning of Dogecoin blockchain node services on Kubernetes using Pulumi. It reads configuration files and environment variables, prepares service-specific deployment arguments (especially for daemon and indexer services), and calls a centralized deployment function to create the necessary resources in the cluster.

It exemplifies the modular, configurable design of the Multi-Blockchain Coinstacks system, enabling scalable, repeatable, and maintainable blockchain infrastructure deployments across multiple networks.