Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create sui-glossary.md #766

Merged
merged 3 commits into from
Mar 17, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 127 additions & 0 deletions doc/src/learn/sui-glossary.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
---
title: Sui Glossary
---

Find terms used in Sui defined below. Where possible, we link to a canonical definition and focus upon Sui’s use of the term.


### Accumulator
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First time hearing about this. Is this used somewhere in our design?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know a few folks have used this term to explain things but guess the impt Q is usage in other docs


An [accumulator](https://en.wikipedia.org/wiki/Accumulator_(cryptography)) makes sure the transaction is received by a quorum of authorities,
collects a quorum of votes, submits the certificate to the authorities, and replies to the client. The accumulator enables transactions to be
certified. Sui offers a Gateway service that can assume the role of accumulator and collect votes on transactions from authorities in Sui,
saving end users bandwidth.


### Authority

An authority in Sui plays a passive role analogous to the more active role of validators and minors in other blockchains. In Sui,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There was a discussion about this from @gdanezis @adeabiodun and others. Basically "passive" is no longer true or won't be true soon as we add features such as shared objects which require consensus, plus other things down the line like state agreement.

The other question for everyone is since authorities are becoming active should we just call them validators?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would file an issue for this update as we use passive already in our docs. And you will have better luck getting a decision from others in a bug, for sure.

authorities do not continuously participate in the consensus protocol but are called into action only when receiving a transaction or
certificate.

For more information, see [Authorities vs validators/miners](how-sui-works.md#authorities-vs-validators-miners).


### Causal order

[Causal order](https://www.scattered-thoughts.net/writing/causal-ordering/) is a representation of the relationship between transactions
and the objects they produce, laid out as dependencies. Authorities cannot execute a transaction dependent on object created by a prior
transaction that has not finished. Rather than total order, Sui uses causal order.

For more information, see [Causal order vs total order](how-sui-works.md#causal-order-vs-total-order).


### Certificate

A certificate is the mechanism proving a transaction has been approved, or certified. Authorities vote on transactions, and the sender collects
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we say gateway here instead of "sender"? Just to clarify we don't mean the end user.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, I get the impression the gateway is optional. End users may act as senders directly, eating the bandwidth cost a gateway would help them avoid. I could be mistaken. Feel free to edit directly when you have an answer.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@huitseeker for comment here, as well.

a Byzantine-resistant-majority of these votes into a certificate and broadcasts it to all Sui authorities, thereby ensuring finality.


### Equivocation

Equivocation in blockchains is the malicious action of dishonest actors giving conflicting information, such as inconsistent or duplicate voting.


### Epoch

Operation of the Sui network is temporally partitioned into non-overlapping, fixed-duration (e.g. 24-hour) *epochs*. During a particular epoch, the set of authorities participating in the network is fixed.

For more information, see [Epochs](../build/authorities.md#epochs).


### Eventual consistency

[Eventual consistency](https://en.wikipedia.org/wiki/Eventual_consistency) is the consensus model employed by Sui; if one honest authority
certifies the transaction, all of the other honest authorities will too eventually.


### Family history

Family history is the relationship between an object in Sui and its direct predecessors and successors. This history is essential to the causal
order Sui uses to process transactions. In contrast, other blockchains attempt to read the entire state of their world for each transaction,
introducing great latency.


### Finality

[Finality](https://medium.com/mechanism-labs/finality-in-blockchain-consensus-d1f83c120a9a) is the assurance a transaction will not be revoked. This
stage is considered closure for an exchange or other blockchain transaction.


### Gas

As with other blockchains, [gas](https://www.investopedia.com/terms/g/gas-ethereum.asp) in Sui is the currency for the cost of conducting a transaction.


### Genesis

Genesis is the initial act of creating accounts and gas objects. Sui provides a `genesis` command that

For more information, see [Genesis](../build/wallet.md#genesis).


### Gateway service

Sui provides a Gateway service that enables third parties, say app/game developers, to route transactions on behalf of users. Because Sui never requires
exchange of private keys, third parties may offload bandwidth use from mobile device to server - for a fee.


### Multi-writer objects
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This definition seems problematic, I think we call it Shared Mutable Object, and it's shared by everyone, not just more than one account.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I think it's better to say "Shared Mutable Object", I see that term used everywhere, and explain that it means multiple people can write.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please edit in the Google Doc. Thanks!


Multi-writer objects are those owned by more than one account. Transactions affecting multi-writer objects require consensus in Sui. This contrasts with
those affecting only single-writer objects, which require only a confirmation of the owner’s account.


### Proof-of-stake

[Proof-of-stake](https://en.wikipedia.org/wiki/Proof_of_stake) is a blockchain consensus mechanism where the voting weights of authorities or validators is
proportional to their stake in the network. This mitigates attacks by forcing bad actors to gain a large stake in the blockchain first.


### Smart contract

A [smart contract](https://en.wikipedia.org/wiki/Smart_contract) is an agreement based upon the protocol for conducting transactions in a blockchain. In Sui,
smart contracts are written in the [Move](https://github.com/MystenLabs/awesome-move) programming language.


### Single-writer objects
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First time hearing about this, is this referenced/used anywhere?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what we call non-shared objects, regular objects? Owned objects (to use a Rust term?)


Single-writer objects are owned by one account. In Sui, transactions affecting only single-writer objects owned by the same account may proceed with only a
check of the sender’s account, greatly speeding transaction times.


### Total order
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might want to put Total Order together with Causal Order


Total order is the view of the entire state of a blockchain at any given time. This is used by many blockchain systems to certify transactions. In contrast,
Sui uses causal order.

For more information, see [Causal order vs total order](how-sui-works.md#causal-order-vs-total-order).


### Transfer

A transfer is switching the owner address of a token to a new one via command in Sui. This is accomplished via the
[Sui Wallet](../build/wallet.md) command line interface. It is one of the more common of many commands
available in the wallet.

For more information, see [Transferring objects](../build/wallet.md#transferring-objects).