stacks-network / sbtc-docs Goto Github PK

As we're getting started putting together the initial documentation, we need to get the first content into place. A good place to start is to write down a high-level description of what sBTC is and how it's working.

Definition of done

• The documentation introduces sBTC, the problem it solves and its purpose.

We need to document the sBTC DR API so that developers understand how to integrate sBTC into their apps.

In the current design, anyone could replay a withdrawal request and cause the protocol to withdraw someone else's sBTC. We should not allow this.

Definition of done

The protocol has been updated so that withdrawal payloads are not replayable.

Enabling sBTC users to pay transaction fees in sBTC will remove friction from the UX and provide a better Bitcoin-native experience.

There is strong user demand for this. For example, Gamma cannot issue NFTs on sBTC without the native mint and gas fees in the same asset (effects the mint contracts).

Some ideas being explored:

1. Sponsored transactions. Transaction fees are handled at the application level. Key questions on implementation: who would pay for the tx fees? Does this approach scale?
2. Users pay in sBTC and an AMM converts to STX. This could present potential edge case issues around slippage and liquidity.
3. Accept as native gas fees on the network. Requires research on Stacks tokeneconomics

Creating this issue to track ideas about how to simplify this UX.

Definition of Done

We have an explanation of what sBTC Mini is, why it is being created, and the technical/economic differences between it and full sBTC.

The withdrawal contracts process withdrawal requests and verify Bitcoin withdrawal transactions.

Withdrawal requests start on Stacks. However, an sBTC holder that does not own any STX can still sign a Stacks transaction and pay transaction fees in sBTC. The protocol exposes a mechanism to submit the withdrawals by means of a sponsored Stacks transaction. The sponsor will then receive an amount of sBTC in return for sponsoring the transaction. A sponsor can decide to sponsor the transaction if they find the fee acceptable.

We need to:

• Explain steps and how redemptions are processed.
• Link back to BTC transaction structure and minimum confirmations required.
• Explain more what the process itself looks like.

The docs are now served in https://stacks-network.github.io/sbtc-docs/. However, mermaid charts are not rendered. We need to install mdbook-mermaid in the GH action deploying the docs to render these charts.

Definition of done

The deployed docs render mermaid charts.

We need to update the design based on the discussion at the Signer hackathon. In the current design, the PoX prepare phase is distinct from the Handoff phase which contains both DKG and Signing. One problem with this, is that we need to separate DKG and signing to distinct phases. In addition to this, the new Nakamoto consensus rules allows us to run the consensus prepare phase in parallel with these phases, and run DKG immediately since the set of Stackers is known throughout the cycle.

Current state

(BTC Blocks)
|----Prepare (80)----|----Handoff (20)----|-----Reward(2000)----|

Proposed update

|------- DKG (80) --------|-----Handoff (20) --------|------Reward(2000)---|

Definition of done:

The docs specify PoX phases which distinguish DKG from Handoff.

Stackers have a lot of responsibilities in sBTC. Let's explain them!

Definition of done

The responsibilities of Stackers is explained in the docs.

The contract that verifies that the hand-off to the next Bitcoin wallet was done properly.

It is mostly automated, but we need to document how it works and who submits hand-off proofs to the component. It is still a critical component to sBTC DR.

We have a placeholder section for how to operate as a Stacker, which should walk potential Stackers through the process of running a Signer binary and connecting to the p2p network of stackers/signers. Although this is not implemented yet, so we'll need to be clear that this is the envisioned interface.

Definition of done

The docs contains easy-to-follow instructions for how to participate in sBTC as a Stacker using the provided signer binary.

A current gap in the spec is the question of what to do if the signers process a deposit anyway while in a bad state?

Situation is as follows:

1. Protocol is a bad state due to whatever reason.
2. User manages to create a deposit request successfully.
3. Signers should not process the deposit request but do it anyway, thus moving the Bitcoin from the escrow address to the peg wallet. (It is on Bitcoin so we cannot prevent it.)
4. Since the protocol is frozen, the protocol will not accept the proof that the Bitcoin was moved.
5. The user now has no Bitcoin and no sBTC.

We had consensus that the protocol would effectively be frozen during a bad state, not allowing deposits and withdrawals. However, that can leave us in an awkward state as seen above.

I think that when the protocol is in a bad state, the onus is on the signers not to process deposits. If they do it anyway for whatever reason, then the protocol should still mint sBTC. In other words, there should be no guard in the deposit processor that would prevent sBTC minting when the protocol is in a bad state.

The sBTC token is implemented as a SIP-010 fungible token. It uses the controller for access control so that the sBTC Protocol contracts may mint and burn sBTC tokens.

Although SIP-010 tokens are second nature for a lot of us, the token contract should still be clearly explained in the docs.

Definition of done

The sBTC docs are served on a nice web page, and updated on every commit to master.

Definition of done

The documentation contains a chapter explaining which functions the new PoX contract should contain, their purpose and who calls them.

