AWS Wallet Upgrade

For AI agents: visit https://vault.docs.blockdaemon.com/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI.

📘

Note:

The upgrade process may take up to an hour. Plan a maintenance window accordingly.

AWS production deployments run on Amazon ECS (not Kubernetes Helm). Roll back by redeploying a prior release bundle with the Makefile targets below, or restore RDS when schema migrations require it.

Prerequisites

Before starting the upgrade, complete the general pre-upgrade checklist:

  1. Review the release changelog for breaking changes and migration steps.
  2. Take a database backup per the System Backup and Restore Process.
  3. Confirm all ECS services and Policy Node Nitro instances are healthy.
  4. Retain the previous installer bundle (Makefile, customer-config.yml, bd-wallet.yml, and deployer version) so you can redeploy if rollback is needed.

Upgrade procedure

  1. Sync the installer bundle for the target wallet release tag:
export CUSTOMER_SHARED_SEGMENT=<target-wallet-release-tag>
export DEPLOYER_VERSION=<target-deployer-version>
export MPA_IMAGE_TAG=<target-policy-node-enclave-tag>
export NAMESPACE=<your-namespace>
export ENV_PREFIX=<environment-name>
export AWS_REGION=<region>
export BACKEND_API_PATH=https://api.<env>.wallet.example.com
PULL_SYNC_MAKEFILE=1 make pull-customer-assets
  1. Pull the deployer image:
make pull-deployer
  1. Refresh deployment configuration for the new release:
    • Update customer-config.yml if Blockdaemon supplied changes, then run make generate-customer-assets, or
    • Merge release notes into your existing bd-wallet.yml and run make generate-conf-files.
  2. Optional but recommended: create an RDS snapshot before applying CDK changes:
export RDS_DB_INSTANCE_IDENTIFIER=<your-db-cluster-id>
make backup-rds-snapshot
  1. Run the upgrade targets (service images, conf refresh, wallet stack, Nitro, start):
make prepare-update
make update

prepare-update runs deploy-service-images and generate-conf-files (and attempts backup-rds-snapshot when RDS_DB_INSTANCE_IDENTIFIER is set). update runs deploy-baseline, generate-fe-env, deploy-wallet, deploy-nitro-nodes, and start-wallet.

  1. When the upgrade changes Policy Node enclave artifacts, confirm MPA_IMAGE_TAG matches the EIF under s3://638663786504-prod-mpa-deployment-customer-artifacts/enclave/<MPA_IMAGE_TAG>/ before deploy-nitro-nodes.

📘

Note

Do not re-run populate-secrets-policy-node* on AWS unless Blockdaemon instructs you to rotate Policy Node crypto material. Re-running populate-secrets-wallet overwrites most wallet-partition secrets and can break a live environment.

Post-upgrade verification

After the upgrade completes:

  1. Verify ECS services are running. In the AWS Console (ECS > Clusters > Services) or CLI:
aws ecs list-services --cluster <cluster-name>
aws ecs describe-services --cluster <cluster-name> --services <service-name>
  1. Check the wallet health endpoint:
curl -s https://<your-wallet-domain>/health
  1. Confirm ECS task definition image tags match the target release.
  2. Smoke test: list accounts and view balances in the UI or API.

Rollback procedure

If the upgrade fails or the wallet is not healthy after deployment:

Option 1: Redeploy previous version (no incompatible schema migration)

Restore the previous Makefile variables and bundle, then:

make pull-deployer
make prepare-update
make update

Wait for services to stabilize, then repeat post-upgrade verification.

Option 2: Full rollback (schema migrations applied)

If the new version applied database migrations incompatible with the previous version:

  1. Redeploy the previous application version as in Option 1.
  2. Restore the database from the pre-upgrade backup per the System Backup and Restore Process.
  3. Restart services in order: NATS, Policy Nodes, then wallet.
  4. Verify health and functionality.

📘

Note

After a database restore, transactions between the backup time and restore time are lost. On-chain balances reconcile on the next indexer pass.

Configuration-only changes (no version bump)

When you change bd-wallet.yml without upgrading images:

make generate-conf-files
make deploy-wallet

Add make deploy-nitro-nodes when Policy Node configuration changed. See Step 14 in the AWS deployment process.

Troubleshooting

See Installation Troubleshooting and the general Troubleshooting Guide.