AWS KMS Wallet, Signer and Connectors

This package contains all the necessary entities to perform the execution of Ethers Wallet and Signer with AMS KMS.

This includes somes connectors to perform easy execution of Chainlink related operations, and additional key rotation functionality.

A handler system allows for integration within a Lambda function.

Setup

npm install @raac/aws-kms-connectors

The system expects a series of environment variables to be set.
See the .env.example file for the required variables.

Primitives

KMSWallet: Ethereum wallet and signer implementation using AWS KMS.

import { KMSWallet } from '@raac/aws-kms-connectors';

const wallet = KMSWallet.fromKeyId('arn:aws:kms:us-east-1:123456789012:key/your-key-id');
const address = await wallet.getAddress();
const balance = await wallet.getBalance();
const tx = await wallet.send({
    to: '0x...',
    value: '0.1',
    data: '0x...',
});
const signer = await wallet.getSigner();
const signature = await signer.signMessage('Hello, world!');
const isValid = await signer.verifyMessage('Hello, world!', signature);
console.log(isValid);

// Example of performing a approve transaction
const contract = new ethers.Contract('0x779877A7B0D9E8603169DdbD7836e478b4624789', LINK_TOKEN_ABI, wallet);
const receipt = await contract.approve(wallet.address, ethers.parseEther('1'));
console.log(receipt);

API

Instance Methods

• getAddress() - Get derived Ethereum address
• getBalance() - Get ETH balance in wei
• getPublicKey(format?) - Get public key (formats: 'uint8array', 'hex', 'raw')
• send(txParams) - Send ETH transaction with automatic gas management

The send() method accepts:

{
    to: '0x...',           // Recipient address (required)
    value: '0.1',          // ETH amount as string or BigInt (required)
    data: '0x...',         // Transaction data (optional)
    gasLimit: 21000n,      // Gas limit override (optional)
    gasPrice: 20000000000n, // Legacy gas price (optional)
    maxFeePerGas: 20000000000n,     // EIP-1559 max fee (optional)
    maxPriorityFeePerGas: 1000000000n // EIP-1559 priority fee (optional)
}

• getSigner() - Get KMSSigner instance (async)

KMSSigner: Signer for KMS-backed signing operations.

Signer for KMS-backed signing operations.

Methods

• signTransaction(tx) - Sign Ethereum transaction
• signMessage(message) - Sign Ethereum message with prefix
• signWithKMS(digest) - Sign raw digest with KMS
• verifyMessage(message, signature) - Verify signature against message

Mocks

For testing or local development purposes, you can use the mocks (they simulate the AWS KMS behavior using a local private key)

import { FakeKMSWallet } from './src/mocks/FakeKMSWallet.js';

const key = '0x...'; // private key
const wallet = FakeKMSWallet.fromKeyId(key);

const address = await wallet.getAddress();
console.log('Wallet address:', address);

The mock wallet uses the same API as the real wallet, so you should be able to use it in the same way. The only difference is that the fromKeyId method expects a private key instead of a key ID.

AWSRotator: Rotator for AWS KMS keys.

AWS Rotator allows to rotate a KMS Key (via KMSSigner). It uses the KMSWallet.

Utils:

import { utils } from './src/index.js';


utils.canonicalizeSignature(sig)                         // Canonicalize signature format
utils.deriveAddressFromPublicKey(key)                    // Derive address from public key
utils.derivePublicKeyFromPrivateKey(privateKey)          // Derive public key from private key
utils.derSignatureToRSV(der, digest, expectedAddress)   // Convert DER to RSV format (optional: expected address for recovery validation)
utils.derToRaw(derSignature)                             // Convert DER to raw signature
utils.estimateGasLimit(provider, params, from)           // Estimate gas limit
utils.getProvider()                                      // Get provider
utils.initializeProvider()                               // Initialize provider
utils.parseSignature(signature)                          // Parse signature from hex
utils.prepareTransaction(provider, params, from, nonce)  // Prepare transaction
utils.signatureToHex(signature)                          // Convert signature to hex
utils.sleep(ms)                                          // Sleep utility
utils.retryWithBackoff(fn, options)                      // Retry with exponential backoff
utils.rawToDer(rawSignature)                             // Convert raw signature to DER

Connectors

PinataConnector: Connector for Pinata.

Handles IPFS file storage and retrieval through Pinata.

Environment Variables Required:

• PINATA_JWT_SECRET - Your Pinata JWT token
• PINATA_GATEWAY - Your Pinata gateway domain