Note: This should focus on the public interface and anything critical to the sBTC design. Implementation details may be omitted.

While we have the high level responsibilities of stackers outlined in the docs, we need to specify practically how the signing protocol works so that stackers are able to participate in signing rounds.

We should provide an overview of

1. How FROST signature aggregation works from a high level (also mentioning FIRE and ROAST)
2. The message schema signers use to participate in signing rounds
3. A brief section about the transport layer used for signer communication
4. An introduction to the reference implementation of the signers covering it's architecture and internal state

Some good resources in this issue: https://github.com/Trust-Machines/stacks-sbtc/issues/596

Definition of done

The documentation explains how signers collaborate to sign messages

I'm currently only aware of xBTC, which is the only asset mentioned in the sBTC whitepaper. SIP-021 does not name any peg system, although it suggests that there exist other "state-of-the-art" two-way peg systems.

Definition of done

The introduction section contains an exhaustive list of all known (to us sBTC developers) BTC-wrapped tokens on Stacks.

We had this discussion before on the stacks-sbtc repo. I'm moving it to sbtc-docs for visibility and to perhaps foster a longer discussion and timeline on this—what I think—important question.

Bitcoin transactions can be made more efficient if we allow multiple deposit and withdrawal reveals to exist in a single Bitcoin transaction. Right now it is capped at 1.

Deposit example: if there are 5 pending deposit commitments (funded P2TR escrow addresses) then the Signers could produce a single Bitcoin transaction to consume all of them.

Withdrawal example: if there are 5 pending withdrawal requests then the signers could fulfil all of them in a single Bitcoin transaction.

Hybrid example: if there are 2 pending deposit commitments and 3 pending withdrawal requests, can we settle it all in a single Bitcoin transaction?

Upsides:

• Potentially way fewer Bitcoin transactions.
• Lower fees?

Downsides:

• Added complexity, how to determine which deposits/withdrawals to bundle?
• Clarity limitations and runtime budgets will be reached more quickly. (When verifying the Bitcoin transactions on the Clarity side.)

Related:

• https://github.com/Trust-Machines/stacks-sbtc/issues/409
• https://github.com/Trust-Machines/stacks-sbtc/issues/413

These user stories inform the Product Requirements outlined here.

Also need to ensure that all user stories have requirements and tasks associated with them.

We have to document all errors defined in sBTC DR so that developers integrating sBTC into their apps understand how to handle them.

Definition of done

The roadmap for the sBTC development, with high-level milestones is included in the documentation

Definition of done

The sBTC operations are documented, including a brief description of the different types of operations and how they are represented on-chain.

Ordinals are driving developer interest in the Bitcoin ecosystem. It's imperative for sBTC to have an Ordinal strategy, given the user demand. Ordinals support was included in the original spec for sBTC Mini here and I wrote a more in depth summary of the opportunity here. Now is the time to revisit this topic to ensure sBTC is capable of supporting Ordinals in the future.

Definition of Done
There is an updated design spec for Ordinal support in the sBTC bridge.

The helper library that makes it easier to decode and interpret Bitcoin transaction in Clarity. Any component that receives Bitcoin transactions uses this library. It is an adapted version of an earlier open source library that we have to link.

Anything else we should explain about this component?

We need to define and document all events emitted from the sBTC DR protocol so that developers creating off-chains apps and indexers know what to look for.

The registry contract functions as the main storage space for the protocol. The other components use the registry to store protocol state. It is intended to allow for more seamless upgrades by keeping the registry the same across future soft upgrades.

We need to explain the things the registry stores and why, also how those things are updated. Special attention to be paid to the get-and-update function.

The controller is a single Clarity smart contract that manages which other contracts are part of the protocol. The other contracts use the controller for access control. The controller also exposes a pathway to upgrade the protocol by changing the access list.

We need to explain exactly how it works.

See #33

We need to ensure there is a migration path to upgrade sBTC held in the v0.1 contract to Nakamoto.

Potential solutions:

• Add trait definition to enable the ability to call sBTC held in v0.1 contract
• sBTC v0.1 signers could transfer the BTC to Nakamoto signers and empower Nakamoto signers to handle sBTC v0.1 redemptions (v0.1 sBTC automatically becomes Nakamoto sBTC at time of hard fork)

Currently, the reveal transaction in commit-reveal does not provide any information on the segwit version used to parse the script data. This means that anyone parsing a reveal transaction has to do a UTXO lookup to know how to interpret the witness data. However, we can easily solve this by adding a version byte to the OP_RETURN of the reveal transaction indicating which segwit version the witness data conforms to.

Definition of done

The commit-reveal specification is updated to enable parsing of witness data without looking up UTXOs

Definition of done

The ECDSA signature of the withdrawal requests is documented in a non-ambiguous way.

Background

Marvin created a proof of concept for sBTC 0.1 in which withdrawals are initiated on the stacks chain here: https://github.com/Trust-Machines/stacks-sbtc/pull/595

