<!-- tempo-docs-context -->
> Source: [/docs/accounts/account-configuration/account-upgrade](https://tempo.com/developers/docs/accounts/account-configuration/account-upgrade.md)
> Section: [Accounts](https://tempo.com/developers/docs/accounts.md). Create accounts, set up signing methods, policies, access keys, key rotation, and fees, and follow guides for users, automations, agents, and teams.
> [Documentation index](https://tempo.com/developers/llms.txt) · [Docs skill](https://tempo.com/developers/SKILL.md)

> Tempo MCP: Use `search`, `find_pages`, `read_page`, and `code` at `https://mcp.tempo.xyz` for Tempo and related documentation.
> If an indexed page is missing or reflects an older site, read this site’s [documentation index](https://tempo.com/developers/llms.txt) and Markdown pages directly.

# Account Upgrade

Adds backup signers to a single-key account without changing its address.

## Overview

An account upgrade turns a single-key account into a configurable account at the same address. A configurable account has several signers and a threshold. A single-key account works like a standard Ethereum account (an EOA). One key controls it, so losing that key loses the account. The upgrade is permanent.

:::warning
**Multiple signers arrive with the [T14 network upgrade](https://tempo.com/developers/docs/protocol/upgrades/t14).** Until T14 activates, an account with several signers and a threshold runs only on the [Tempo Accounts devnet](https://tempo.com/developers/docs/accounts/create#connect-to-the-devnet), not on mainnet or testnet, and may still change.
:::

Until T14, the upgrade transaction does nothing on mainnet or testnet. It succeeds and charges its fee, but the original key still approves alone. Tempo rejects transactions from the configurable account.

In the interactive web page, create a private-key account on the Tempo Accounts devnet, fund it from the faucet, and pay 1 AlphaUSD with it. Then upgrade it in place to a configurable account with the original key and a new backup key as signers and a threshold of 2. A payment signed by the original key alone is rejected, and a payment approved by both signers succeeds. The address and balance stay the same. Each step is a real devnet transaction.

<span id="make-a-single-key-account-recoverable" />

<span id="upgrade-an-existing-account" />

<span id="legacy-account-upgrade" />

<span id="what-an-upgrade-changes" />

<span id="what-changes" />

## Upgrade Effects

The upgrade gives the account a list of signers, each with a weight. It also sets a threshold, the total weight an approval needs. From then on, signers whose weights reach the threshold approve for the account. The original key approves only if you list it, at its weight. The address, balances, token approvals, nonce, contract storage, and access keys with their limits stay the same.

Tempo retires the original key. It can no longer sign transactions, TIP-20 permits, or fee sponsorships for the account, even ones it signed before the upgrade. The upgrade installs a one-byte code marker, so Permit2 and other contracts that check for code route signatures to the account's [ERC-1271 check](https://tempo.com/developers/docs/development/configurable-accounts#verify-owner-approvals-in-a-contract). Contracts that try `ecrecover` before or instead of ERC-1271, such as OpenZeppelin `SignatureChecker` before v5.1, still accept the original key. It also still controls the address on other EVM chains.

<span id="choose-signers-and-threshold" />

## Choose Signers

List the original key and at least one backup signer. A backup can be a passkey on the user's device or a key your recovery provider holds.

| Setup | Threshold | Result |
| --- | --- | --- |
| Original key and one backup, each at weight 1 | 1 | Either key pays alone and replaces the other if it's lost. |
| Three signers at weight 1 | 2 | Every payment needs two approvals. |

In any setup, the signers left after losing any one must still reach the threshold ([Plan for Recovery](https://tempo.com/developers/docs/accounts/account-configuration#plan-for-recovery)).

[Revoke](https://tempo.com/developers/docs/accounts/access-keys/revocation) any access key you don't want before you upgrade.

## Send the Upgrade

The original key signs a transaction with a top-level `upgradeAccount(threshold, owners)` call on Tempo's built-in multisig contract. Call it with `writeContractSync`, and stop unless the client is on the devnet. Set `feeToken` to the stablecoin that pays the fee. Without it, Viem sends a standard Ethereum transaction, and the upgrade reverts with `PrimitiveRootRequired`.

`client.ts` connects to the Tempo Accounts devnet ([set up the devnet key](https://tempo.com/developers/docs/accounts/create#connect-to-the-devnet)).

:::code-group
```ts [upgrade.ts]
import { concat, keccak256, parseAbi, toHex } from 'viem'
import { tempoDevnet } from 'viem/chains'
import { Account, Addresses } from 'viem/tempo'
import { client } from './client'

// Mainnet and testnet accept the transaction but don't upgrade the account.
if (client.chain.id !== tempoDevnet.id) throw new Error('Account upgrades run only on the Tempo Accounts devnet.') // [!code hl]

// The key that controls the account today
const original = Account.fromSecp256k1(process.env.PRIVATE_KEY as `0x${string}`)
// The backup signer's address. Its key stays on the user's device or with your recovery provider.
const backup = '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'

// The account's configuration after the upgrade
const account = Account.fromConfig({ // [!code hl]
  address: original.address, // [!code hl]
  owners: [original, backup], // [!code hl]
  threshold: 1, // [!code hl]
  salt: keccak256(concat([toHex('tempo:configurable-account:upgrade'), original.address])), // [!code hl]
  version: 1n, // [!code hl]
}) // [!code hl]
const { owners, threshold } = account.config

// A test stablecoin on the devnet
const token = '0x20c0000000000000000000000000000000000001'

await client.writeContractSync({ // [!code hl]
  account: original, // [!code hl]
  address: Addresses.nativeMultisig, // [!code hl]
  abi: parseAbi([ // [!code hl]
    'function upgradeAccount(uint8 threshold, (address owner, uint8 weight)[] owners) returns (bytes32)', // [!code hl]
  ]), // [!code hl]
  functionName: 'upgradeAccount', // [!code hl]
  args: [threshold, owners], // [!code hl]
  feeToken: token, // [!code hl]
}) // [!code hl]

// Save account.config. Your app rebuilds the account from it.
```

```ts [client.ts]
import { http } from 'viem'
import { tempoDevnet } from 'viem/chains'
import { createClient } from 'viem/tempo'

// The Tempo Accounts devnet. Its RPC needs a key, which Tempo gives you.
const rpcKey = process.env.TEMPO_DEVNET_RPC_KEY

export const client = createClient({
  chain: tempoDevnet,
  transport: http('https://rpc-stack-mdtgf.devnet.tempoxyz.dev', {
    fetchOptions: { headers: { Authorization: `Basic ${btoa(`previews:${rpcKey}`)}` } },
  }),
})
```
:::

The upgraded configuration uses `version: 1n` and a salt Tempo derives from the address. `account.config` lists the signers sorted by address, as Tempo requires.

After the upgrade, the record your app [saves](https://tempo.com/developers/docs/development/configurable-accounts#keep-the-current-configuration) is the account's only readable list of signers. Each time your app acts for the account, rebuild it from that record with `Account.fromConfig`. Attach the keys that approve, such as `original`. The other signers stay as addresses.

Viem signs with the attached keys until their weights reach the threshold. If they fall short, it throws `Local owners do not meet the threshold.` and sends nothing. Approvals can also come from [separate devices](https://tempo.com/developers/docs/accounts/policies/signing-thresholds#approvers-on-separate-devices).

[Adding](https://tempo.com/developers/docs/accounts/account-configuration/configuration-updates#add-a-signer) or [removing](https://tempo.com/developers/docs/accounts/account-configuration/configuration-updates#remove-a-signer) signers later raises the version. After the update succeeds, save `AccountConfig.update(saved.config, nextConfig)` and rebuild the account from it. Otherwise the next transaction fails with `multisig configuration commitment mismatch`.

<span id="account-upgrade-limits" />

## Limits

* Only the original key can sign the upgrade. Access keys can't, but a [fee payer](https://tempo.com/developers/docs/accounts/fees/fee-sponsorship) can sponsor it.
* The upgrade must be a top-level call, with no EIP-7702 authorization list. It can sit anywhere in a batch. Calls before it run under the original key, and calls after it see the new signers.
* Accounts with contract code, an EIP-7702 delegation, or existing signers can't upgrade.
* Afterward, a direct signature from the original key fails with `RootKeyRetired` (`primitive root key retired`). Sign with the account rebuilt from the saved configuration instead.

## Related

[Account Configuration](https://tempo.com/developers/docs/accounts/account-configuration): Covers signers, weights, thresholds, and recovery planning.

[Configuration Updates](https://tempo.com/developers/docs/accounts/account-configuration/configuration-updates): Use for adding, removing, or replacing signers after the upgrade.

[Signing Thresholds](https://tempo.com/developers/docs/accounts/policies/signing-thresholds): Covers how signer weights approve a transaction.

[Single-Key Accounts](https://tempo.com/developers/docs/development/single-key-accounts#upgrade-to-a-configurable-account): Covers the protocol reference for the upgrade to a configurable account.