Usage:

import { PinataConnector } from "./src/connectors/PinataConnector.js";

const pinata = new PinataConnector();
const result = await pinata.uploadFile("test.txt", "file content");
const content = await pinata.readFile(result.cid);

Methods

• uploadFile(filename, content) // Upload a file to Pinata
• readFile(cid) // Read a file from Pinata
• deleteFile(cid) // Delete a file from Pinata
• getFileUrl(cid) // Get the public URL for a file using its CID
• findFileIdByCid(cid) // Find file ID by CID
• listFiles() // List all files in Pinata

ChainlinkVRFConnector: Connector for Chainlink VRF.

Manages Chainlink VRF v2.5 subscriptions

Environment Variables Required:

• RPC_URL - Blockchain RPC endpoint URL
• PRIVATE_KEY - Wallet private key for signing transactions
• CHAINLINK_NETWORK - Network name (ethereum, polygon, arbitrum, optimism, base)
• CHAINLINK_CHAIN - Chain name (mainnet, sepolia, mumbai, etc.)

Usage:

import { ChainlinkVRFConnector } from "./src/connectors/ChainlinkVRFConnector.js";

const vrf = new ChainlinkVRFConnector();

const subscriptions = await vrf.listSubscriptions([
  "102692964286750664259499016255520300419720563719633059324084515380375060412330"
]);

const subscriptionResult = await vrf.createSubscription();
const isOwned = await vrf.isSubscriptionOwned(subscriptionResult.subscriptionId);
const subscriptionDetails = await vrf.getSubscription(subscriptionResult.subscriptionId);

Methods

• fundSubscription(subscriptionId, amount, currency = 'ETH') // Fund the subscription with ETH or LINK
• createSubscription() // Create a new subscription
• isSubscriptionOwned(subscriptionId) // Check if a subscription is owned by us
• getSubscription(subscriptionId) // Get subscription details
• listSubscriptions([subscriptionId]) // List all subscriptions
• cancelSubscription(subscriptionId) // Cancel a subscription
• addConsumer(subscriptionId, consumerAddress) // Add a consumer to a subscription
• removeConsumer(subscriptionId, consumerAddress) // Remove a consumer from a subscription

ChainlinkSecretsConnector: Connector for Chainlink Secrets.

Manages Chainlink Secrets for Chainlink Functions.

Environment Variables Required:

• RPC_URL - Blockchain RPC endpoint URL
• PRIVATE_KEY - Wallet private key for signing transactions
• CHAINLINK_NETWORK - Network name (ethereum, polygon, arbitrum, optimism, base)
• CHAINLINK_CHAIN - Chain name (mainnet, sepolia, mumbai, etc.)

Usage:

import { ChainlinkSecretsConnector } from "./src/connectors/ChainlinkSecretsConnector.js";

const secrets = new ChainlinkSecretsConnector();

const secrets = await secrets.listHostedSecrets();

Methods

• fetchKeys() // Fetch the keys from the Chainlink Functions contract
• listHostedSecrets() // List all hosted secrets
• encryptSecrets(secrets) // Encrypt secrets
• encryptSecretsUrls(urls) // Encrypt secrets URLs
• encryptAndUploadSecrets(secrets) // Encrypt secrets and upload to the DON
• sendEncryptedSecretsToDON(encryptedSecrets, slotId, ttl) // Send encrypted secrets to the DON
• listHostedSecrets() // List all hosted secrets

ChainlinkFunctionsConnector: Connector for Chainlink Functions.

Manages Chainlink Functions for Chainlink Secrets.

Environment Variables Required:

• RPC_URL - Blockchain RPC endpoint URL
• PRIVATE_KEY - Wallet private key for signing transactions
• CHAINLINK_NETWORK - Network name (ethereum, polygon, arbitrum, optimism, base)
• CHAINLINK_CHAIN - Chain name (mainnet, sepolia, mumbai, etc.)

Usage:

import { ChainlinkFunctionsConnector } from "./src/connectors/ChainlinkFunctionsConnector.js";

const functions = new ChainlinkFunctionsConnector();

const subscription = await functions.createSubscription();

Methods

• createSubscription() // Create a new subscription
• listSubscriptions() // List all subscriptions
• getSubscription(subscriptionId) // Get subscription details
• cancelSubscription(subscriptionId) // Cancel a subscription
• addConsumer(subscriptionId, consumerAddress) // Add a consumer to a subscription
• removeConsumer(subscriptionId, consumerAddress) // Remove a consumer from a subscription

