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

1

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.
2

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

​
evmAddress
string
required
Ethereum-compatible address derived from the private key.
​
elderAddress
string
required
Alpha Layer Elder address format for the same private key.
​
privateKey
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

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
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
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
  };
}