| keywords | description | image | |||
|---|---|---|---|---|---|
|
Stardust Ledger Anatomy. |
/img/logo/Chrysalis_logo_dark.png |
The ledger is a distributed database that records ownership of funds in the network. Users modify the ledger by posting transactions to the network that move these funds between user accounts.
IOTA uses the Unspent Transaction Output Model (UTXO) to model ledger entries. A transaction consumes ledger entries (previously created transaction outputs) and creates new ones. When a UTXO is consumed, it is marked as spent and is removed from the database, while newly created UTXOs are added. All currently unspent UTXOs comprise the most recent ledger state.
A UTXO is allowed to be spent if its owner presents a valid digital signature corresponding to the owner of the UTXO that is generally called the owner address. Stardust extends this concept by letting users define additional spending constraints on UTXOs, for example that an output can only be spent after a certain time.
In the following, we will demonstrate with example some common types of transactions and in the meantime we will explore the different kind of constraints and outputs that one might create in the ledger.
A simple transaction moves funds from one user account to another. On a high level, transactions must define 3 things:
- Inputs: previously created unpsent transaction outputs holding funds that the transaction consumes,
- Unlock Blocks: they hold the signatures authorizing the consumption of inputs,
- Outputs: newly created outputs holding transferred funds.
In Stardust a simple transfer may be realized with an output type called Basic Output. Just like every other output type, Basic Outputs define the base token funds they hold in the Amount field. They have to have at least one Unlock Condition defined: the Address Unlock Condition.
It means that in order to unlock the output in a transaction, one has to present a valid signature for the given address. The signature signs the whole content of the transaction, thereby authorizing the consumption of inputs but also declaring the intention to create new outputs.
Transaction A simply:
- consumes as input a Basic Output with 100i locked under ownerAddress,
- provides an Unlock, namely a Signature Unlock that contains a valid signature of the transaction content corresponding to the private key behind ownerAddress,
- creates a new Basic Output with 100i locked under the recipients address, namely recipientAddress.
The first new Unlock Condition we are going to look at is the Expiration Unlock Condition. It lets the creator of the output define an Expiration Deadline. Before the deadline, the recipient can consume and unlock the output in a transaction, but once the deadline expired, only the Return Address defined in the Expiration Unlock Condition can unlock it.
Transaction B defines an output that can only be unlocked by the recipient in a transaction that is confirmed by a milestone where both the Milestone Index and the Milestone Unix Timestamp are less, than the values defined in the Expiration Unlock Condition. Note, that it is possible to set either Milestone Index or Unix Time to zero in order to use only one way of defining the deadline, but both can not be zero.
Transaction C shows how the recipient can consume the output before the deadline and take the funds into full, unconditional custody.
Transaction D depicts how the original sender claims an expired output. Note, that it is not necessary for the sender to sweep the funds into their own wallet, they can just treat it as funds they have full custody of.
With Stardust, it is possible to lock funds away based on time. When an output has a Timelock Unlock Condition defined, not even its rightful owner can unlock it before the timelock expires. Just like in the case of the Transaction C and D, the notion of time in the ledger is determined by the index and timestamp of the milestone that confirms the transaction.
Transaction E creates an output owned by the recipient but timelocked until Milestone Index 1500 and May 24 2022 18:00:00.
The recipient has no way to unlock the output before the deadline. Once the timelock expired, the funds can be moved, as depicted on Transaction F.
Stardust introduces a new system to protect the ledger size and hence node storage resources, called Byte-cost based Storage Deposit System. You can read more about it in TIP-19. In short, every output in the ledger need to carry enough base tokens to cover for its network storage use.
Implicitly this means that an output has to have a minimum amount of base tokens, otherwise it is considered invalid. The exact minimum depends on the size of the output and the protocol parameter Virtual Byte Cost. The implication of this is that is no longer possible to store microfunds in an output. So suppose you wanted to send 1i (0.000001 MIOTA): is it still possible?
The answer is yes. With the Storage Deposit Return Unlock Condition it is possible to define spending constraints on outputs that you create. Let's assume that the minimum amount of funds that need to be present in an output is 100i. If you wanted to send only 1i to the recipient, you would transfer 101i to the recipient's address with the extra condition that she can only use the funds if she refunds you in the very same transaction with 100i.
Transaction G show the creation of an output with Storage Deposit Return Unlock Condition. Notice, that Basic Output #11 holds 101i, and the unlock condition defines the Return Amount of 100i to ReturnAddress ownerAddress. All in all, the recipient can only freely use 1i when she consumes the output in Transaction H.
In order for the recipient to claim the 1i, she needs to sweep it into one of her own outputs. Therefore, she consumes Basic Output #12 in the transaction that holds her funds. On the output side, she has to have Basic Output #13 that refunds the original sender, plus she creates Basic Output #14 into which she sweeps the 1i.
What forces the recipient to post and execute Transaction H? Nothing. She can just keep the sender's 100i in limbo forever. That is why it is handy that you can combine unlock conditions. For example, the sender can add an expiration condition to Basic Output #11. Once the output is expired, the recipient won't be able to claim the 1i and the sender takes full custody of the 101i in the output.
Next to Unlock Conditions, Stardust allows to define optional Features on outputs of a transfer that do not impact the actual unlocking of the created output. The Sender feature is one of such features, which lets the creator of the output define an explicit Sender Address attribute for an output.
The Sender attribute is validated on protocol level. Validation ensures that the transaction that created the output unlocked the Sender address on the input side. Therefore, this feature is a protocol validated proof that the output was created by someone who controls the Sender address.
Transaction J shows how one can add a sender attribute to a created output. Note, that Transaction J would be invalid if:
- Basic Output #15 wouldn't be locked to senderAddress, or
- Basic Output #16 would define Sender as anything else than senderAddress from Basic Output #15.
On-ledger (originating from L1) requests of IOTA Smart Contracts use this feature heavily, but it is also possible to fetch outputs created by a specific party with the Sender Feature through the INX UTXO indexer application and REST API.
Another handy tool is the Metadata Feature of outputs. This feature makes it possible to store arbitrary data in outputs. Of course, storing data in outputs increases the minimum base token requirement, but in turn it provides a data storage option that is 24/7 available on any network node.
As soon as the output with metadata is consumed, it is pruned from nodes' databases and base tokens used as storage deposit are freed up.
The first and most important ledger program for ISC chains is the Alias Output. 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. 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 address 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.
Foundries deal with the issuance of user defined custom tokens, so-called Native Tokens.
As we mentioned above, unlocking an output is performed via a digital signature. This is what we call an Address Unlock Condition.
TODO