Upgrade Universal Account

Overview

Upgrades the UEA (Universal Executor Account) to the latest required implementation version. This is a gasless, signature-based operation and is done automatically via the SDK without requiring gas.

You only need to call this when getAccountStatus() reports uea.requiresUpgrade === true. Sending universal transactions on an outdated UEA will fail.

Note: upgradeAccount() is a no-op if the UEA is already at or above the minimum required version.

Upgrade Universal Account

pushChainClient.upgradeAccount({options?}): Promise<void>

await pushChainClient.upgradeAccount({
  progressHook: (progress) => {
    console.log(`${progress.id}: ${progress.message}`);
  },
});

TheseArgumentsare mandatory

Arguments	Type	Default	Description
options.progressHook	(event: ProgressEvent) => void	undefined	Callback invoked at each upgrade step showing progress.

Progress Hook Type and Response

ProgressHook Type and Response

Field	Type	Description
progress	Object	The progress of the upgrade operation.
progress.id	string	Unique identifier for the progress event.
progress.title	string	Brief title of the progress event.
progress.message	string	Detailed message describing the event.
progress.level	INFO | SUCCESS | ERROR	Severity level of the event.
progress.timestamp	string	ISO-8601 timestamp when the event occurred.

ID	Title	Message	Level
UEA-MIG-01	Checking Status	Fetching current UEA version and upgrade requirement	INFO
UEA-MIG-02	Awaiting Signature	Awaiting user signature for migration payload (EIP-712)	INFO
UEA-MIG-03	Broadcasting	Submitting migration transaction to Push Chain	INFO
UEA-MIG-9901	Upgrade Complete	UEA successfully upgraded to version <new version>	SUCCESS
UEA-MIG-9902	Upgrade Failed	<error message>	ERROR
UEA-MIG-9903	No Upgrade Needed	UEA is already at the required version; operation skipped	INFO

Recommended Usage Pattern

Always check getAccountStatus() before calling upgradeAccount() to avoid unnecessary prompts:

const status = await pushChainClient.getAccountStatus();

if (status.uea.requiresUpgrade) {
  await pushChainClient.upgradeAccount({
    progressHook: (progress) => {
      console.log(`${progress.id}: ${progress.message}`);
    },
  });
}

Live Playground

VIRTUAL NODE IDE

Copy playground link

Copy code

Next Steps

• Check UEA state before upgrading with Get Account Status
• Send your first universal transaction after upgrading with Send Universal Transaction