Skip to main content

Alias Transactions

Stardust introduces a new output type called Alias Output that is essentially a UTXO state machine. Simply put, this represents a new type of ledger account suitable for committee ran smart contract chains. The main features are:

  • storage of state commitments of the second-layer smart contract chains,
  • globally unique address assigned upon creation,
  • different account privileges for two controllers that can be rotated, and
  • ability of issuing custom tokens that are linked to the unique address.

Alias outputs can be created by anyone in the protocol via transactions. A newly created alias receives a unique identifier, called Alias ID, generated by the protocol based on the content of the creating transaction. Once an alias output is created, only its controllers are able to unlock it in subsequent transactions.

Depending on which controller unlocks it, different commands or state mutations are possible. The State Controller is allowed to change the state data stored in the output and also to manipulate token balances of the alias account. One restriction of the State Controller is that whenever it unlocks the alias output in a transactions, it must transition the alias into its new state, meaning the alias output must appear in the transaction as a created output.

The Governor on the other hand might choose to destroy the alias by not creating its subsequent state as an output in the transaction. It also has the power to change the controller entities.

Funds can be sent directly to the unique alias address (derived from Alias ID) of the alias by anyone. Since this address is generated by the protocol, it doesn't have a private key that could be used for signing transactions to prove ownership. So how does one prove that they own the funds locked under an alias address?

The trick is to require the unlocking of the alias output that defines the address in the same transaction that tries to unlock funds sitting on the alias address. If you can prove you own the alias account by successfully unlocking its alias output in a transaction, you can access the funds locked under its address.

Creating an Alias

Just like a regular Basic Output, an Alias Output also has:

  • Amount to hold base token
  • Unlock Conditions that define how the output can be unlocked
  • Features that don't modify the unlocking.

On top of these, it also defines:

  • State Index that has to be incremented in every transaction initiated by the State Controller.
  • State Metadata that may hold binary data,
  • Foundry Counter that defines how many foundries the alias has already created,
  • Immutable Features that are regular Features defined upon creation which can never be modified afterwards.

Alias outputs only support two type of unlock conditions:

  • State Controller Address Unlock Condition that defines the state controller, and
  • Governor Address Unlock Condition that defines the governor of the alias.

Transaction A shows the process of creating a new alias output and hence an alias account. Notice the creation constraints enforced by the protocol:

  • Alias ID must be zeroed out. This signals to the protocol that the alias account is new and when the transaction confirms, a unique Alias ID must be generated.
  • State Index must be zero as this is the first possible state the alias represents.
  • Foundry Counter must be zero as the alias doesn't control any foundries yet.
  • Issuer and Sender addresses must be unlocked in the transaction if present.

Transaction A - Creating an Alias

When Alias Output #1 from Transaction A is consumed in a subsequent transaction, the Alias ID field in the transitioned alias must be set to the protocol generated unique identifier, which is the Blake2b-256 hash of the Output ID of Alias Output #1.

State Transition

Transaction B represents a state transition of the alias. As the name suggests, a state transition must be initiated by the State Controller, therefore it is the stateControllerAddress that needs to sign the transaction. During a state transition, the following constraints need to be met:

  • the alias can't be destroyed,
  • token balances of the output may be changed, the State Controller can transfer funds in- and out of the alias account,
  • State Index must be incremented,
  • State Metadata may be updated,
  • Foundry Counter must be incremented by the number of foundries created in the transaction,
  • Unlock Conditions must not be changed, therefore the state controller can't update ownership of the alias account,
  • Sender Feature may be updated,
  • Metadata Feature must not be updated.

Transaction B - State transition of an alias

Notice how the Alias ID field has to be set in Alias Output #2 to the protocol generated value.

Governance Transition

Transaction C depicts a governance transition of the alias. Such a transaction must be signed by the address in Governor Address Unlock Condition. The constraints for a valid governance transition are:

  • the alias output might be destroyed by the governor (Transaction D),
  • State Controller Address Unlock Condition may be changed,
  • Governor Address Unlock Condition may be changed,
  • Metadata Feature may be changed.

No other fields are allowed to change in the next alias state, therefore a governance transition can't modify token balances or create foundries.

Transaction C - Governance transition of an alias

Destroying an Alias

Transaction D shows a governance transition that destroys the alias. The storage deposit is refunded to a governor defined address. Keep in mind that once the alias is destroyed, any funds locked in the ledger in other outputs to the address of the alias (derived from Alias ID) are essentially lost, as it is not possible to unlock them ever.

Transaction D - Destroying an alias

Unlocking funds owned by an Alias

An alias account may own funds in the ledger two ways:

  • locked directly in its alias output,
  • locked in other outputs to the address of the alias.

The global alias address is derived from the unique Alias ID. Technically, the alias address is the concatenation of the Alias Address Type and the Alias ID. A practical example from TIP-31:

  • Output ID (34-byte) that created the alias: 52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c6490000
  • Alias ID, BLAKE2b-256 hash (32-byte): fe80c2eb7c736da2f7c98ecf135ee9e34e4e076afe6e1dfebc9ec578b8f56d2f
  • Serialized alias address (33-byte): 08fe80c2eb7c736da2f7c98ecf135ee9e34e4e076afe6e1dfebc9ec578b8f56d2f
  • Bech32 string:
    • IOTA (64-char): iota1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj76j6rev
    • IOTA Testnet (64-char): atoi1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj7autzrp
    • Shimmer (63-char): smr1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj7dzrr0a
    • Shimmer Testnet (63-char): rms1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj7e9ge5y

Anyone can send funds in the ledger to the address of the alias, while only the current state controller is able to unlock such funds by including the alias itself in the very same transaction. An alias address doesn't have a private key for signing unlocks, therefore one has to prove that they can unlock the alias output that created the alias address.

Transaction E shows the process of alias unlocking. Basic Output #3 holds funds that are locked to the address of the alias. The state controller initiates a state transition and included the basic output in the same transaction. The Unlock for Basic Output #3 is an Alias Unlock that references the Unlock of the alias that defines aliasAddress.

Important to note, that an Alias Unlock may only reference an unlock at a lower index within the transaction to prevent circular unlocking without any signature. Due to this reason, it is possible to intentionally deadlock aliases by locking them to each other's alias address. Clients should implement safety mechanisms to prevent accidental user errors.

Transaction E - Consuming Alias owned funds