Handlers

Rotate Handler

The rotate handler action can be use to pass the encrypted secrets from Instruxi to the Lambda function for rotation.

curl -X POST http://localhost:3000/rotate \
  -H "Content-Type: application/json" \
  -d '{"action": "rotate", "payload": "MDJlODUwNDg0MjM5MTkzYTBjNzExZWQ0ZmMxN2UyNWM4ODYyNjlmOGIzYWUxMjExZDZjMmJlMDdhMDg4Y2FiYWNiYjEyMTVkNTUyODg0ODU3NmJlYmU3MjRiZGE4YmQ5ZmNmMjA5NzUxZDJjM2JhMmQ5ODcwN2VkN2M4M2I3OGNjZmQ1NWZiZGYyOTU5ZGFjNDljYWQzYWFiZGJlZWRkNzRiOTg5NDdiMDRjMDYxMWZlZWUwZjdmYjVkODZkZWQ4ZmRhMzhiZDg5Y2U2MGU0NWM2MDU5YmM4MzlkYWYxCjAyNGRiZTc1MGU5MDk5NDNlNzM2NGQxNTU4NWY2MTBmZGJhYWVmOWM0MTRkNWNkZTVmNGZmNGI3YmU0YjRjNzBjZmRhMGU5MjcwZTlmY2JkMmJiMGJkNDg4MjJjMWM0MDUwZDAxN2U5YWRkYzkxNTJhOTJiN2UwMjNmMjg4YWYxNWNlYTJiZWU0NjAyNmQxNjgyYWM0ZGEzMTQyYzNlOWI5ZTFhMzAzY2NiOGIyM2IwZDZmMzc5MzY0ZjFjMjc0NGFlYTEzZDA2NWRhNjU2MmRiNTUyOWZiYzJiNTZlNTBmYTQ4OAowMzdmZmU0N2I3OGE5ZTg3MDA4OTMwYjkwNDFkM2E0ZjY5ZGU4MTI5MTRiN2I0MDU2NTJlODA5MjkwZjYyYzIyOGUwNDQyYTBlMmMxMDE3ZTc5NTNjM2UzYmQxNDljNGQ0MzBlOWQ1NDFjZjgyYTU4NDUwODU0NDczM2U4MTE2MDFlMDhjYmJhN2M1YTRhMzA5ZjU3N2JkNGU0MGY4ZTViOTczNzhmNjAyZDhiOGQ5ZWI1ZTc1ZTA3YzVjYWQ3YjVkNjdlYzM4MWRhZWI5ZTY0Y2ZhN2UyMjk2ODJmCjAzMjI4ZjcxMzhkNjFlZmRhYjk3MWU1ZDc0MGIzM2M2MTA4YTJhYjAzYWViMzYwMjE2MDFiYzQ5Y2YyNmI0NTg3OGM5ZjgwNjY1ODVjNGNhOTRjNzYwZThkMDFhMmNiOTBmODExMjRjYWMxZDk2Yjc1NzgwNWNiZWEwMTdiYTAxNjM3NmM0Mjc1MzA3MTE2NTAxNTQzNzY2NmUyNmI1YjIwMWYwZTRlZjMwNzU4YWJmYTI0ODBmYzU4ZGIyY2YwOTQxNDFmYzYwN2UKMDM2YWYxYjdhN2MxOWFmOWZhZDBkNDE1ZDVhZjdhOWZkYjg4Y2ZhZmM5ZDNkNWU5NjJjZTYxMTIwNDM1N2E4MzExZTA2NWQyMDVjMTM1OGNlZTg2MDM1ZjIzZTU1N2U3OTFkYWQ2NGQxMTg0ODg0YzA2MDNlNzFmNzdiNmI2ZDA5N2QzNzcwY2VlMzVlMzIzMWE1MDdiNzJjM2Q2NjVmY2U0NzgzNjgyODNhMTI3NWI3MzZjZTA4ZjYxMGExOTQ2ZDhjMA=="}'

Prices Handler

