🚀 DeployKit

AWS KMS-based Ethereum Smart Contract Deployment & Management Toolkit

DeployKit is a professional CLI tool and SDK for deploying and managing Ethereum smart contracts using AWS KMS (Key Management Service) for secure transaction signing. No private keys needed!

⚠️ Version Compatibility

Current Version: v1.x - Requires Hardhat 2.x + ethers v5

• ✅ Hardhat 2.28.0+ with ethers v5 → Use [email protected] (this version)
• 🚧 Hardhat 3.x with ethers v6 → v2.x coming soon (or downgrade to Hardhat 2.x)

👉 See VERSION_COMPATIBILITY.md for details

📝 JavaScript vs TypeScript Support

DeployKit works with both JavaScript and TypeScript Hardhat projects:

• ✅ JavaScript Projects: If you have hardhat.config.js and config/deploy.config.js, no additional setup needed
• ✅ TypeScript Projects: If you have hardhat.config.ts or config/deploy.config.ts, install ts-node:

  npm install --save-dev ts-node typescript

The package automatically detects which type of config files you're using and handles them accordingly.

✨ Features

• 🔐 Secure Signing: Uses AWS KMS (secp256k1) - no private keys in code
• 📦 Multi-Pattern Support: Deploy standard, UUPS, Transparent, and Beacon proxy upgradeable contracts
• 🌍 Multi-Chain: Supports all EVM chains (Ethereum, Polygon, Arbitrum, Optimism, etc.)
• 🎯 CLI & SDK: Use as a command-line tool or integrate into your scripts
• ⚡ EIP-1559 Support: Modern gas pricing with maxFeePerGas
• ✅ Contract Verification: Built-in Etherscan verification
• 🔄 Dry Run Mode: Test deployments without executing transactions
• 📊 Detailed Logging: Transaction hashes, addresses, and deployment summaries

📦 Installation

Global Installation (CLI)

npm install -g systango-deploykit

Local Installation (Project Dependency)

npm install --save-dev systango-deploykit

🚀 Quick Start

1. Setup AWS KMS

Create a KMS key with ECC_SECG_P256K1 key spec:

aws kms create-key \
  --key-spec ECC_SECG_P256K1 \
  --key-usage SIGN_VERIFY \
  --description "Ethereum Deployment Key"

2. Configure Environment

Create .env in your project root:

# AWS KMS Configuration
AWS_KMS_KEY_ID=your-kms-key-id
AWS_REGION=ap-south-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

# Network RPC (Optional)
ALCHEMY_API_KEY=your-alchemy-key

# Block Explorer (For Verification)
ETHERSCAN_API_KEY=your-etherscan-key

3. Get Your KMS Address

deploykit kms-address -n sepolia

4. Fund the Address

Send ETH to the KMS-derived address for gas fees.

5. Deploy Contracts

deploykit deploy -n sepolia

📖 Documentation

• CLI Usage Guide - Complete CLI reference
• Configuration Guide - Setup and config details
• Examples - Real-world usage examples

🛠️ Usage

CLI Commands

# Display help
deploykit --help

# Get KMS address
deploykit kms-address -n sepolia

# Check balance
deploykit kms-balance -n sepolia

# Deploy contracts (dry run)
deploykit deploy -n sepolia --dry-run

# Deploy contracts
deploykit deploy -n sepolia

# Deploy specific contract
deploykit deploy -n sepolia --contract MyContract

# Verify contract
deploykit verify -a 0x... -n sepolia --contract-name MyContract

# Refund remaining ETH
deploykit kms-refund -t 0xYourAddress -n sepolia

# Show configuration
deploykit info

SDK Usage

import { runDeployments } from "@systango/deploykit";
import { DeploymentConfig } from "@systango/deploykit/config/deploy.config";
import hre from "hardhat";

const configs: DeploymentConfig[] = [
  {
    contractName: "MyContract",
    network: "sepolia",
    upgradeability: "uups",
    initializer: "initialize",
    initializerArgs: ["Hello World"],
  },
];

const results = await runDeployments(hre, configs);
console.log("Deployed:", results);

⚙️ Configuration

Deployment Configuration (config/deploy.config.ts)

export const deployments: DeploymentConfig[] = [
  // UUPS Upgradeable
  {
    contractName: "MyUUPSContract",
    network: "sepolia",
    upgradeability: "uups",
    initializer: "initialize",
    initializerArgs: ["arg1", "arg2"],
    gasOverrides: {
      maxFeePerGasWei: "30000000000",        // 30 gwei
      maxPriorityFeePerGasWei: "2000000000", // 2 gwei
    },
  },
  
  // Transparent Upgradeable
  {
    contractName: "MyTransparentContract",
    network: "sepolia",
    upgradeability: "transparent",
    initializer: "initialize",
    initializerArgs: ["arg1"],
    proxyAdminOwner: "0xYourAdminAddress",
  },
  
  // Non-upgradeable
  {
    contractName: "MyStandardContract",
    network: "sepolia",
    upgradeability: "none",
    constructorArgs: ["arg1", "arg2"],
  },
  
  // Beacon Proxy
  {
    contractName: "MyBeaconContract",
    network: "sepolia",
    upgradeability: "beacon",
    initializer: "initialize",
    initializerArgs: ["arg1"],
    beaconOwner: "0xYourBeaconOwnerAddress", // Optional
  },
];

