diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 040a6eb1f6d92..0000000000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,5 +0,0 @@ -# Code of Conduct - -Please see Diem's -[Code of Conduct](https://developers.diem.com/docs/policies/code-of-conduct/), -which describes the expectations for interactions within the community. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b03ea77363ff..85caaa343323f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,21 +9,15 @@ cd sui cargo build --all --all-targets cargo test ``` -TODO: Note the `git clone` command above fails with the following error, which *should* go away when we open our repo up: +TODO: Note the `git clone` command above may fail with the following error, which *should* go away when we open our repo up: ``` remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead. remote: Please see https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/ for more information. ``` -## Coding guidelines for Rust code - -For detailed guidance on how to contribute to the Rust code in the Sui repository refer to the [Diem developer documentation](https://developers.diem.com/docs/welcome-to-diem/). - ## Pull requests -Please refer to the documentation to determine the status of each project (e.g. actively developed vs. archived) before submitting a pull request. - To submit your pull request: 1. Fork the `sui` repository and create your branch from `main`. @@ -34,7 +28,4 @@ To submit your pull request: 6. Complete the Contributor License Agreement (CLA), if you haven't already done so. 7. Submit your pull request. -TODO: Add links to the steps above for more details, such as how to build and test the dev site and where to find the CLA. - -## Code of Conduct -Please refer to the [Diem Code of Conduct](https://developers.diem.com/docs/policies/code-of-conduct/) for guidelines on interacting with the community. +TODO: Add links to the steps above for more details, such as how to build and test the dev site and where to find the CLA once we have one. diff --git a/README.md b/README.md index 6b9c39c08e5d8..137db1c8edeb5 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,50 @@ -# Sui (pre-alpha) - -[![Build Status](https://github.com/mystenlabs/fastnft/actions/workflows/rust.yml/badge.svg)](https://github.com/mystenlabs/fastnft/actions/workflows/rust.yml) -[![License](https://img.shields.io/badge/license-Apache-green.svg)](LICENSE.md) - -Sui is a decentralized permisionless smart contracts platform -developed with a goal of efficient management of rich assets. Sui uses -low-latency scalable and reliable broadcast between a set of validators to -ensure the safety of common operations on assets. It relies on full -consensus for governance operations and checkpointing performed off -the critical latency path. It uses the [Move](https://github.com/diem/move) -programming language to define assets as typed objects and operations -on these objects. - -For more information, visit the [Sui Developer Portal](doc/SUMMARY.md). - -## References - -Sui is based on [FastPay: High-Performance Byzantine Fault Tolerant Settlement](https://arxiv.org/pdf/2003.11506.pdf). - -## Contributing - -Read [Eng Plan](https://docs.google.com/document/d/1Cqxaw23PR2hc5bkbhXIDCnWjxA3AbfjsuB45ltWns4U/edit#). -TODO: Share the Doc with public. Consider formalizing and branding it. - -## License - -The content of this repository is licensed as [Apache 2.0](https://github.com/MystenLabs/fastnft/blob/update-readme/LICENSE). +# Sui Developer Portal + +Welcome to Sui, a next generation smart contract platform with high throughput, low latency, and an asset-oriented programming model powered by the [Move](https://github.com/MystenLabs/awesome-move) programming language! Here are some suggested starting points: + +* To jump right into building smart contract applications on top of Sui, go to [Move Quick Start](https://github.com/MystenLabs/fastnft/tree/main/doc/move.md). +* To experiment with a sample Sui wallet, check out [Wallet Quick Start](https://github.com/MystenLabs/fastnft/tree/main/doc/wallet.md). + +* To understand what's possible by browsing Move code built on top of Sui, review the [examples](https://github.com/MystenLabs/fastnft/tree/main/sui_programmability/examples/sources) +* To start coding against Sui's REST API's, start [here](https://app.swaggerhub.com/apis/arun-koshy/sui-api) +* To go deep on how Sui works, understand [Key Concepts](https://github.com/MystenLabs/fastnft/tree/main/doc/key-concepts.md). +* To learn what distinguishes Sui from other blockchain systems, see [What Makes Sui Different?](https://github.com/MystenLabs/fastnft/tree/main/doc/what-makes-sui-different.md). + + + + + +## Architecture + +Sui is a distributed ledger that stores a collection of programmable *[objects](https://github.com/MystenLabs/fastnft/tree/main/doc/objects.md)*, each with a globally unique ID. Every object is owned by a single *address*, and each address can own an arbitrary number of objects. + +The ledger is updated via a *[transaction](https://github.com/MystenLabs/fastnft/tree/main/doc/transactions.md)* sent by a particular address. A transaction can create, destroy, and write objects, as well as transfer them to other addresses. + +Structurally, a transaction contains a set of input object references and a pointer to a Move code object that already exists in the ledger. Executing a transaction produces updates to the input objects and (if applicable) a set of freshly created objects along with their owners. A transaction whose sender is address *A* can accept objects owned by *A*, shared objects, and objects owned by other objects in the first two groups as input. + +```mermaid +flowchart LR + CC(CLI Client) --> ClientService + RC(Rest Client) --> ClientService + RPCC(RPC Client) --> ClientService + ClientService --> AuthorityAggregator + AuthorityAggregator --> AC1[AuthorityClient] & AC2[AuthorityClient] + subgraph Authority1 + AS[AuthorityState] + end + subgraph Authority2 + AS2[AuthorityState] + end + AC1 <==>|Network TCP| Authority1 + AC2 <==>|Network TCP| Authority2 +``` + +Sui authorities agree on and execute transactions in parallel with high throughput using [Byzantine Consistent Broadcast](https://en.wikipedia.org/wiki/Byzantine_fault). + +## Move quick start +See the [Move Quick Start](https://github.com/MystenLabs/fastnft/tree/main/doc/move.md) for installation, defining custom objects, object operations (create/destroy/update/transfer/freeze), publishing, and invoking your published code. + + +## Wallet quick start +See the [Wallet Quick Start](https://github.com/MystenLabs/fastnft/tree/main/doc/wallet.md) for installation, querying the chain, client setup, sending transfer transactions, and viewing the effects. + diff --git a/doc/SUMMARY.md b/doc/SUMMARY.md deleted file mode 100644 index edd5f98f1a399..0000000000000 --- a/doc/SUMMARY.md +++ /dev/null @@ -1,87 +0,0 @@ -# Sui Developer Portal - -Welcome to Sui, a next generation smart contract platform with high throughput, low latency, and an asset-oriented programming model powered by the [Move](https://github.com/diem/move) programming language! Here are some suggested starting points: - -* To jump right into building smart contract applications on top of Sui, go to [Move Quick Start](move.md). -* To experiment with a sample Sui wallet, check out [Wallet Quick Start](wallet.md). -* To understand what's possible by browsing examples of full-fledged applications and games built on top of Sui, review the [Demos](TODO). -* To go deep on how Sui works, understand [Key Concepts](TODO). -* To learn what distinguishes Sui from other blockchain systems, see [What Makes Sui Different?](TODO). -* To experience Sui's speed and scalability for yourself, try [Benchmarking](TODO). -* To see the current status of the Sui software/network and preview what's coming next, read through our [Roadmap](TODO). - -TODO: Populate and link to the missing pages above or strike the links and references. - -## Architecture - -Sui is a distributed ledger that stores a collection of programmable *[objects](objects.md)*, each with a globally unique ID. Every object is owned by a single *address*, and each address can own an arbitrary number of objects. - -The ledger is updated via a *[transaction](transactions.md)* sent by a particular address. A transaction can create, destroy, and write objects, as well as transfer them to other addresses. - -Structurally, a transaction contains a set of input object references and a pointer to a Move code object that already exists in the ledger. Executing a transaction produces updates to the input objects and (if applicable) a set of freshly created objects along with their owners. - -A transaction whose sender is address *A* can accept objects owned only by *A* with one exception: a transaction can read from immutable objects regardless of their owner. - -```mermaid -flowchart LR - CC(CLI Client) --> ClientService - RC(Rest Client) --> ClientService - RPCC(RPC Client) --> ClientService - ClientService --> AuthorityAggregator - AuthorityAggregator --> AC1[AuthorityClient] & AC2[AuthorityClient] - subgraph Authority1 - AS[AuthorityState] - end - subgraph Authority2 - AS2[AuthorityState] - end - AC1 <==>|Network TCP| Authority1 - AC2 <==>|Network TCP| Authority2 -``` - -Sui authorities process transactions in parallel with high throughput using [Byzantine Consistent Broadcast](https://en.wikipedia.org/wiki/Byzantine_fault). - -## Move quick start -See the [Move Quick Start](move.md) for installation, defining custom objects, object operations (create/destroy/update/transfer/freeze), publishing, invoking your published code. Then deeper: Sui standard library, design patterns, examples. - -## Wallet quick start -See the [Wallet Quick Start](wallet.md) for installation, querying the chain, client setup, getting test coins, sending transfer transactions, viewing the effects in a block explorer. Then deeper: wallet CLI vs client service vs forwarder architecture, how to integrate your code (wallet, indexer, ...) with the client service or forwarder components. - -## Demos - -TODO: Develop or remove. - -## Concepts -- [Authorities](authorities.md) -- [Objects](objects.md) -- [Programmability](programmability.md) -- [Transactions](transactions.md) -- TODO: clients -- TODO: state sync -- TODO: reconfiguration -- TODO governance, incentives, and rewards - -## What makes Sui different? - -Sui allows a set of distributed authorities, some of which are Byzantine, to maintain a high-integrity and high-availability settlement system for pre-funded payments. It can be used to settle payments in a native unit of value (crypto-currency) or as a financial side-infrastructure to support retail payments in fiat currencies. Sui is based on Byzantine Consistent Broadcast as its core primitive, foregoing the expenses of full atomic commit channels (consensus). The resulting system has low latency for both confirmation and payment finality. Remarkably, each authority can be sharded across many machines to allow unbounded horizontal scalability. Our experiments demonstrate intra-continental confirmation latency of less than 100ms, making Sui applicable to point-of-sale payments. In laboratory environments, we achieve more than 80,000 transactions per second with 20 authorities---surpassing the requirements of current retail card payment networks while significantly increasing their robustness. - -Here are Sui's key features: - -- High throughput and low latency (enables low cost with fixed hardware) -- Causal order vs total order (enables massively parallel execution) -- Move and object-centric data model (enables composable objects/NFTs) - -### Authorities vs Validators/Miners -An authority plays a role similar to "validators" or "miners" in other blockchain systems. The key distinction between these roles (and the reason we insist on using a separate term) is that validators/miners are *active*, whereas authorities are *passive*. Broadly speaking: -* Miners/validators continuously participate in a global consensus protocol that requires multiple rounds of all-to-all communication between the participants. The goal is typically to agree on a *totally ordered* block of transactions and the result of their execution. -* Authorities do nothing until they receive 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. - -## 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. - -## Roadmap - -TODO diff --git a/doc/key-concepts.md b/doc/key-concepts.md new file mode 100644 index 0000000000000..27b8fdad5d25f --- /dev/null +++ b/doc/key-concepts.md @@ -0,0 +1,9 @@ +## Key Concepts +- [Authorities](authorities.md) +- [Objects](objects.md) +- [Programmability](programmability.md) +- [Transactions](transactions.md) +- TODO: clients +- TODO: state sync +- TODO: reconfiguration +- TODO governance, incentives, and rewards diff --git a/doc/what-makes-sui-different.md b/doc/what-makes-sui-different.md new file mode 100644 index 0000000000000..66f06776e89cb --- /dev/null +++ b/doc/what-makes-sui-different.md @@ -0,0 +1,17 @@ +## What makes Sui different? + +TODO: WIP + +Here are Sui's key features: + +- High throughput and low latency (enables low cost with fixed hardware) +- Causal order vs total order (enables massively parallel execution) +- Move and object-centric data model (enables composable objects/NFTs) + +### Authorities vs Validators/Miners +An authority plays a role similar to "validators" or "miners" in other blockchain systems. The key distinction between these roles (and the reason we insist on using a separate term) is that validators/miners are *active*, whereas authorities are *passive*. Broadly speaking: +* Miners/validators continuously participate in a global consensus protocol that requires multiple rounds of all-to-all communication between the participants. The goal is typically to agree on a *totally ordered* block of transactions and the result of their execution. +* Authorities do nothing until they receive 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.