📘

Note:

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

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 services are healthy.
4. Retain the previous release bundle (Makefile and deployer artifacts) so you can redeploy if rollback is needed.

Upgrade procedure

1. Pull the Makefile for the target release version:

   aws s3 cp s3://638663786504-prod-mpa-deployment-customer-artifacts/release/<RELEASE_VERSION>/Makefile .

2. Pull the corresponding deployer bundle:

   make pull-deployer

3. Re-pull your bd-wallet.yml configuration to ensure compatibility with the new version:

   aws s3 cp s3://638663786504-prod-mpa-deployment-customer-artifacts/customer/<your-namespace>/bd-wallet.yml .

4. Run the upgrade:

   make update

Post-upgrade verification

After the upgrade completes:

1. Verify all ECS services are running and tasks are in a RUNNING state. Check via 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>

2. Check the wallet health endpoint:

   curl -s https://<your-wallet-domain>/health

3. Confirm the deployed image tags match the target release version in the ECS task definitions.

4. Perform a smoke test — verify you can list accounts and view balances in the UI or via API.

Rollback procedure

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

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

Re-run the upgrade procedure using the previous release bundle (prior Makefile and deployer artifacts):

aws s3 cp s3://638663786504-prod-mpa-deployment-customer-artifacts/release/<PREVIOUS_VERSION>/Makefile .
make pull-deployer
make update

Wait for all services to stabilize, then re-run the post-upgrade verification steps above.

Option 2: Full rollback (schema migrations applied)

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

1. Redeploy the previous application version using the prior release bundle as shown in Option 1.

2. Restore the database from the pre-upgrade backup following the System Backup and Restore Process.

3. Restart all services in the correct order (NATS → Policy Nodes → Wallet).

4. Verify health and functionality.

📘

Note:

After a database restore, any transactions that occurred between the backup and the restore point will be lost. On-chain balances will reconcile automatically on the next indexer pass.

Troubleshooting

If you encounter issues during or after the upgrade, consult the Troubleshooting Guide for common error codes and resolutions.