Alpha Layer Hardhat Plugin

This plugin enables seamless integration between Hardhat projects and Shib Alpha Layer Rollups, providing wallet management, deployment tools, and configuration helpers.

Overview

The @shibaone/alpha-layer-hardhat package extends your Hardhat development environment with Shib Alpha Layer capabilities:

Wallet Management: Import, delete, and manage private keys for rollup transactions
Elder Wrap Integration: Deploy smart contracts using the Elder Wrap node
Network Configuration: Automatically inject rollup networks into your Hardhat config
CLI Tools: Command-line interface for Elder Wrap operations

Installation

Prerequisites

Before installing the plugin, ensure you have:

Node.js v20 or higher
A package manager (npm, pnpm, or yarn)
An existing Hardhat project

Setup

Create npm configuration

Create a .npmrc file in your project root to access the ShibaOne registry:

.npmrc

@shibaone:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<AUTH_TOKEN>

Replace <AUTH_TOKEN> with your GitHub personal access token that has package read permissions.

Install the plugin

Install the latest version of the Alpha Layer Hardhat plugin:

npm install @shibaone/alpha-layer-hardhat@latest

The plugin is successfully installed when you see it listed in your package.json dependencies.

Configuration

Generate keystore for contract deployments and onchain transactions using elder-wrap. This will create evm and elder address for private key you import.

npx wrap keystore import [alias] [private-key-hex]

Make sure to fund the corresponding evm account with native funds to pay fees

Create an elder.config.yaml file in your project root to configure the plugin:

elder.config.yaml

elder_grpc_endpoint: localhost:9090
elder_wrap_port: 8546
key_store_dir: ./keystore
log_level: info # debug, info, warn, error
rollup_rpcs:
  rollApp1:
    rpc: https://rollApp1_RPC_ADDRESS
    elder_registration_id: 1
  rollApp2:
    rpc: https://rollApp2_RPC_ADDRESS
    elder_registration_id: 2

https://shib.io/rollups/browse visit here to get rollup config details

Configuration Parameters

Hardhat Integration

Basic Setup

Wrap your existing Hardhat configuration with the withElder function:

hardhat.config.js

const { withElder } = require("@shibaone/alpha-layer-hardhat");

module.exports = withElder({
  solidity: {
    version: "0.8.19",
    settings: {
      optimizer: {
        enabled: true,
        runs: 200
      }
    }
  },
  networks: {
    // Your existing networks remain unchanged
    hardhat: {
      chainId: 1337
    }
  }
});

Advanced Configuration

For more control over the integration, you can use a function-based configuration:

hardhat.config.js

const { withElder } = require("@shibaone/alpha-layer-hardhat");

module.exports = withElder((config, keys) => {
  return {
    solidity: "0.8.19",
    networks: {
      rollApp1: {
        url: "http://localhost:8546",
        accounts: keys.map(key => key.privateKey),
        chainId: 1337
      },
      rollApp2: {
        url: "http://localhost:8546", 
        accounts: keys.map(key => key.privateKey),
        chainId: 1338
      }
    }
  };
}, "deployer"); // Use specific key alias

Wrap Server

You can run a wrap service to enable transactions via alpha layer.

# Start Elder Wrap service
npx wrap server

You will see server starting at 8546. Make sure to change network in hardhat.config.ts to http://localhost:8546/<Roll_App_Name>

API Reference

Hardhat Integration Functions

`withElder(hhConfig, keyAlias?)`

Wraps your Hardhat configuration to inject Alpha Layer rollup networks and accounts.

`getNetwork({ name, keyAlias? })`

Returns a Hardhat network configuration for a specific rollup.

const { getNetwork } = require("@shibaone/alpha-layer-hardhat");

const rollApp1Config = getNetwork({ name: "rollApp1" });
const rollApp2Config = getNetwork({ name: "rollApp2", keyAlias: "deployer" });

Keystore Management

The plugin provides several functions for managing wallet keys:

`getKey(alias)`

Retrieve a specific key by its alias.

const { getKey } = require("@shibaone/alpha-layer-hardhat");

const deployerKey = getKey("deployer");
console.log(`Deployer address: ${deployerKey.evmAddress}`);

`keyMap()`

Get a mapping of all key aliases to their corresponding key objects.

const { keyMap } = require("@shibaone/alpha-layer-hardhat");

const allKeys = keyMap();
Object.keys(allKeys).forEach(alias => {
  console.log(`${alias}: ${allKeys[alias].evmAddress}`);
});

`listKeys()`

Retrieve an array of all available key objects.

const { listKeys } = require("@shibaone/alpha-layer-hardhat");

const keys = listKeys();
keys.forEach(key => {
  console.log(`Address: ${key.evmAddress}, Elder: ${key.elderAddress}`);
});

Key Object Structure

string

required