Hardhat Configuration (hardhat.config.ts)

import { HardhatUserConfig } from "hardhat/config";
import "@nomiclabs/hardhat-ethers";
import "@openzeppelin/hardhat-upgrades";
import "@nomiclabs/hardhat-etherscan";
import * as dotenv from "dotenv";

dotenv.config();

const config: HardhatUserConfig = {
  solidity: "0.8.23",
  networks: {
    sepolia: {
      url: process.env.ALCHEMY_API_KEY
        ? `https://eth-sepolia.g.alchemy.com/v2/${process.env.ALCHEMY_API_KEY}`
        : "https://rpc.sepolia.org",
      accounts: [], // No private keys needed!
    },
  },
  etherscan: {
    apiKey: process.env.ETHERSCAN_API_KEY,
  },
};

export default config;

📚 Examples

Deploy All Contract Types

# Dry run to preview
deploykit deploy -n sepolia --dry-run

# Execute deployment
deploykit deploy -n sepolia

Output:

🚀 DeployKit - Contract Deployment

📡 Target Network: sepolia
📦 Found 4 contract(s) to deploy

Deploying MyUUPSContract (upgradeability=uups)
✅ Deployed UUPS proxy
   Proxy: 0x123...
   Implementation: 0x456...

Deploying MyTransparentContract (upgradeability=transparent)
✅ Deployed Transparent proxy
   Proxy: 0x789...
   Implementation: 0xabc...
   Admin: 0xdef...

Deploying MyBeaconContract (upgradeability=beacon)
✅ Deployed Beacon proxy
   Beacon: 0x...
   Proxy: 0x...
   Implementation: 0x...

Deploying MyStandardContract (upgradeability=none)
✅ Deployed standard contract
   Address: 0x111...

════════════════════════════════════════════════════════════
✅ DEPLOYMENT SUMMARY
════════════════════════════════════════════════════════════

4 contracts deployed successfully!

Verify Contracts After Deployment

# Verify UUPS implementation
deploykit verify -a 0x456... -n sepolia --contract-name MyUUPSContract

# Verify Transparent implementation
deploykit verify -a 0xabc... -n sepolia --contract-name MyTransparentContract

# Verify Beacon proxy (use proxy address)
deploykit verify -a 0x... -n sepolia --contract-name MyBeaconContract

# Verify standard contract
deploykit verify -a 0x111... -n sepolia --contract-name MyStandardContract

🏗️ Supported Contract Patterns

1. UUPS (Universal Upgradeable Proxy Standard)

import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";

contract MyUUPS is Initializable, UUPSUpgradeable, OwnableUpgradeable {
    function initialize() public initializer {
        __Ownable_init(msg.sender);
        __UUPSUpgradeable_init();
    }
    
    function _authorizeUpgrade(address) internal override onlyOwner {}
}

2. Transparent Upgradeable Proxy

import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

contract MyTransparent is Initializable {
    function initialize() public initializer {
        // Initialize logic
    }
}

3. Beacon Proxy

import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

contract MyBeacon is Initializable {
    function initialize(string memory _config) public initializer {
        // Initialize logic
    }
}

4. Non-Upgradeable (Standard)

contract MyStandard {
    constructor(string memory _name) {
        // Constructor logic
    }
}

🔒 Security Best Practices

1. AWS KMS: Use dedicated KMS keys per environment (dev/prod)
2. IAM Policies: Grant minimal KMS permissions (Sign, GetPublicKey)
3. Key Rotation: Implement key rotation policies
4. Network Isolation: Use VPC endpoints for KMS access
5. Audit Logging: Enable CloudTrail for KMS operations
6. Environment Separation: Never use production keys in development

Example IAM Policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:Sign",
        "kms:GetPublicKey"
      ],
      "Resource": "arn:aws:kms:region:account-id:key/key-id"
    }
  ]
}

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

ISC License - see LICENSE for details.

🙏 Acknowledgments

• OpenZeppelin - Upgradeable contracts
• Hardhat - Development environment
• aws-kms-ethers-signer - KMS signing library
• Commander.js - CLI framework

📞 Support

• Issues: GitHub Issues
• Documentation: CLI Usage Guide
• Email: [email protected]

Made with ❤️ by Systango