Skip to content

Latest commit

 

History

History
42 lines (29 loc) · 5.13 KB

objects.md

File metadata and controls

42 lines (29 loc) · 5.13 KB
title
Objects

Sui has programmable objects created and managed by Move packages (a.k.a. smart contracts). Move packages themselves are also objects. Thus, Sui objects can be partitioned into two categories:

  • Mutable data values: typed data governed by a particular Move module. Each object value is a struct with fields that can contain primitive types (e.g. integers, addresses), other objects, and non-object structs. Each object value is mutable at the time of its creation but can subsequently be frozen and become permanently immutable.
  • Immutable packages: a set of Move bytecode modules with a distinct name. A package can depend on other package objects that were previously published to the Sui ledger.

Object metadata

All Sui objects have the following metadata:

  • A 20 byte globally unique ID. An object ID is derived from the digest of the transaction that created the object and from a counter encoding the number of IDs generated by the transaction.
  • An 8 byte unsigned integer version representing the number of transactions that have included this object as an output. Thus, all objects freshly created by a transaction will have version 1.
  • A 32 byte transaction digest indicating the last transaction that included this object as an output.
  • An is_mutable flag indicating whether the object can be mutated, destroyed, or transferred in a transaction sent by its owner. Both immutable and mutable objects can be read. Once an object becomes immutable, it remains immutable forever.

In addition to common metadata, objects have a category-specific, variable-sized contents field. For a data value, this contains the Move type of the object and its Binary Canonical Serialization (BCS)-encoded payload. For a package value, this contains the bytecode modules in the package.

Referring to objects

There are a few different ways to concisely refer to an object without specifying its full contents and metadata, each with slightly different use cases:

  • ID: the globally unique ID of the object mentioned above. This is a stable identifier for the object across time, and is useful (e.g.) for querying the current state of an object or describing which object was transferred between two addresses.
  • Versioned ID: an (ID, version) pair. This describes the state of the object at a particular point in the object's history, and is useful for (e.g.) asking what the value of the object was at some point in the past or determining how fresh some view of an object is now.
  • Object Reference: an (ID, object digest) pair. The object digest is the hash of the object's contents and metadata. An object reference provides an authenticated view of the object at a particular point in the object's history. Transactions require object inputs to be specified via object references to ensure the transaction's sender and an authority processing the transaction agree on the contents and metadata of the object.

The transaction-object DAG: Relating objects and transactions

Transactions (and thus, certificates) take objects as input, read/write/mutate these inputs, and produce mutated or freshly created objects as output. And as discussed above, each object knows the (hash of the) last transaction that produced it as an output. Thus, a natural way to represent the relationship between objects and transactions is a directed acyclic graph (DAG) where:

  • nodes are transactions.
  • directed edges connect transaction output objects to transaction input objects and are labeled with object references.

To construct this graph, we add a node for each committed transaction and draw a directed edge labeled with object reference O from transaction A to transaction B if A produced object O (i.e., created or mutated O) and transaction B takes object O as an input.

The root of this DAG is a genesis transaction that takes no inputs and produces the objects that exist in the initial state of the system. The DAG can be extended by identifying mutable transaction outputs that have not yet been consumed by any committed transaction and sending a new transaction that takes these outputs (and optionally, immutable transaction outputs) as inputs.

The set of objects that are available to be taken as input by a transaction are the live objects, and the global state maintained by Sui consists of the totality of such objects. The live objects for a particular Sui address A are all objects owned by A, along with all immutable objects in the system.

When this DAG contains all committed transactions in the system, it forms a complete (and crytographically auditable) view of the system's state and history. In addition, we can use the scheme above to construct a DAG of the relevant history for a subset of transactions or objects (e.g., the objects owned by a single address).

Further reading