Ethereum-compatible address derived from the private key.

string

required

Alpha Layer Elder address format for the same private key.

string

required

Hex-encoded private key for signing transactions.

Configuration Helpers

`getConfig()`

Parse and validate the configuration from elder.config.yaml.

const { getConfig } = require("@shibaone/alpha-layer-hardhat");

const config = getConfig();
console.log(`Elder Wrap URL: ${config.elder_wrap_port}`);

`wrap_url()`

Get the local Elder Wrap service URL.

const { wrap_url } = require("@shibaone/alpha-layer-hardhat");

const wrapUrl = wrap_url(); // Returns "http://localhost:8546"

Deployment

Using Hardhat Tasks

The plugin registers a custom Hardhat task for deploying contracts:

npx hardhat deploy-elder ./ignition/modules/MyContract.ts --network rollApp1

You can use the shorthand hh ignition deploy-elder for faster typing.

Deployment with ethers

The plugin works seamlessly with HRE too for complex deployments:

scripts/TokenDeployment.ts

import { hre } from "hardhat";

async function main() {
  const token = await hre.ethers.deployContract(
    "MyToken", ["My Token", "MTK"]
  );
    await token.waitForDeployment();
    console.log(`Token deployed to ${token.target}`);
};

Then deploy using:

npx hardhat run scripts/TokenDeployment.ts --network rollApp1

CLI Usage

The plugin provides a CLI wrapper for the elder-wrap binary:

# Start Elder Wrap service
wrap start

# Check service status
wrap status

# Stop the service
wrap stop

Always ensure the Elder Wrap service is running before attempting deployments or transactions.

Troubleshooting

Connection Issues

Problem: Cannot connect to Elder Wrap serviceSolutions:

Verify Elder Wrap is running on the configured port
Check firewall settings for port 8546
Ensure elder_grpc_endpoint is accessible
Restart the Elder Wrap service

Key Management Errors

Problem: Keys not found or invalidSolutions:

Verify keys are properly imported to the keystore directory
Check key file permissions (should be 600)
Ensure key aliases match exactly in configuration
Re-import keys if corruption is suspected

Deployment Failures

Problem: Contract deployment failsSolutions:

Check account balance on the target rollup
Verify contract bytecode compilation
Ensure proper network configuration
Check Elder Wrap logs for detailed error messages

Configuration Schema

Elder Config Schema

interface ElderConfig {
  elder_grpc_endpoint: string;
  elder_wrap_port: number;
  key_store_dir: string;
  log_level: "debug" | "info" | "warn" | "error";
  rollup_rpcs: {
    [network: string]: {
      rpc: string; // URL
      elder_registration_id: number;
    };
  };
}

Key Schema

interface KeyObject {
  evmAddress: string;
  elderAddress: string;
  privateKey: {
    key: string; // base64-encoded
  };
}

APIs & Data

Development Tools

Overview

Installation

Prerequisites

Setup

Configuration

Configuration Parameters

Hardhat Integration

Basic Setup

Advanced Configuration

Wrap Server

API Reference

Hardhat Integration Functions

`withElder(hhConfig, keyAlias?)`

`getNetwork({ name, keyAlias? })`

Keystore Management

`getKey(alias)`

`keyMap()`

`listKeys()`

Key Object Structure

Configuration Helpers

`getConfig()`

`wrap_url()`

Deployment

Using Hardhat Tasks

Deployment with ethers

CLI Usage

Troubleshooting

Configuration Schema

Elder Config Schema

Key Schema

​Overview

​Installation

​Prerequisites

​Setup

​Configuration

​Configuration Parameters

​Hardhat Integration

​Basic Setup

​Advanced Configuration

​Wrap Server

​API Reference

​Hardhat Integration Functions

​withElder(hhConfig, keyAlias?)

​getNetwork({ name, keyAlias? })

​Keystore Management

​getKey(alias)

​keyMap()

​listKeys()

​Key Object Structure

​Configuration Helpers

​getConfig()

​wrap_url()

​Deployment

​Using Hardhat Tasks

​Deployment with ethers

​CLI Usage

​Troubleshooting

​Configuration Schema

​Elder Config Schema

​Key Schema

Overview

Installation

Prerequisites

Setup

Configuration

Configuration Parameters

Hardhat Integration

Basic Setup

Advanced Configuration

Wrap Server

API Reference

Hardhat Integration Functions

`withElder(hhConfig, keyAlias?)`

`getNetwork({ name, keyAlias? })`

Keystore Management

`getKey(alias)`

`keyMap()`

`listKeys()`

Key Object Structure

Configuration Helpers

`getConfig()`

`wrap_url()`

Deployment

Using Hardhat Tasks

Deployment with ethers

CLI Usage

Troubleshooting

Configuration Schema

Elder Config Schema

Key Schema