TON KMS Lambda

A comprehensive AWS Lambda solution for TON blockchain operations using AWS KMS for secure ed25519 key management and signing. This project provides multi-send functionality compatible with TON Wallet V5 using TonClient.

Features

• 🔐 Encryption-at-Rest: Mnemonic stored in AWS Secrets Manager with KMS CMK encryption
• 🔑 Fine-grained Access Control: IAM roles control who can decrypt secrets
• 🌐 TON Blockchain Support: Native support for TON mainnet and testnet
• 📧 Multi-Send Capability: Send transactions to multiple recipients in a single transaction (Wallet V5 style)
• ⚡ Lambda Functions: Scalable serverless operations
• 🛡️ Security: Private keys encrypted with KMS CMK, never stored in plaintext
• 📝 TypeScript: Complete type safety and modern development experience

Architecture

graph TB
    A[Client Application] --> B[API Gateway]
    B --> D[TON Multi-Send Lambda]
    D --> E[AWS Secrets Manager]
    D --> F[TON Blockchain]
    E --> G[KMS CMK]
    G --> H[Encrypted Mnemonic]

    subgraph "Encryption at Rest"
        E
        G
        H
    end

    subgraph "Access Control"
        I[IAM Role] --> D
        I --> J[kms:Decrypt Permission]
    end

Loading

Project Structure

ton-kms-lambda/
├── bin/                    # CDK app entry point
├── lib/                    # CDK stack definitions
├── src/
│   ├── lambda/
│   │   └── functions/      # Lambda function implementations
│   │       └── ton-multisend/ # Multi-send operations
│   └── utils/              # Shared utilities
├── scripts/                # Build and deployment scripts
├── tests/                  # Test files
└── docs/                   # Documentation

Prerequisites

• AWS Account with CDK permissions
• Node.js 18+
• AWS CLI configured
• TON blockchain access (mainnet/testnet)

Installation

1. Clone and setup:

   cd ton-kms-lambda
   npm install

2. Configure environment:

   cp env.template .env
   # Edit .env with your configuration

3. Build the project:

   npm run build

Configuration

Create a .env file with the following parameters:

# AWS Configuration
AWS_REGION=ap-southeast-1
 AWS_ACCOUNT_ID=123456789012

# TON Network Configuration
TON_NETWORK=mainnet
TON_RPC_URL=https://toncenter.com/api/v2/jsonRPC
TON_API_KEY=your_ton_api_key_here

# KMS Configuration (choose one)
# Option 1: Use existing KMS key
KMS_KEY_ID=your_existing_kms_key_id_here

# Option 2: Import from mnemonic (recommended)
MNEMONIC=your_24_word_mnemonic_phrase_here

# Legacy: Direct decrypt key (not recommended for production)
# DECRYPT_KMS_KEY=your_decrypt_key_here

Deployment

1. Bootstrap CDK (first time only):

   npm run bootstrap

2. Deploy the stack:

   npm run deploy

3. Check outputs:

   npm run synth

Usage

TON Multi-Send Lambda

Multi-send operations for batch transactions:

// Multi-send transaction
{
  "operation": "multisend",
  "recipients": [
    {
      "to": "EQD...",
      "value": "1000000000",
      "comment": "Payment 1"
    },
    {
      "to": "EQD...",
      "value": "2000000000",
      "comment": "Payment 2"
    }
  ],
  "seqno": 1,
  "timeout": 1640995200
}

Supported Operations

TON Multi-Send Lambda Operations

• multisend: Send to multiple recipients in one transaction
• status: Get multi-send configuration and limits
• format_amount: Format amount in readable format

Key Features

Wallet V5 Multi-Send Support

This implementation supports TON Wallet V5 multi-send transactions:

• Multiple Recipients: Send to up to 254 recipients per transaction
• Individual Comments: Each recipient can have a unique comment
• Efficient Gas Usage: Single transaction fee for multiple sends
• Secure Pending: All transactions signed by AWS KMS ed25519 keys

Security Features

• Encryption at Rest: Mnemonic stored in Secrets Manager with KMS CMK encryption
• Fine-grained Access Control: Only Lambda functions with kms:Decrypt permission can access secrets
• No Plaintext Storage: Private keys never stored in plaintext anywhere
• IAM-based Security: AWS IAM roles control access to encrypted secrets
• ed25519 Signatures: Industry-standard elliptic curve cryptography
• Input Validation: Comprehensive validation of addresses, amounts, and parameters
• Error Handling: Robust error handling and logging

Encryption-at-Rest Flow

The system implements a secure encryption-at-rest flow for storing TON wallet mnemonics:

1. Storage Phase:

   • Mnemonic is stored in AWS Secrets Manager
   • Secrets Manager uses a KMS CMK (Customer Managed Key) for encryption
   • Data exists only as ciphertext in the database

2. Access Phase:

   • Lambda function calls secretsmanager:GetSecretValue
   • Secrets Manager retrieves ciphertext from database
   • Secrets Manager sends ciphertext to KMS for decryption
   • KMS only returns plaintext if Lambda has kms:Decrypt permission

3. Access Control:

   • Only Lambda functions with proper IAM roles can decrypt secrets
   • Even AWS console admins cannot read secrets without kms:Decrypt permission
   • Fine-grained control over who can access encrypted data

Development

Adding New Operations

1. Update TonUtils class in src/utils/ton-utils.ts
2. Add operation handler in Lambda functions
3. Update tests
4. Document new operation

Testing

# Run all tests
npm run test:all

# Test specific operations
npm run test:ton-signatures
npm run test:multisend

Troubleshooting

Common Issues

1. KMS Key Issues:

   • Ensure KMS key exists and has correct permissions
   • Check key spec is ECC_SECG_P256K1 for ed25519 compatibility

2. TON Network Issues:

   • Verify TON_RPC_URL is accessible
   • Check TON_API_KEY if required

3. Lambda Timeout:

   • Increase timeout for large multi-send operations
   • Check memory allocation

Contributing

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

License

MIT-0 License - see LICENSE file for details.

Support

For issues and questions:

• Create GitHub issues
• Check documentation in /docs
• Review troubleshooting section

Security Notice

This software is for educational and development purposes. Before using in production:

1. Audit all code thoroughly
2. Test extensively on testnet
3. Review AWS KMS security best practices
4. Implement proper monitoring and alerting
5. Follow TON security guidelines