Skip to content

Commit

Permalink
(fix) qip-0001: refactor to markdown
Browse files Browse the repository at this point in the history
  • Loading branch information
@alanorwick
alanorwick committed Nov 22, 2023
1 parent 4a8e372 commit 1f46bdd
Show file tree
Hide file tree
Showing 7 changed files with 223 additions and 373 deletions.
16 changes: 16 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
People wishing to submit QIPs, first should propose their idea to the [Quai forum](https://forum.qu.ai) (do *not* assign a number - read [QIP 1](qip-0001.mediawiki) for the full process). After discussion, please open a PR. After copy-editing and acceptance, it will be published here.

We are fairly liberal with approving QIPs, and try not to be too involved in decision making on behalf of the community. The exception is in very rare cases of dispute resolution when a decision is contentious and cannot be agreed upon. In those cases, the conservative option will always be preferred.

Having a QIP here does not make it a formally accepted standard until its status becomes Final or Active.

Those proposing changes should consider that ultimately consent may rest with the consensus of the Quai users.

| Number | Layer | Title | Owner | Type | Status |
|--------|----------------------|---------------------------------|----------|---------|--------|
| [1](qip-0001.mediawiki) | | QIP process | wizeguyy | Process | Active |
| [2](qip-0002.mediawiki) | Consensus (hard fork) | Sharded ledger | wizeguyy | Standard| Draft |
| [3](qip-0003.mediawiki) | Applications | Shard Specific Address Discovery | wizeguyy | Standard| Draft |
| [4](qip-0004.mediawiki) | Applications | 9 Shard Address Mapping | wizeguyy | Standard| Draft |

<!-- IMPORTANT! See the instructions at the top of this page, do NOT JUST add QIPs here! -->
46 changes: 0 additions & 46 deletions README.mediawiki
View file

This file was deleted.

200 changes: 88 additions & 112 deletions qip-0001.mediawiki → qip-0001.md
View file

Large diffs are not rendered by default.

134 changes: 44 additions & 90 deletions qip-0002.mediawiki → qip-0002.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<pre>
```
QIP: 2
Layer: Consensus (hard fork)
Title: Sharded ledger
Expand All @@ -9,114 +9,68 @@
Type: Standards Track
Created: 2023-09-07
License: BSD-2-Clause
</pre>
```

==Abstract==
## Abstract

The Quai protocol accommodates high transactional throughput by splitting ledger state into independent shards. Each shard is updated via block chain and merge mined with the other shard chains. This QIP describes a mechanism of splitting the state trie according to account prefix, in order to guarantee no two shards posess conflicting state transitions.
The Quai protocol accommodates high transactional throughput by splitting ledger state into independent shards. Each shard is updated via blockchain and merge mined with the other shard chains. This QIP describes a mechanism of splitting the state trie according to account prefix, in order to guarantee no two shards possess conflicting state transitions.

==Motivation==
## Motivation

Sharding makes it possible to asynchronously progress multiple chains simultaneously. Concretely, sharding the ledger provides a simple guarantee that no two zone chains will have conflicting state transitions. Without this guarantee, zone chains would not be able progress asynchronously. Put differently, if zone chains could have conflicting transactions, then no chain would reach finality until it found a merge mined block that the entire network accepts as canonical. This would completely negate the scaling benefits of Quai's merge mined architecture, reducing the network throughput to that of a single chain of merged blocks.
Sharding makes it possible to asynchronously progress multiple chains simultaneously. Concretely, sharding the ledger provides a simple guarantee that no two zone chains will have conflicting state transitions. Without this guarantee, zone chains would not be able to progress asynchronously. Put differently, if zone chains could have conflicting transactions, then no chain would reach finality until it found a merge mined block that the entire network accepts as canonical. This would completely negate the scaling benefits of Quai's merge mined architecture, reducing the network throughput to that of a single chain of merged blocks.

==Specification==
## Specification

===Overview===
### Overview

The address space is divided into subsets according to address prefix. The account state for each subset of addresses will be maintained wholly by one and only one shard. Intra-shard transactions may only be processed by the blockchain which maintains that shard. Inter-shard transactions are possible, but the specification for those will be left to another QIP.

===Shard Organization===
### Shard Organization

The Quai protocol defines a hierarchy of merge mined blockchains. This hierarchy takes the form of a tree with two levels under the root. The root chain (aka prime chain) is merge mined by several "region chains" of lower difficulty. Each region chain is merge mined by "zone chains" of lower difficulty.

Since this architecture is symmetric, the total number of shards which can exist in a region is `sqrt(N)`, where `N` is the total number of shards in the network.

===Shard Identifiers===
### Shard Identifiers

Each shard is given a binary identifier. Any address which has a matching binary prefix will exist in that shard. The shard identifier is a single byte. The first 4 MSb of the identifier indicates which region this shard belongs to. The remaining 4 LSb of the indentifier, indicates which zone within the region, this shard belongs to.
Each shard is given a binary identifier. Any address which has a matching binary prefix will exist in that shard. The shard identifier is a single byte. The first 4 MSb of the identifier indicates which region this shard belongs to. The remaining 4 LSb of the identifier, indicates which zone within the region, this shard belongs to.

====Format====
{|
#### Format

!bits 0..4
!bits 4..8
|-
| region number
| zone number
|}
| bits 0..4 | bits 4..8 |
| ------------- | ------------- |
| region number | zone number |

#### Examples

====Examples====
The following table gives a few example shard identifiers, and which zone chain they belong to.

{|
!Shard ID
!Hex Value
!Region
!Zone
|-
| shard-0
| 0x00
| region-0
| zone-0-0
|-
| shard-1
| 0x01
| region-0
| zone-0-1
|-
| shard-10
| 0x0A
| region-0
| zone-0-10
|-
| shard-42
| 0x2A
| region-2
| zone-2-10
|-
| shard-255
| 0xFF
| region-15
| zone-15-15
|}


===Shard Activation===
| Shard ID | Hex Value | Region | Zone |
| --------- | --------- | -------- | -------- |
| shard-0 | 0x00 | region-0 | zone-0-0 |
| shard-1 | 0x01 | region-0 | zone-0-1 |
| shard-10 | 0x0A | region-0 | zone-0-10|
| shard-42 | 0x2A | region-2 | zone-2-10|
| shard-255 | 0xFF | region-15| zone-15-15|

### Shard Activation

There is no requirement for shards to be active. It is likely that only a fraction of the shards will be active initially, and the network will expand to activate more shards as network demand increases. The exact process for deciding how/when to activate more shards will be left for a future QIP. The Quai protocol defines the initial topology to be a 3x3 tree, so there will be 9 shards active in this minimum topology. Those shards are given below.
====Initially Active Shards====
{|
!Shard ID
!Hex Value
|-
| shard-0
| 0x00
|-
| shard-1
| 0x01
|-
| shard-2
| 0x02
|-
| shard-3
| 0x10
|-
| shard-4
| 0x11
|-
| shard-5
| 0x12
|-
| shard-6
| 0x20
|-
| shard-7
| 0x21
|-
| shard-8
| 0x22
|}

==Copyright==

This QIP licensed under the BSD 2-clause license.

#### Initially Active Shards

| Shard ID | Hex Value |
| --------- | --------- |
| shard-0 | 0x00 |
| shard-1 | 0x01 |
| shard-2 | 0x02 |
| shard-3 | 0x10 |
| shard-4 | 0x11 |
| shard-5 | 0x12 |
| shard-6 | 0x20 |
| shard-7 | 0x21 |
| shard-8 | 0x22 |

## Copyright

This QIP licensed under the BSD 2-clause license.
58 changes: 29 additions & 29 deletions qip-0003.mediawiki → qip-0003.md
View file
Original file line number Diff line number Diff line change
@@ -1,41 +1,42 @@
<pre>
QIP: 3
Layer: Applications
Title: Shard Specific Address Discovery
Author: wizeguyy <[email protected]>
Comments-Summary: No comments yet.
Comments-URI: https://github.com/quainetwork/qips/wiki/Comments:QIP-0003
Status: Draft
Type: Standards Track
Created: 2023-09-12
License: BSD-2-Clause
</pre>
```
QIP: 3
Layer: Applications
Title: Shard Specific Address Discovery
Author: wizeguyy <[email protected]>
Comments-Summary: No comments yet.
Comments-URI: https://github.com/quainetwork/qips/wiki/Comments:QIP-0003
Status: Draft
Type: Standards Track
Created: 2023-09-12
License: BSD-2-Clause
```

==Abstract==
## Abstract

This QIP defines an address discovery algorithm for deterministic [https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki BIP44] wallets, which is compatible with Quai's <a href="qip-0002.mediawiki">QIP2</a> sharded address space.
This QIP defines an address discovery algorithm for deterministic [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) wallets, which is compatible with Quai's [QIP2](qip-0002.mediawiki) sharded address space.

==Motivation==
## Motivation

The hierarchy proposed in BIP44 is well defined, but the gap limit technique for address discovery is insufficient for wallets operating in Quai's sharded address space, described in <a href="qip-0002.mediawiki">QIP2</a>. This specification discribes an algorithm to discover addresses mapped to each shard, within the BIP44 hierarchy.
The hierarchy proposed in BIP44 is well defined, but the gap limit technique for address discovery is insufficient for wallets operating in Quai's sharded address space, described in [QIP2](qip-0002.mediawiki). This specification describes an algorithm to discover addresses mapped to each shard, within the BIP44 hierarchy.

==Specification==
## Specification

===Relationship to BIP44===
### Relationship to BIP44

BIP44 defines the following 5 levels in the BIP32 path:
<pre>
```
m / purpose' / coin_type' / account' / change / address_index
</pre>
```

Additionally BIP44 describes an account discovery and address gap limit techniques to standardize how wallet software can identify keys for use on a given blockchain. This QIP adheres to BIP44 in all ways except for the gap limit technique. Since each address is valid in one and only one chain, and that validity cannot be known by path alone (validity is determined by address prefix), the wallet must grind addresses until it finds addresses which are valid in each shard. In place of BIP44's gap limit, we define the shard discovery technique below.

===Shard Address Discovery===
### Shard Address Discovery

To perform address discovery, a wallet software should search through the BIP44 <code>address_index</code> level of the BIP32 path and record which shard each address belongs to. This creates a secondary mapping on the <code>address_index</code>, which we denote <code>shard_address_index</code>. Precisely, the i<sup>th</sup> <code>shard_address_index</code> in <code>shard-k</code> is the i<sup>th</sup> address from the subset of addresses which are valid in <code>shard-k</code>.
To perform address discovery, a wallet software should search through the BIP44 `address_index` level of the BIP32 path and record which shard each address belongs to. This creates a secondary mapping on the `address_index`, which we denote `shard_address_index`. Precisely, the i<sup>th</sup> `shard_address_index` in `shard-k` is the i<sup>th</sup> address from the subset of addresses which are valid in `shard-k`.

We give the following search algorithm in pseudo code for reference:
<pre>

```plaintext
// A BIP32 type to represent a full BIP32 path for address derivation
struct bip32 {
uint64 purpose;
Expand Down Expand Up @@ -83,24 +84,23 @@ vec<vec<addresses>> generateShardAddresses(n int, path bip32) {
// Return the full list of addresses we've discovered
return address_lists;
}
</pre>

===Gap Limit===
```
### Gap Limit

For an account ledger there is no need to search for additional addresses beyond the first 256 (QIP2 defined maximum number of shards). For a UTXO ledger, we follow BIP44's gap limit definition applied to each shard, instead of applied to the raw <code>address_index</code>.

Precisely, BIP44 has defined a gap limit of 20. In keeping with that, a UTXO wallet in the Quai network should keep searching for addresses until a gap of 20 unused addresses is found '''in each shard'''. It can be assumed that there are no used addresses in a shard beyond the 20<sup>th</sup> unused address in that shard.

Software should warn when the user is trying to exceed the gap limit on any given shard chain, by generating a new address.

====Examples====
### Examples

TBD...

==Copyright==
## Copyright

This QIP licensed under the BSD 2-clause license.

==References==
## References
* https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
* https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki
46 changes: 46 additions & 0 deletions qip-0004.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
```
QIP: 4
Layer: Applications
Title: 9 Shard Address Mapping
Author: wizeguyy <[email protected]>
Comments-Summary: No comments yet.
Comments-URI: [https://github.com/quainetwork/qips/wiki/Comments:QIP-0004](https://github.com/quainetwork/qips/wiki/Comments:QIP-0004)
Status: Draft
Type: Standards Track
Created: 2023-09-15
License: BSD-2-Clause
```

## Abstract

This QIP defines an address mapping to be used in a 9 shard hierarchy of the Quai protocol.

## Motivation

This defines the address mapping used in early testnets of the Quai protocol. Early testnets use a lighter 9-shard hierarchy. It has already been concluded that the mainnet should accommodate more than 9 shards, so this mapping is no longer recommended. We documented it here for wallet compatibility with early testnets.

## Specification

### Overview

The address space is divided into subsets according to address prefix. The account state for each subset of addresses will be maintained wholly by one and only one shard. Intra-shard transactions may only be processed by the blockchain which maintains that shard. Inter-shard transactions are possible, but the specification for those will be left to another QIP.

### Address Mapping

All addresses are mapped to exist in one of nine shards according to the MSB of the address. The Address groupings are given below:

| Name | Region | Zone | Min Address | Max Address |
|---------|---------|---------|-----------------------------------------|-----------------------------------------|
| cyprus1 | region-0| zone-0-0| 0x0000000000000000000000000000000000000000| 0x1DFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF|
| cyprus2 | region-0| zone-0-1| 0x1E00000000000000000000000000000000000000| 0x3AFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF|
| cyprus3 | region-0| zone-0-2| 0x3B00000000000000000000000000000000000000| 0x57FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF|
| paxos1 | region-1| zone-1-0| 0x5800000000000000000000000000000000000000| 0x73FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF|
| paxos2 | region-1| zone-1-1| 0x7400000000000000000000000000000000000000| 0x8FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF|
| paxos3 | region-1| zone-1-2| 0x9000000000000000000000000000000000000000| 0xABFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF|
| hydra1 | region-2| zone-2-0| 0xAC00000000000000000000000000000000000000| 0xC7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF|
| hydra2 | region-2| zone-2-1| 0xC800000000000000000000000000000000000000| 0xE3FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF|
| hydra3 | region-2| zone-2-2| 0xE400000000000000000000000000000000000000| 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF|

## Copyright

This QIP is licensed under the BSD 2-clause license.
Loading

0 comments on commit 1f46bdd

Please sign in to comment.