AWS Kaia Rewards TypeScript Lambda Integration

This project represents a TypeScript implementation of an AWS customer master key (CMK) based Kaia network account using AWS Lambda and the AWS Cloud Development Kit (CDK), specifically designed for multisend reward distributions.

Overview

This repository contains a TypeScript/Node.js implementation of the AWS KMS Kaia network integration, providing functionality for sending rewards to multiple users on the Kaia network using AWS KMS for secure key management.

Features

• Kaia Network Integration: Create and manage Kaia network accounts using AWS KMS
• Multisend Functionality: Send KAIA tokens and native tokens to multiple recipients in batch operations
• Token Operations: Support for both native KAIA tokens and ERC-20 tokens
• Transaction Signing: Sign Kaia transactions using AWS KMS
• Multi-Network Support: Support for Kaia mainnet and testnet
• TypeScript: Full type safety and modern development experience
• CDK Infrastructure: Infrastructure as code using AWS CDK
• KMS Key Import: Import existing private keys into AWS KMS

Architecture

The project consists of:

1. CDK Stack (lib/aws-kaia-lambda-stack.ts): Defines the AWS infrastructure
2. Kaia Utilities (src/utils/kaia-utils.ts): Core Kaia operations including multisend
3. Lambda Functions:
   • kaia-kms-client: Basic Kaia operations
   • KaiaMultisendClient: Multisend functionality for reward distributions
   • KMSImportLambda: Import existing private keys into AWS KMS
4. Infrastructure: KMS keys, Lambda functions, and IAM permissions

Prerequisites

• Node.js 18.x or later
• AWS CLI configured with appropriate credentials
• AWS CDK CLI installed globally
• TypeScript knowledge

Installation

1. Clone the repository and navigate to the project directory:

   cd aws-kaia-rewards

2. Install dependencies:

   npm install

3. Install CDK globally (if not already installed):

   npm install -g aws-cdk

Configuration

Environment Variables

Set the following environment variables:

export KAIA_NETWORK=mainnet  # or testnet
export AWS_REGION=us-east-1
export CDK_DEFAULT_ACCOUNT=your-aws-account-id
export CDK_DEFAULT_REGION=your-aws-region

KMS Key Configuration

Option 1: Use Existing KMS Key (Recommended)

export KMS_KEY_ID=your-existing-kms-key-id-or-arn

This will use an existing KMS key instead of creating a new one. You can specify either:

• Key ID: 5bb59668-5613-4104-bf93-08f619dca565
• Full ARN: arn:aws:kms:us-east-1:123456789012:key/5bb59668-5613-4104-bf93-08f619dca565

Option 2: Import Private Key (Creates New Key)

export PRIVATE_KEY=your-private-key-here

This will create a new KMS key and import your private key.

Option 3: Auto-create New Key If neither KMS_KEY_ID nor PRIVATE_KEY is set, CDK will automatically create a new KMS key.

RPC URLs (Optional)

You can customize RPC endpoints by setting:

export KAIA_MAINNET_RPC_URL=https://your-mainnet-rpc-url
export KAIA_TESTNET_RPC_URL=https://your-testnet-rpc-url
export CUSTOM_RPC_URL=https://your-custom-rpc-url

Development

Building the Project

npm run build

CDK Operations

# Synthesize CloudFormation template
npm run synth

# Deploy the stack
npm run deploy

# Destroy the stack
npm run destroy

# Show differences
npm run diff

# Bootstrap CDK (first time only)
npm run bootstrap

Usage

Lambda Function Operations

The Lambda functions support the following operations:

Basic Kaia Client (kaia-kms-client)

• status: Get Kaia address from KMS public key
• send: Create and sign a transaction
• sign: Sign a transaction (same as send)
• personal_sign: Sign a personal message
• eth_sign: Sign a message hash
• verify: Verify a signature
• balance: Get account balance

Kaia Multisend Client (KaiaMultisendClient)

• status: Get Kaia address from KMS public key
• approve_token_and_send: Approve token spending and create transaction
• multisend_token_and_send: Send tokens to multiple recipients
• multisend_ether_and_send: Send native KAIA to multiple recipients
• get_transaction_status: Check transaction status
• balance: Get account balance

KMS Import Lambda (KMSImportLambda)

• Purpose: Import existing Kaia private keys into AWS KMS
• Input: Private key, key description, and AWS region
• Output: KMS Key ID and ARN
• Usage: One-time operation for migrating existing keys to AWS KMS

Example API Calls

Get Account Status

{
  "operation": "status"
}

Send Single Transaction

{
  "operation": "send",
  "dst_address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "amount": "0.001",
  "nonce": 0
}

Approve Token and Send

{
  "operation": "approve_token_and_send",
  "tokenAddress": "0x1234567890123456789012345678901234567890",
  "amount": "1000000000000000000"
}

Multisend Token and Send

{
  "operation": "multisend_token_and_send",
  "tokenAddress": "0x1234567890123456789012345678901234567890",
  "recipients": [
    "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "0x8ba1f109551bD432803012645Hac136c"
  ],
  "amounts": ["1000000000000000000", "2000000000000000000"]
}

Multisend Ether and Send

{
  "operation": "multisend_ether_and_send",
  "recipients": [
    "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "0x8ba1f109551bD432803012645Hac136c"
  ],
  "amounts": ["1000000000000000000", "2000000000000000000"],
  "value": "3000000000000000000"
}

Get Transaction Status

{
  "operation": "get_transaction_status",
  "txHash": "0x1234567890abcdef..."
}

Security

• KMS keys are configured with ECC_SECG_P256K1 specification for Kaia compatibility
• Lambda functions have minimal IAM permissions (only KMS GetPublicKey and Sign)
• Private keys are never exposed in the code
• All cryptographic operations are performed by AWS KMS

Network Support

• Kaia Mainnet: Production Kaia network (Chain ID: 8217)
• Kaia Testnet: Test Kaia network (Chain ID: 1001)
• Custom Networks: Support for custom RPC endpoints

Error Handling

The Lambda functions include comprehensive error handling:

• Input validation for all operations
• Detailed error messages for debugging
• Proper HTTP status codes
• CORS headers for web integration

Monitoring and Logging

• CloudWatch logs for all Lambda executions
• Structured logging with operation details
• Error tracking and debugging information
• Performance metrics via CloudWatch

Cost Considerations

• KMS charges per API call
• Lambda execution time and memory
• Data transfer costs for RPC calls
• Consider using provisioned concurrency for high-traffic scenarios

Troubleshooting

Common Issues

1. KMS Permission Errors: Ensure Lambda execution role has proper KMS permissions
2. RPC Connection Issues: Check RPC endpoint URLs and network connectivity
3. Signature Verification Failures: Verify message format and hash calculation
4. Transaction Failures: Check gas limits, nonce values, and account balances

Debug Mode

Enable debug logging by setting:

export LOG_LEVEL=DEBUG

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT-0 License. See the LICENSE file for details.

Support

For issues and questions:

• Check the CloudWatch logs for detailed error information
• Verify AWS credentials and permissions
• Ensure all environment variables are set correctly
• Review the CDK deployment logs for infrastructure issues

Related Resources

• AWS KMS Documentation
• Kaia Network Documentation
• AWS CDK Documentation
• Ethers.js Documentation
• Kaia Multisend Contract