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](https://vault.docs.blockdaemon.com/docs/how-to-perform-wallet-upgrade#before-you-upgrade):

1. Review the [release changelog](https://vault.docs.blockdaemon.com/changelog) for breaking changes and migration steps.
2. Take a database backup per the [System Backup and Restore Process](https://vault.docs.blockdaemon.com/docs/wallet-state-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:

```shell
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
```

2. Pull the deployer image:

```shell
make pull-deployer
```

3. 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`.
4. Optional but recommended: create an RDS snapshot before applying CDK changes:

```shell
export RDS_DB_INSTANCE_IDENTIFIER=<your-db-cluster-id>
make backup-rds-snapshot
```

5. Run the upgrade targets (service images, conf refresh, wallet stack, Nitro, start):

```shell
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`.

6. 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:

```shell
aws ecs list-services --cluster <cluster-name>
aws ecs describe-services --cluster <cluster-name> --services <service-name>
```

2. Check the wallet health endpoint:

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

3. Confirm ECS task definition image tags match the target release.
4. 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:

```shell
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](https://vault.docs.blockdaemon.com/docs/wallet-state-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:

```shell
make generate-conf-files
make deploy-wallet
```

Add `make deploy-nitro-nodes` when Policy Node configuration changed. See [Step 14](https://vault.docs.blockdaemon.com/docs/aws-ecs-deployment-process#step-14-apply-configuration-changes-after-install) in the AWS deployment process.

## Troubleshooting

See [Installation Troubleshooting](https://vault.docs.blockdaemon.com/docs/installation-troubleshooting) and the general [Troubleshooting Guide](https://vault.docs.blockdaemon.com/docs/troubleshooting-guide).