From a9b25bf92c0cfe10219670312927bb5695c3533f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A5rten=20Blankfors?= Date: Fri, 28 Jul 2023 15:08:15 +0200 Subject: [PATCH 1/6] wip: Reorganizing thigns a bit to pave the way for PoX information --- src/SUMMARY.md | 1 + src/architecture.md | 1 + src/clarity-contracts.md | 1 + src/pox-contract.md | 7 +++++++ src/sbtc-contract.md | 5 +++++ 5 files changed, 15 insertions(+) create mode 100644 src/clarity-contracts.md create mode 100644 src/sbtc-contract.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 9e21045..8d0241d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -20,6 +20,7 @@ - [sBTC Requests and Responses](./sbtc-operations.md) - [Bitcoin Transactions](./sbtc-operations/bitcoin-transactions.md) - [The Commit-Reveal System](./sbtc-operations/commit-reveal-system.md) +- [The sBTC Token](./sbtc-contract.md) - [The PoX Contract](./pox-contract.md) - [Stacker responsibilities](./stacker-responsibilities.md) - [Signature Aggregation with FROST](./stacker-responsibilities/frost.md) diff --git a/src/architecture.md b/src/architecture.md index 537a387..666f8d8 100644 --- a/src/architecture.md +++ b/src/architecture.md @@ -8,6 +8,7 @@ Stacking is performed through a special smart contract, called the PoX contract. People who stack are called stackers. In sBTC we introduce the following changes to Stacks consensus: +* TODO: Introduce sBTC Token contract... * The PoX contract is extended to include sBTC as a [SIP-010 fungible token](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md). * The Stacks blockchain is required to monitor Bitcoin for sBTC requests. The blockchain mints and burns sBTC tokens as defined in the PoX contract in direct response to valid sBTC requests. * Stackers must provide a Bitcoin address for sBTC deposits in the PoX contract. diff --git a/src/clarity-contracts.md b/src/clarity-contracts.md new file mode 100644 index 0000000..ebc5c14 --- /dev/null +++ b/src/clarity-contracts.md @@ -0,0 +1 @@ +# Clarity Contracts diff --git a/src/pox-contract.md b/src/pox-contract.md index 46bd36d..568314f 100644 --- a/src/pox-contract.md +++ b/src/pox-contract.md @@ -1,4 +1,11 @@ # The PoX Contract +The [PoX Contract](https://docs.stacks.co/docs/clarity/noteworthy-contracts/stacking-contract) is used by Stackers to lock their STX in order to receive BTC rewards. +In sBTC the PoX contract is extended to also do the following. + +- Mint and burn sBTC tokens. +- More things? + + Explanation of the PoX contracts and it's public functions. It should be clear which functions a user would interact with, which ones are used by stackers, and which ones that are called as part of Stacks consensus (sBTC mint/burn). TODO: [#9](https://github.com/stacks-network/sbtc-docs/issues/9) diff --git a/src/sbtc-contract.md b/src/sbtc-contract.md new file mode 100644 index 0000000..eeddcf9 --- /dev/null +++ b/src/sbtc-contract.md @@ -0,0 +1,5 @@ +# The sBTC Token +The sBTC Token is defined as a [SIP-010 fungible token contract](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md). + +Content for this page: +- Tokenomics: How many tokens can be minted? Who can mint and burn the token? From 4771675b51d7ad2c36e12f248472a9fb72090218 Mon Sep 17 00:00:00 2001 From: jesus Date: Sun, 6 Aug 2023 10:18:48 -0400 Subject: [PATCH 2/6] kickoff intro, user types & lifecycle --- src/pox-contract.md | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/src/pox-contract.md b/src/pox-contract.md index 568314f..64428fc 100644 --- a/src/pox-contract.md +++ b/src/pox-contract.md @@ -1,11 +1,28 @@ # The PoX Contract -The [PoX Contract](https://docs.stacks.co/docs/clarity/noteworthy-contracts/stacking-contract) is used by Stackers to lock their STX in order to receive BTC rewards. -In sBTC the PoX contract is extended to also do the following. +The PoX contract, in this case PoX-4, is the crux of stacking & therefore the general consensus between Bitcoin & Stacks. Miners on Bitcoin mine STX blocks by sending Bitcoin to a weighted lottery; on the Stacks side, users can "stack" their STX, every two weeks, to receive a part of the Bitcoin mining rewards. -- Mint and burn sBTC tokens. -- More things? +The fourth version of this, PoX-4 introduces the logic necessary for a decentralized Bitcoin-peg (sBTC). Specifically, it introduces the mechanics necessary for stackers to evolve into signers: instead of stacking & passively receiving mining rewards, signers are now incentivized to help process (by signing) peg-in(deposits), peg-out(withdraws) & peg-transfers (handoffs). +PoX-2 documentation lives [here](https://docs.stacks.co/docs/clarity/noteworthy-contracts/stacking-contract). Below we introduce the likely *new* public functions that'll fold into PoX-4. First, though, we'll review the user types before hopping into the PoX-4 lifecycle which lasts ~2100 blocks & is split over five windows. -Explanation of the PoX contracts and it's public functions. It should be clear which functions a user would interact with, which ones are used by stackers, and which ones that are called as part of Stacks consensus (sBTC mint/burn). +# User Types +**Observer** +This is basically any active principal in the Stacks network, regardless of whether they hold STX or sBTC. They're not incentivized to *sign* anything, but, they are incentivized to throw a flat (aka start a penalty) if they see an issue with the protocol. + +**Registered Signer** +This is a principal that is or will register & vote in the current cycle. They are *not,* signers but more so the signers on-deck for the next cycle. + +**Current Signer** +This is a principal that is currently a signer. + +# PoX Lifecycle +**Disbursement [x]** + +**Registration [1600 - x blocks]** + +**Vote [300 blocks]** + +**Transfer [100 blocks]** + +**Penalize [100 blocks]** -TODO: [#9](https://github.com/stacks-network/sbtc-docs/issues/9) From 2e8cb3aa26bad5c1de7210a8268dfa16bbf94b60 Mon Sep 17 00:00:00 2001 From: jesus Date: Sun, 6 Aug 2023 15:44:37 -0400 Subject: [PATCH 3/6] updated summaries & starting to list functions --- src/pox-contract.md | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/src/pox-contract.md b/src/pox-contract.md index 64428fc..796e69a 100644 --- a/src/pox-contract.md +++ b/src/pox-contract.md @@ -5,24 +5,42 @@ The fourth version of this, PoX-4 introduces the logic necessary for a decentral PoX-2 documentation lives [here](https://docs.stacks.co/docs/clarity/noteworthy-contracts/stacking-contract). Below we introduce the likely *new* public functions that'll fold into PoX-4. First, though, we'll review the user types before hopping into the PoX-4 lifecycle which lasts ~2100 blocks & is split over five windows. + # User Types **Observer** -This is basically any active principal in the Stacks network, regardless of whether they hold STX or sBTC. They're not incentivized to *sign* anything, but, they are incentivized to throw a flat (aka start a penalty) if they see an issue with the protocol. +This is basically any active principal in the Stacks network, regardless of whether they hold STX or sBTC. They're not incentivized to *sign* anything, but, they are incentivized to throw a flat (aka start a penalty) if they see an issue with the protocol. Both Current & Registered Signers (below) are subsets of an Observer. -**Registered Signer** +**Registered Signer (N+1)** This is a principal that is or will register & vote in the current cycle. They are *not,* signers but more so the signers on-deck for the next cycle. -**Current Signer** -This is a principal that is currently a signer. +**Current Signer (N)** +This is a principal that is currently a signer for the current PoX cycle. + +**Previous Signer (N-1)** +This is a principal that was the signer during the previous PoX cycle. + + +# PoX Lifecycle & Functions +Below we'll review the PoX lifecycle along with what public functions are avaiable to which user type. -# PoX Lifecycle **Disbursement [x]** +The disbursement window is the very last step of the **previous** cycle. This is when the PoX rewards from the previous cycle are distributed to the previous signers. Since these rewards are disbursed in Bitcoin, someone needs to verify it on Stacks. + +Observer -> (penalty-pox-reward-disbursement ...) +Previous Signer -> (prove-rewards-were-disbursed ...) **Registration [1600 - x blocks]** +Summary of registration window + +Registered Signer -> (register ...) **Vote [300 blocks]** +Summary of vote window + +Registered Signer -> (vote-for-threshold-wallet-candidate ...) **Transfer [100 blocks]** +Observer -> (penalty-pox-transfer ...) **Penalize [100 blocks]** From 32d1180d3bcd02fd93c2faccd1c8aae2b819266d Mon Sep 17 00:00:00 2001 From: jesus Date: Sun, 6 Aug 2023 16:00:26 -0400 Subject: [PATCH 4/6] test spacing --- src/pox-contract.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/pox-contract.md b/src/pox-contract.md index 796e69a..1606abe 100644 --- a/src/pox-contract.md +++ b/src/pox-contract.md @@ -27,6 +27,7 @@ Below we'll review the PoX lifecycle along with what public functions are avaiab The disbursement window is the very last step of the **previous** cycle. This is when the PoX rewards from the previous cycle are distributed to the previous signers. Since these rewards are disbursed in Bitcoin, someone needs to verify it on Stacks. Observer -> (penalty-pox-reward-disbursement ...) + Previous Signer -> (prove-rewards-were-disbursed ...) **Registration [1600 - x blocks]** @@ -40,7 +41,9 @@ Summary of vote window Registered Signer -> (vote-for-threshold-wallet-candidate ...) **Transfer [100 blocks]** +Summary of transfer window + Observer -> (penalty-pox-transfer ...) **Penalize [100 blocks]** - +Summary of penalty window From 943b2817130e8400d053f5834cb61d75a80c115b Mon Sep 17 00:00:00 2001 From: jesus Date: Sun, 13 Aug 2023 08:29:06 -0400 Subject: [PATCH 5/6] wip: defining all windows & functions --- src/pox-contract.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/src/pox-contract.md b/src/pox-contract.md index 1606abe..5295496 100644 --- a/src/pox-contract.md +++ b/src/pox-contract.md @@ -1,39 +1,42 @@ # The PoX Contract -The PoX contract, in this case PoX-4, is the crux of stacking & therefore the general consensus between Bitcoin & Stacks. Miners on Bitcoin mine STX blocks by sending Bitcoin to a weighted lottery; on the Stacks side, users can "stack" their STX, every two weeks, to receive a part of the Bitcoin mining rewards. +The PoX contract, PoX-4, is the crux of stacking & therefore the general consensus between Bitcoin & Stacks. Miners on Bitcoin mine STX blocks by sending Bitcoin to a weighted lottery every block; on the Stacks side, users can "stack" their STX, every two weeks, for receive a part of the Bitcoin mining rewards. -The fourth version of this, PoX-4 introduces the logic necessary for a decentralized Bitcoin-peg (sBTC). Specifically, it introduces the mechanics necessary for stackers to evolve into signers: instead of stacking & passively receiving mining rewards, signers are now incentivized to help process (by signing) peg-in(deposits), peg-out(withdraws) & peg-transfers (handoffs). +The fourth version of this, PoX-4, introduces the logic necessary for a decentralized two-way Bitcoin-peg (sBTC). Specifically, it introduces the mechanics necessary for stackers to now evolve into signers: instead of stacking & passively receiving mining rewards, signers are now incentivized to help process (by signing) peg-ins(deposits), peg-outs(withdraws) & peg-transfers (handoffs). PoX-2 documentation lives [here](https://docs.stacks.co/docs/clarity/noteworthy-contracts/stacking-contract). Below we introduce the likely *new* public functions that'll fold into PoX-4. First, though, we'll review the user types before hopping into the PoX-4 lifecycle which lasts ~2100 blocks & is split over five windows. # User Types **Observer** -This is basically any active principal in the Stacks network, regardless of whether they hold STX or sBTC. They're not incentivized to *sign* anything, but, they are incentivized to throw a flat (aka start a penalty) if they see an issue with the protocol. Both Current & Registered Signers (below) are subsets of an Observer. +Any active principal in the Stacks network, regardless of whether they hold STX or sBTC. They're not incentivized to *sign* anything, but, they are incentivized to throw a flag (aka start a penalty) if they see an issue with the protocol. Both Current & Registered Signers (below) are subsets of an Observer. -**Registered Signer (N+1)** -This is a principal that is or will register & vote in the current cycle. They are *not,* signers but more so the signers on-deck for the next cycle. +**Pre-Registered Signer** +For the developer release, a pre-registered stacker is an observer that wants to become a signer for at least one future cycle. -**Current Signer (N)** -This is a principal that is currently a signer for the current PoX cycle. +**Registered Signer** +For the developer release, this is a stacker that is now registered to be a signer (for the next cycle); they're either a pre-registered stacker or a current-signer. -**Previous Signer (N-1)** -This is a principal that was the signer during the previous PoX cycle. +**Voted Signer** +For the developer release, this is a registered signer that has now voted for a threshold wallet candidate (for the next cycle). + +**Current Signer** +This is a principal that is a signer for the current PoX cycle. The previous cycle they registered & voted. This current cycle, as a current signer, they can also register & vote for the *next* cycle. # PoX Lifecycle & Functions Below we'll review the PoX lifecycle along with what public functions are avaiable to which user type. **Disbursement [x]** -The disbursement window is the very last step of the **previous** cycle. This is when the PoX rewards from the previous cycle are distributed to the previous signers. Since these rewards are disbursed in Bitcoin, someone needs to verify it on Stacks. +The disbursement window is the first window yet also acts as the final window of the **previous** cycle. This is when the PoX rewards from the *previous* cycle are disbursed to the previous signers. Since these rewards are disbursed in Bitcoin, someone [either Observer or any of the Signer user types] needs to verify the disbursements on Stacks. Observer -> (penalty-pox-reward-disbursement ...) - -Previous Signer -> (prove-rewards-were-disbursed ...) +Observer -> (prove-rewards-were-disbursed ...) **Registration [1600 - x blocks]** -Summary of registration window +Once disbursement has been proven on Stacks, the registration window opens (it's worth noting that this is the only window with a dynamic start height). This is the window when either pre-registered signers or current signers register to be a signer for the next cycle. During this same window, once registered, this is when current signers can vote for a threshold wallet candidate. -Registered Signer -> (register ...) +Pre-registered Signer -> (signer-register ...) +Registered Signer -> (signer-register ...) **Vote [300 blocks]** Summary of vote window From 80433e30566f3c0d9f944abfac4ebda546a4c368 Mon Sep 17 00:00:00 2001 From: jesus Date: Sun, 13 Aug 2023 08:55:55 -0400 Subject: [PATCH 6/6] wip: 1st draft almost completed --- src/pox-contract.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/src/pox-contract.md b/src/pox-contract.md index 5295496..08375f6 100644 --- a/src/pox-contract.md +++ b/src/pox-contract.md @@ -33,20 +33,25 @@ Observer -> (penalty-pox-reward-disbursement ...) Observer -> (prove-rewards-were-disbursed ...) **Registration [1600 - x blocks]** -Once disbursement has been proven on Stacks, the registration window opens (it's worth noting that this is the only window with a dynamic start height). This is the window when either pre-registered signers or current signers register to be a signer for the next cycle. During this same window, once registered, this is when current signers can vote for a threshold wallet candidate. +Once disbursement has been proven on Stacks, the registration window opens (it's worth noting that this is the only window with a dynamic start height). This is the window when either pre-registered signers or current signers register to be a signer for the next cycle. Pre-registered Signer -> (signer-register ...) -Registered Signer -> (signer-register ...) +Current Signer -> (signer-register ...) **Vote [300 blocks]** -Summary of vote window +After, registered signers can vote for the next cycle sBTC threshold/peg-wallet. The goal here is for registered signers to reach a 70% consensus on a candidate. +Observer -> (penalty-pox-reward-disbursement ...) Registered Signer -> (vote-for-threshold-wallet-candidate ...) **Transfer [100 blocks]** -Summary of transfer window +Once the vote windows is over, a new threshold/peg wallet should've been - this is now the window when the current signers can transfer the pegged-sBTC balance to the new threshold wallet (aka passing on the responsibility). Observer -> (penalty-pox-transfer ...) +Observer -> (balance-was-transferred ...) **Penalize [100 blocks]** -Summary of penalty window +The final window before the new cycle starts with the disbursement window; the main role here is for any observer to throw a flag (aka start a penalty) if they see an issue with the protocol. + +Observer -> (penalty-balance-transfer ...) +Observer -> (penalty-unhandled-request ...)