Ops Add New Chain

Add New Chain to Boundless Infrastructure

Interactive workflow for deploying Boundless services (order-stream, distributor, slasher, indexer, order-generator) to a new blockchain network.

SAFETY: Never perform destructive operations

NEVER delete, remove, or destroy Pulumi stacks, resources, or config files. NEVER run pulumi destroy, pulumi stack rm, or remove existing Pulumi.*.yaml files. This skill is strictly additive -- it only creates new stacks and config.

NEVER perform destructive AWS actions. Do not delete AWS resources, S3 objects, KMS keys, IAM roles, security groups, RDS instances, ECS services, or any other AWS infrastructure. Do not run aws ... delete-*, aws ... remove-*, or aws ... terminate-* commands.

Step 1: Gather Chain Information

Ask the user for the following information in batches of 2-3 questions:

Batch 1: Chain basics

• Chain ID (numeric, e.g. 167000 for Taiko)
• Chain name (human-readable, e.g. Taiko Mainnet)
• Do staging and prod use different chain IDs? (e.g. mainnet for prod, testnet for staging, or same chain ID with different contracts)

Batch 2: Contract addresses

Staging and prod typically have different contract deployments. Ask for two separate sets of contract addresses -- one for staging and one for prod. Some addresses (e.g. COLLATERAL_TOKEN_ADDRESS, SET_VERIFIER_ADDR) may be shared across environments; confirm with the user rather than assuming.

For each environment (staging and prod), ask for:

• BOUNDLESS_ADDRESS (BoundlessMarket contract -- also used as BOUNDLESS_MARKET_ADDR in some services)
• COLLATERAL_TOKEN_ADDRESS
• SET_VERIFIER_ADDR
• CHAINALYSIS_ORACLE_ADDRESS (use zero address if chain has no Chainalysis oracle)

If the user does not have an address yet, use 0x0000000000000000000000000000000000000000 as a placeholder.

Note: DISTRIBUTOR_ADDRESS is the same across all staging envs and all prod envs respectively. It gets copied automatically from the source stack via copy_config.sh and does not need to be asked for or overridden.

Batch 3: Deployment details

• Deployment block for each environment (block number where contracts were deployed -- used as START_BLOCK for indexer and slasher). Staging and prod may have different deployment blocks if they use different contracts.
• RPC URLs for the new chain -- ask for a separate RPC URL per service, since each service may use a different provider. Services that need an RPC URL:
  • order-stream (ETH_RPC_URL)
  • distributor (ETH_RPC_URL)
  • slasher (ETH_RPC_URL)
  • indexer (ETH_RPC_URL and optionally LOGS_ETH_RPC_URL)
  • order-generator (ETH_RPC_URL) The user may provide a single URL for all, or different URLs per service.
• ALB domain for order-stream (e.g. taiko-mainnet.boundless.network), or skip if not setting up a domain yet

Store all gathered values as variables for use in subsequent steps.

Step 2: Verify AWS Access

The dev account role only has read-only access to the Pulumi state bucket. You need credentials for a role with write access: Ops Admin, Staging Admin, or Production Admin.

Ask the user to provide AWS credentials. They need to export these env vars in the terminal:

export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="..."
export AWS_DEFAULT_REGION="us-west-2"

After the user confirms they have exported credentials, verify by running:

aws sts get-caller-identity

Confirm the output shows a valid identity. If it fails, stop and ask the user to fix credentials before proceeding.

Then verify Pulumi backend access:

pulumi login "s3://boundless-pulumi-state?region=us-west-2&awssdk=v2"

If either command fails, do not proceed.

Step 3: Update ChainId Enum

Edit infra/util/index.ts:

1. Add the new chain to the ChainId enum (use UPPER_SNAKE_CASE):

export enum ChainId {
  ETH_MAINNET = "1",
  ETH_SEPOLIA = "11155111",
  BASE = "8453",
  BASE_SEPOLIA = "84532",
  {NEW_CHAIN} = "{CHAIN_ID}",
}

2. Add entry in getChainName() (before the throw):

if (chainId === ChainId.{NEW_CHAIN}) {
  return "{Chain Name}";
}

3. Add entry in getChainId() (before the throw):

if (chainId === "{CHAIN_ID}") {
  return ChainId.{NEW_CHAIN};
}

Step 4: Update Pipeline Definitions

Two files need updating. The others inherit from LaunchDefaultPipeline and get the new chain automatically.

4a: LaunchDefaultPipeline.ts

File: infra/pipelines/pipelines/base/LaunchDefaultPipeline.ts

In createPipeline(), after the existing CodeBuild projects, add two new ones:

const stagingDeployment{ChainName} = new aws.codebuild.Project(
    `l-${this.config.appName}-staging-{CHAIN_ID}-build`,
    this.codeBuildProjectArgs(this.config.appName, "l-staging-{CHAIN_ID}", role, BOUNDLESS_STAGING_DEPLOYMENT_ROLE_ARN, dockerUsername, dockerTokenSecret, githubTokenSecret),
    { dependsOn: [role] }
);

const prodDeployment{ChainName} = new aws.codebuild.Project(
    `l-${this.config.appName}-prod-{CHAIN_ID}-build`,
    this.codeBuildProjectArgs(this.config.appName, "l-prod-{CHAIN_ID}", role, BOUNDLESS_PROD_DEPLOYMENT_ROLE_ARN, dockerUsername, dockerTokenSecret, githubTokenSecret),
    { dependsOn: [role] }
);

Add pipeline stage actions:

• In DeployStaging.actions array, add action with runOrder: 1:

{
    name: "DeployStaging{ChainName}",
    category: "Build",
    owner: "AWS",
    provider: "CodeBuild",
    version: "1",
    runOrder: 1,
    configuration: {
        ProjectName: stagingDeployment{ChainName}.name
    },
    outputArtifacts: ["staging_output_{chain_snake}"],
    inputArtifacts: ["source_output"],
}

• In DeployProduction.actions array, add action with runOrder: 2:

{
    name: "DeployProduction{ChainName}",
    category: "Build",
    owner: "AWS",
    provider: "CodeBuild",
    version: "1",
    runOrder: 2,
    configuration: {
        ProjectName: prodDeployment{ChainName}.name
    },
    outputArtifacts: ["production_output_{chain_snake}"],
    inputArtifacts: ["source_output"],
}

4b: l-indexer.ts

File: infra/pipelines/pipelines/l-indexer.ts

This file overrides createPipeline() with its own stage definitions. Apply the exact same pattern as 4a -- add staging + prod CodeBuild projects and pipeline stage actions.

Files that do NOT need changes

• l-distributor.ts, l-order-stream.ts, l-slasher.ts, l-order-generator.ts use LaunchDefaultPipeline without overriding createPipeline()
• l-requestor-lists.ts uses environment-level stacks (l-staging/l-prod), not chain-specific