[doc] initial progress on dev docs. An overview, some outlines for qu… #245
Conversation
sblackshear
force-pushed
the
docs
branch
2 times, most recently
from
9ca24dd
to
d44f805
Compare
…ick start and key concepts sections, section on objects.
| EDITORIAL COMMENT: I think this section should lead with high-level selling points, then go into some more nuanced technical comparisons with existing systems, then conclude with honest descriptions limitations + pointers into the roadmap items that show we're already thinking about addressing them | ||
|
|
||
| - High throughput and low latency (enables low cost w/ fixed hardware) | ||
| - Horizontal scalability |
There was a problem hiding this comment.
Hm, it's hard to reconcile this with the direction to shard each authority within itself. Usually horizontal scalability means adding more nodes increases throughput. In this case, however, adding more authorities leads to decreasing throughput, since the broadcast has to go wider. The only thing that adds throughput is scaling each authority.
| * 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. |
|
|
||
| ### Transfer | ||
|
|
||
| This transaction type transfers coins from the sender to the specified recipients. |
There was a problem hiding this comment.
Do we really mean "coins" or it should be "objects"?'
EDIT: makes more sense after reading the editorial note.
|
|
||
| EDITORIAL COMMENT: feel free to take a hatchet to what follows | ||
|
|
||
| ### Authorities vs Validators/Miners |
There was a problem hiding this comment.
I would link to the authorities doc below.
I think this is also a good place to add something about scalability plans. Namely that unlike other blockchain systems which shard amongst participants, the idea is for authorities to be entities which internally shard, so that authorities could be clusters.
There was a problem hiding this comment.
Also wonder if this is the place to talk about incentives for authorities.
There was a problem hiding this comment.
Nevermind, I see that those details are below. Would be good to mention that the linked doc has details on incentives, sharing and scalability, and many other important details.
| * Authorities do nothing until they recieve a transaction or certificate from a user. Upon receiving a transaction or certificate, an authority need not communicate with other authorities in order to take action and advance its internal state machine. It may wish to communicate with other authorities to share certificates, but need not do so. | ||
|
|
||
| ## Causal Order vs Total Order | ||
| Unlike most existing blockchain systems (and as the reader may have guessed from the description of write requests above), Sui does not impose a total order on the transactions submitted by clients. Instead, transactions are *causally* ordered--if a transaction `T1` produces output objects `O1` that are used as input objects in a transaction `T2`, an authority must execute `T1` before it executes `T2`. Note that `T2` need not use these objects directly for a causal relationship to exist--e.g., `T1` might produce output objects which are then used by `T3`, and `T2` might use `T3`'s output objects. However, transactions with no causal relationship can be processed by Sui authorities in any order. |
There was a problem hiding this comment.
It might be good to talk about implications of casual ordering. For sure, casual ordering would have implications on the idea of global state. It is not a chain, but like a set or something. Or maybe that's too deep for this which is a summary.
| EDITORIAL NOTE: Feels like this last bit could/should be part of a different | ||
|
|
||
| ## Benchmarking | ||
| TODO: installation, running throughput and latency benchmarks, demonstrating that throughput goes up when you add more cores, adding more authorities leads to linear-ish decrease of latency/throughput. |
There was a problem hiding this comment.
I'd love to see this section flushed out cuz I wanted to ask about it. :)
|
|
||
| The Sui network is operated by a set of independent *authorities*, each running its own instance of the Sui software on a separate machine (or a [sharded](TODO) cluster of machines operated by the same entity). An authority participates in the network by handling [read](TODO) and write requests sent by [clients](TODO). This section focuses on the latter. | ||
|
|
||
| Sui uses proof of stake (PoS) to determine which authorities operate the network and their voting power. Authorities are incentivized to participate in good faith via a share of transaction fees, staking rewards, and slashing to punish misbehavior. See [Governance, Incentives, and Rewards](TODO) for more detail. |
There was a problem hiding this comment.
What are authorities voting on? I thought that authorities are passive and basically don't really communicate with each other. Is it for epochs - to Make sure there is agreement on authorities?
| ## Committees | ||
| A *committee* is a set of authorities whose combined voting power is >2/3 of the total during a particular epoch. For example, in a Sui instance operated by four authorities that all have the same voting power, any group containing 3 authorities is a committee. | ||
|
|
||
| The committee size of >2/3 is chosen to ensure *Byzantine fault tolerance*. As we will see, an authority will only commit a transaction (i.e., durably store the transaction and update its internal state with the effects of the transaction) if it is accompanied by cryptographic signatures from a committee. We call the combination of the transaction and the committee signatures on its bytes a *certificate*. The policy of only committing certificates ensures Byzantine fault tolerance: if <2/3 of the authorities faithfully follow the protocol, they are guaranteed to eventually agree on both the set of committed certificates and their effects. |
There was a problem hiding this comment.
Two notes here:
-
2/3, not <2/3, right?
- "eventually" could be forever if there are network partitions, for which < 1/3 of authorities do not get updates and don't converge.
|
|
||
| ## 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 we 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 DAG where: |
There was a problem hiding this comment.
Food for thought: I wonder if we've thought about making everything immutable. That is that transactions always produces new objects. It might seem a bit of a waste, but it would probably simplify parts of the system, no need to track that everything is mutable, and it turns storage into more of a log, and would make differential comparisons easier. New things are just a differential tree.
| * Gas Input: An object reference pointing to the object that will be used to pay for this transaction's execution and storage. This object must be owned by the user and must be of type `Sui::Coin::Coin<GAS>` (i.e., the Sui native currency). | ||
| * Gas Price: An unsigned integer specifying the number of native tokens per gas unit this transaction will pay. The gas price must always be nonzero. | ||
| * Maximum Gas Budget: The maximum number of gas units that can be expended by executing this transaction. If this budget is exceeded, transaction execution will [abort](TODO) and have no effects other than debiting the gas input. The gas input object must have a value higher than the gas price multipled by the max gas, and this product is the maximum amount that the gas input object will be debited for the transaction. | ||
| * Epoch: The Sui epoch this transaction is intended for--see [Epochs](TODO). |
There was a problem hiding this comment.
What happens if the Epoch rolls over as a tx is being submitted?
|
|
||
| ## Move Call Transaction | ||
|
|
||
| This transaction type is a "smart contract call" that invokes a function in a published Move package with objects owned by the sender and pure values (e.g., integers) as inputs. Executing a function may read, write, mutate, and transfer these input objects, as well as other objects created during execution. |
There was a problem hiding this comment.
What does it mean for a Move package to be "published"? Does this mean it lives in the ledger as an object?
|
|
||
| ## Move Publish Transaction | ||
|
|
||
| This transaction type publishes a new Move package as an immutable object. Once the package has been published, its public functions and types can be used by future packages, and its entrypoint functions can be called by future transactions. |
There was a problem hiding this comment.
Can a user browse the list of published packages?
|
|
||
| ### Transfer | ||
|
|
||
| This transaction type transfers coins from the sender to the specified recipients. |
There was a problem hiding this comment.
Why is a transfer a distinct type as opposed to another Move call?
…ick start and key concepts sections, section on objects.