curl -X POST http://localhost:3000/prices \
  -H "Content-Type: application/json" \
  -d '{"action": "prices", "payload": "MDJlODUwNDg0MjM5MTkzYTBjNzExZWQ0ZmMxN2UyNWM4ODYyNjlmOGIzYWUxMjExZDZjMmJlMDdhMDg4Y2FiYWNiYjEyMTVkNTUyODg0ODU3NmJlYmU3MjRiZGE4YmQ5ZmNmMjA5NzUxZDJjM2JhMmQ5ODcwN2VkN2M4M2I3OGNjZmQ1NWZiZGYyOTU5ZGFjNDljYWQzYWFiZGJlZWRkNzRiOTg5NDdiMDRjMDYxMWZlZWUwZjdmYjVkODZkZWQ4ZmRhMzhiZDg5Y2U2MGU0NWM2MDU5YmM4MzlkYWYxCjAyNGRiZTc1MGU5MDk5NDNlNzM2NGQxNTU4NWY2MTBmZGJhYWVmOWM0MTRkNWNkZTVmNGZmNGI3YmU0YjRjNzBjZmRhMGU5MjcwZTlmY2JkMmJiMGJkNDg4MjJjMWM0MDUwZDAxN2U5YWRkYzkxNTJhOTJiN2UwMjNmMjg4YWYxNWNlYTJiZWU0NjAyNmQxNjgyYWM0ZGEzMTQyYzNlOWI5ZTFhMzAzY2NiOGIyM2IwZDZmMzc5MzY0ZjFjMjc0NGFlYTEzZDA2NWRhNjU2MmRiNTUyOWZiYzJiNTZlNTBmYTQ4OAowMzdmZmU0N2I3OGE5ZTg3MDA4OTMwYjkwNDFkM2E0ZjY5ZGU4MTI5MTRiN2I0MDU2NTJlODA5MjkwZjYyYzIyOGUwNDQyYTBlMmMxMDE3ZTc5NTNjM2UzYmQxNDljNGQ0MzBlOWQ1NDFjZjgyYTU4NDUwODU0NDczM2U4MTE2MDFlMDhjYmJhN2M1YTRhMzA5ZjU3N2JkNGU0MGY4ZTViOTczNzhmNjAyZDhiOGQ5ZWI1ZTc1ZTA3YzVjYWQ3YjVkNjdlYzM4MWRhZWI5ZTY0Y2ZhN2UyMjk2ODJmCjAzMjI4ZjcxMzhkNjFlZmRhYjk3MWU1ZDc0MGIzM2M2MTA4YTJhYjAzYWViMzYwMjE2MDFiYzQ5Y2YyNmI0NTg3OGM5ZjgwNjY1ODVjNGNhOTRjNzYwZThkMDFhMmNiOTBmODExMjRjYWMxZDk2Yjc1NzgwNWNiZWEwMTdiYTAxNjM3NmM0Mjc1MzA3MTE2NTAxNTQzNzY2NmUyNmI1YjIwMWYwZTRlZjMwNzU4YWJmYTI0ODBmYzU4ZGIyY2YwOTQxNDFmYzYwN2UKMDM2YWYxYjdhN2MxOWFmOWZhZDBkNDE1ZDVhZjdhOWZkYjg4Y2ZhZmM5ZDNkNWU5NjJjZTYxMTIwNDM1N2E4MzExZTA2NWQyMDVjMTM1OGNlZTg2MDM1ZjIzZTU1N2U3OTFkYWQ2NGQxMTg0ODg0YzA2MDNlNzFmNzdiNmI2ZDA5N2QzNzcwY2VlMzVlMzIzMWE1MDdiNzJjM2Q2NjVmY2U0NzgzNjgyODNhMTI3NWI3MzZjZTA4ZjYxMGExOTQ2ZDhjMA=="}'

Ciphers

Encrypting / Decrypting Secrets and Key pair generation

Generate a key pair:

import { generateKeyPair } from "./src/ciphers/crypto/keygen.js";

const { privateKey, publicKey } = generateKeyPair();

We can then share the public key with Instruxi for them to encrypt the secrets.

Encrypt and decrypt secrets:

import { encryptSecrets } from "./src/ciphers/encryptSecrets.js";
import { decryptSecrets } from "./src/ciphers/decryptSecrets.js";

const secrets = ["SECRET1=value1", "SECRET2=value2"];
const privateKey = Buffer.from(process.env.ENCRYPT_PRIVATE_KEY, 'hex');
const publicKey = Buffer.from(process.env.ENCRYPT_PUBLIC_KEY, 'hex');
const encryptedSecrets = await encryptSecrets(secrets, publicKey);
const decryptedSecrets = await decryptSecrets(encryptedSecrets, privateKey);

License

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