Skip to content

README.md

Latest commit

 

History

History
270 lines (197 loc) · 6.62 KB

README.md

File metadata and controls

270 lines (197 loc) · 6.62 KB

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