Wallet Infrastructure (UTXO Management Server)

WALLET INFRASTRUCTURE (UTXO MANAGEMENT SERVER) - USAGE INSTRUCTIONS

This container provides a JSON-RPC HTTP server on port 8080 for BRC-100 compliant BSV wallet clients to store and manage UTXOs. Image: 709825985650.dkr.ecr.us-east-1.amazonaws.com/bsv-blockchain/wallet-infra:<version>

1. PREREQUISITES

• AWS account with permissions to pull from Marketplace ECR and run containers (ECS/EKS/EC2/App Runner).
• MySQL 8.0 database reachable from the container (Amazon RDS recommended). Tables auto-create on first launch.
• Outbound HTTPS to BSV network services; inbound HTTP on port 8080.
• Minimum 0.5 vCPU, 512 MB RAM; recommended 1 vCPU, 1 GB RAM.
• A 32-byte hex private key for the server identity (store in Secrets Manager).

2. CONFIGURATION Set the following environment variables on the container:

• NODE_ENV: production
• BSV_NETWORK: main (or test)
• HTTP_PORT: 8080
• SERVER_PRIVATE_KEY: 64-character hex string (store as a secret)
• KNEX_DB_CONNECTION: JSON string, e.g. {"host":"<rds-endpoint>","user":"wallet_admin","password":"<secret>","database":"wallet_storage","port":3306}
• ENABLE_NGINX: true (recommended for production)

Before first launch, create the database in MySQL: CREATE DATABASE wallet_storage; CREATE USER 'wallet_admin'@'%' IDENTIFIED BY '<password>'; GRANT ALL PRIVILEGES ON wallet_storage.* TO 'wallet_admin'@'%';

3. STEP-BY-STEP DEPLOYMENT (Amazon ECS on Fargate) Step 1: Subscribe on AWS Marketplace, then authenticate Docker: aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com

Step 2: Provision an Amazon RDS for MySQL 8.0 instance in your VPC. Note the endpoint and credentials. Create the wallet_storage database and user as shown above.

Step 3: Store SERVER_PRIVATE_KEY and KNEX_DB_CONNECTION in AWS Secrets Manager. Grant the ECS task execution role permission to read them.

Step 4: Create an ECS task definition using the Marketplace image. Map container port 8080. Inject environment variables, sourcing secrets from Secrets Manager. Set CPU 512, memory 1024.

Step 5: Create a Fargate service in a private subnet with outbound internet (NAT gateway). Place behind an Application Load Balancer with HTTPS listener and target group on port 8080. Health check: HTTP GET / expecting 200.

Step 6: Point a Route 53 record at the ALB and attach an ACM certificate to the HTTPS listener.

4. VERIFYING THE APPLICATION IS RUNNING

• CloudWatch Logs should show: "wallet-storage server started"
• Test the endpoint: curl -X POST https://<your-domain>/ -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"walletUtxoStorage_getHeight","params":[]}' - a JSON response with the current blockchain height confirms the server and database are working.
• Confirm Knex created tables: connect to MySQL, run "USE wallet_storage; SHOW TABLES;" - expect outputs, transactions, baskets, labels, certificates, and others.
• In the EC2 console, confirm ALB target group reports the task as healthy.

5. MONITORING

• CloudWatch Logs: configure awslogs driver on the ECS task; logs go to stdout/stderr.
• CloudWatch Container Insights: enable on the cluster for CPU, memory, and network metrics. Recommended alarms at 80% CPU/memory, and on task count below desired.
• ALB metrics: monitor HealthyHostCount, HTTPCode_Target_5XX_Count, TargetResponseTime (typical under 200ms).
• RDS: enable Enhanced Monitoring and Performance Insights. Watch connection count, slow queries on the outputs table, and storage utilization.
• External health checks: poll GET https://<your-domain>/ for a 200 response.

DOCUMENTATION

• Source and full docs: https://github.com/bitcoin-sv/wallet-infra 
• BRC-100 spec: https://github.com/bitcoin-sv/BRCs/blob/master/wallet/0100.md 

SUPPORT GitHub Issues: https://github.com/bsv-blockchain/wallet-infra/issues