Skip to main content

Address Aliases

Address aliases can be used to configure the set of keys that are allowed to sign transactions for a particular address on the Sui network.

You can use address aliases to:

  • Perform simple key rotation for an address.
  • Grant multiple signers full access to everything owned by an address.
  • Implement more complicated authentication schemes, such as smart wallets with passkeys.
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 any changes to your aliases! Any new alias you add effectively becomes a joint owner of your address.

How aliases work​

Each address on Sui has a set of aliases. New addresses begin as their own alias. That is, a new address A has the alias set {A}.

You can modify aliases for an address using the Move API in the sui::address_alias module. These modification functions must be invoked as top-level PTB commands and cannot be called from other Move functions.

Some constraints for modifying aliases:

  • An address must always have at least one alias.
  • An address can be removed from its own alias set. For example, you can have an address A which only allows signatures from {B, C}.
  • The maximum number of allowed aliases for an address is 8.

Authenticating transactions with aliased addresses​

Transactions on Sui are configured with two addresses: a sender and a gas_owner (which might or might not be the same). For each configured address, a signature is required from one of the signers in its alias set.

For example, with the following transaction and aliases:

transaction T {
  sender: A
  gas_owner: X
  ...
}

aliases[A] = {A, B}
aliases[X] = {Y}

To be valid, the transaction T would require a signature from either A or B, and a signature from Y.

In this example, even if the transaction had signatures from [B, Y] and not from A, during execution it would nonetheless have access to everything owned by A, and during Move call execution its TxContext::sender would be A.

Managing aliases with the Sui CLI​

You can manage address aliases using sui client ptb to call entry functions in the sui::address_alias module. The AddressAliasState singleton object lives at the address 0xa.

Enable aliases for your address​

Before modifying aliases, you must enable alias configuration for your address. This creates an AddressAliases object initialized with your own address as the sole alias:

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

Note the object ID of the AddressAliases object in the created objects section of the transaction output. You need this ID for all subsequent alias operations.

Add an alias​

Add another address to your alias set, granting it the ability to sign transactions on your behalf:

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

Replace all aliases​

Overwrite the entire alias set with a new set of addresses using replace_all. For example, to set a single address as the only alias:

$ sui client ptb \
    --move-call sui::address_alias::replace_all \
        @<ADDRESS_ALIASES_OBJECT_ID> \
        vector[@<ALIAS_ADDRESS>] \
    --gas-budget 50000000
warning

If you replace your aliases with a set that does not include your own address, you will no longer be able to sign transactions for your address. Only the addresses in the new alias set will have that ability.

Remove an alias​

Remove a specific address from your alias set:

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

Offline signing​

If you are using a hardware wallet or other external signer, add --serialize-unsigned-transaction to any of the commands above to output the raw transaction bytes instead of executing. You can then sign the transaction offline and submit it separately. See Sui Client PTB CLI for details.