For Mini it has turned out to be simpler to initiate withdrawals on Stacks, and we suspect that the final design would be simpler if that also were the case.

Let's explore the following three options

• Option 0: Don't change the design
• Option 1: Support initiating withdrawals on Stacks alongside bitcoin operations
• Option 2: Only support initiating withdrawals on Stacks

Definition of done

We have decided on one of the options above and updated the design in line with that option, as well as provide an explanation in the design for the interested reader motivating the design.

The sBTC Stacking pool proper that allows Stackers to participate in the sBTC Protocol. Stackers will participate in the distributed key generation scheme and individually vote on the next Bitcoin wallet address to use. They vote by locking their STX for the next cycle.

The pool is the most extensive contract in sBTC DR. It will need a thorough documentation and is likely deserving of a separate sub page right from the beginning.

Proposal

From this Discord discussion: https://discord.com/channels/621759717756370964/730814571517968436/1135960606919368734

Briefly the idea is to allow a deposit flow with two steps:

1. The user submits a deposit commit transaction. The only deviation from the current spec, is that this transaction cannot be immediately reclaimable by the user. It can be reclaimable through a time lock, as long as it can be proven that only the Stackers can spend this UTXO for the next few reward cycles.
2. The Stackers accept the deposit through a smart contract call on Stacks and mint the sBTC to the user. This call would reveal the witness script committed to in 1. so that anyone can verify that the minted amount is correct.

Motivation:

With this change, users would only have to subsidize a single BTC transaction to deposit - as opposed to the current commit-reveal scheme where they would have to subsidize two transactions.

Definition of done

We have explored the possibility of supporting the deposit flow described above and any related variants, and decided on whether or not to include it in the design.

sBTC introduces a lot of updates to the Stacks consensus rules. We need to have a page outlining how these rules.

Definition of Done

The sBTC additions to the Stacks consensus rules are documented.

Context

In the sprint planning meeting today, it was raised that the current release names are confusing. The current releases are named Alpha, Mini, MVP and 1.0 and are outlined in this doc chapter: https://github.com/stacks-network/sbtc-docs/blob/master/src/sbtc-releases.md

We should create alignment around a better set of names, and rebrand the releases.

Definition of done

• The releases are renamed in the docs and everyone is happy.

Definition of Done

We have an explanation of what sBTC alpha is, and how it differs from the final release. The alpha architecture and components are explained in-depth in subsequent sections and the alpha code is linked.

Two items we should work into the roadmap:

1. Add two security audits. An internal for the Dev release and an external for the Nakamoto release.
2. Include FIRE instead of ROAST as the first crypto algorithm for the signer, and work on ROAST in parallel with the signers.

Context

The current design supports commit-reveal operations as an alternative method of constructing sBTC operations. To use commit-reveal, a user or application is dependent on a trusted entity to act as a revealer - which is the entity consuming the commit transaction and constructing the reveal transaction visible to the sBTC system (and anyone else observing the chain).

While anyone can act as a revealer, we anticipate that there will be low interest in community-provided revealers. Therefore, we'd like to add consensus-level support for commit-reveal, to ensure that sBTC comes with a solution for applications to leverage the commit-reveal protocol.

Definition of done

The sBTC consensus rules are updated to ensure there's always a reliable revealer available.

Currently, the wire formats leave some room for interpretation - for example how an amount integer gets represented as 8 bytes. The docs does not specify if this is using big-endian or little-endian encoding.

Definition of done

There is no ambiguity in the wire formats of the sBTC docs.

Definition of done

Commit-reveal operations are documented.

The deposit contracts verify Bitcoin deposit transactions. They trigger an sBTC mint to the recipient found in the Bitcoin transaction. The transaction format is described in the docs already.

We need to explain how deposits are processed, link back to BTC transaction structure and minimum confirmations required.

Definition of done

Deposit and withdrawal flows of sBTC are explained.

Definition of done

The MVP release of sBTC is Documented, giving an explanation of the first consensus-breaking release of sBTC. What it contains and how it differs from the final product.

Definition of done

The high-level techincal design of sBTC is documented

The sBTC Developer Release makes a bunch of assumptions. These should be documented.

Non-exhaustive list:

• Signers are assumed to be benevolent.
• Focus on "happy paths".

These are defined based on the aspects that sBTC DR is supposed to validate:

• The process of jointly managing a Bitcoin wallet by means of a threshold scheme.
• The ability to verify Bitcoin Taproot transactions in Clarity.
• The ability to mint and burn sBTC based on those transactions.
• Managing the hand-off process.

Document how to bootstrap sBTC DR. It should include:

1. Deploying the contracts.
2. Sending the upgrade transaction to enable the protocol contracts.
3. Getting the pool to an active state so that signers can join and vote.

Definition of done

We have documentation for non-technical users how to deposit and withdraw their sBTC

To introduce the different versions of sBTC, we should have a single page which lists the different versions and outlines the differences between them.

Definition of done

There's an outline introducing the different sBTC versions and their features