Skip to main content

Address Aliases for Asset Custody

Address aliases let you authorize additional Sui addresses to sign transactions for a Sui address. This page covers how aliases apply to asset custody patterns. For the full API reference and CLI commands, see Address Aliases.

warning

All aliases for a given address have the ability to unilaterally control or take all coins, balances, and other resources owned by the address. Be extremely careful when making changes to your aliases.

How do I enable alias configuration?​

An address alias is another address authorized to sign transactions for your address. Alias configuration is the prerequisite for having aliases: before you can add, remove, or replace aliases for an address, you must first enable alias configuration with sui::address_alias::enable @0xa:

$ sui client ptb \
    --move-call sui::address_alias::enable @0xa \
    --gas-budget 50000000

The enable transaction creates the AddressAliases object. Save its object ID: the add and remove commands on this page take it as their first argument (<ADDRESS_ALIASES_OBJECT_ID>), so you reuse the same ID every time you change the aliases for that address.

How do I rotate keys without migrating assets?​

Traditional key rotation on Sui requires transferring all objects and balances from the old address to the new one. With aliases, assets stay at the original address, and the new address is authorized to act on them as an alias:

  1. Generate a new keypair (new address).

  2. If alias configuration is not already enabled for the old address, enable it (see How do I enable alias configuration?) and save the created AddressAliases object ID.

  3. Add the new address as an alias of the old address:

    $ sui client ptb \
        --move-call sui::address_alias::add \
            @<ADDRESS_ALIASES_OBJECT_ID> \
            @<NEW_ALIAS_ADDRESS> \
        --gas-budget 50000000

No asset migration needed. All objects and balances stay at the original address.

If you remove the old address from its own alias set, the old key can no longer sign for that address. Make sure the replacement key is backed up and working before removing the original address.

How do I authorize an agent with an alias?​

Instead of transferring objects to a trusted agent or operational hot key, add that address as an alias. The alias signs transactions with its own key and is authorized to act as your address, accessing your objects and balances directly. Revoke access by removing the alias:

sui client ptb \
    --move-call sui::address_alias::remove @<ADDRESS_ALIASES_OBJECT_ID> @<AGENT_ADDRESS> \
    --gas-budget 50000000

When should a multisig delegate to a single-key alias?​

A multisig address can add a single-key alias for operational speed. The alias has full sender authority: it can do anything the multisig address can do, including spending assets and changing aliases. Use this pattern only when you trust the alias holder completely and accept that, while the alias is present, the address's effective security is reduced to that single key. To revoke the alias, remove it with sui::address_alias::remove as shown in How do I authorize an agent with an alias?.

Aliases have full authority

An alias address has the same authority as the original address. It can transfer objects, spend balances, call any function as the aliased address, and modify the alias set. Only add aliases for keys you fully trust.

How do I manage aliases?​

The AddressAliasState singleton object lives at address 0xa. Use sui client ptb to call entry functions in the sui::address_alias module. See Address Aliases for the complete CLI reference, including enable, add, remove, and replace_all commands.