[Design]: Bootstrap signer components

[netrome]

Completing the issue description and arriving at a conclusion is the deliverable of this issue.

Design - Bootstrap signer components

This ticket defines the main components which constitute the sBTC bootstrap signer and how they interact to fulfill deposits and withdrawals in sBTC v1.

1. Summary

We have broken down the sBTC bootstrap signer into the following main components

• Block observer
• Signer set manager
• Decision engine
• Transaction signer
• Transaction coordinator
• Request sequencer

building on top of these supporting modules

• Bitcoin interface
• Stacks interface
• Deposit API interface
• Signer network
• sBTC transactions

2. Context & Purpose

The sBTC bootstrap signer should be able to coordinate the creation of transactions, maintain shared custody of a bitcoin wallet, and make smart contract calls in the .sbtc contract. To manage the complexity of this system, we want to break it down into multiple loosely coupled components of separate functionality.

Relevant Research Discussions

• [Design]: sBTC Signer Behavior and Communication #34
• [Research]: Can we verify Schnorr signatures in Clarity? #33
• [Research]: Signer Coordinator Selection and Failover #39
• [Research]: Signer control plane API #40
• [Research]: Signer Coordinator Activity Execution Location #37
• [Research]: Deposit API Service (formerly Revealer API) #18

External Resources

3. Design

3.1 Proposed Component Design

The bootstrap signer is responsible for:

• Storing the signer DKG shares and private network key
• Observing and reacting to sBTC requests
• Coordinating DKG and signing rounds when needed

To fulfill these duties, we have identified the following sub-components of functionality in the Signer.

Block observer

The block observer is the component responsible for populating the bitcoin and stacks blocks in the state. In addition, the observer should parse any requests, responses or other transactions it observes and populate the corresponding pieces of the state.

Signer set manager

The signer set manager is the component orchestrating signer bootstrapping, key rotation and DKG.

Decision engine

The decision engine exposes an extendible interface for deciding whether to accept or reject a sBTC request.

Transaction signer

The transaction signer is responsible for participating in WSTS signing rounds for any approved transactions.

Transaction coordinator

The transaction coordinator is responsible for orchestrating WSTS signing rounds, and submitting the resulting transactions to the blockchain.

Request sequencer

The request sequencer is responsible for creating the next sBTC transaction for the coordinator to handle in a signing round given the signer state.

Bitcoin interface

Support module that helps the signer interact with the Bitcoin blockchain.

Stacks interface

Support module that helps the signer interact with the Stacks blockchain.

Deposit API interface

Support module that allows the signer to communicate with the Deposit API.

Signer network

Module that provides an interface to allow signers to talk to each other.

sBTC transactions

Library that helps the signer create and validate sBTC specific transactions.

3.1.1 Design diagram

The following picture contains the main components for the signers. Lower components are more fundamental and have less dependencies, whereas the higher components typically depend on the pieces below them. They are color coded according to:

• Yellow: Interacts with a blockchain.
• Blue: Has network interactions.
• Green: Does not depend on anything outside of the signer state.

Furthermore, this picture illustrates their main interactions with each other and the signer state.

Component interaction walkthrough

The above chart can be a mouthful at first glance, so let's walk through what happens in the signer.

1. The block observer populates the signer with chain state data

The block observer is responsible for constructing the signer's view of the state of Bitcoin and Stacks. In practice, this means that the block observer populates all tables outlined in #44 except for deposit_signers, withdraw_signers and dkg_shares.

It uses the Stacks and Bitcoin interface to get block data from the respective chains. The relevant data is extracted and stored in the appropriate tables. The block observer interacts with the Deposit API interface to know of pending deposit requests, and it communicates status updates back to the Deposit API.

2. The signers start listening and reacting to DKG and Signing round messages

The signers listen to inbound messages for DKG and signing rounds, and participate in these processes.

3. The Signer set manager coordinates DKG

The signer set manager can observe the current signer set in the database. Using this information, the signer set manager is able to coordinate a DKG round and set the aggregate key in the .sbtc contract.

4. The signers observe requests and communicate their decisions.

The signers observes all pending requests that they have not yet made a decision for. For these requests, the signer calls the decision engine to decide whether to accept or reject the request. These decisions are stored in the database and communicated to the other signers over the signer network.

The signer listens to all decisions coming in from other signers and stores these decisions in its own database as well.

5. The transaction coordinator constructs and coordinates signing for transaction responses

The transaction coordinator observes the signer state and fetches all pending requests, along with the signer decisions. This information is passed to the request sequencer which constructs the next sBTC transaction to be signed and broadcasted. The coordinator coordinates a signing round for this transaction and broadcasts the signed transaction to either the Stacks or Bitcoin blockchain depending on which transaction it is.

3.1.2 Considerations & Alternatives

3.2 Areas of Ambiguity

This is a very high level overview of the signer operations and leaves room for further low-level design for the individual components.

---

Closing Checklist

• The design proposed in this issue is clearly documented in the description of this ticket.
• Everyone necessary has reviewed the resolution and agrees with the proposal.
• This ticket has or links all the information necessary to familiarize a contributor with the design decision, why it was made, and how it'll be included.

[AshtonStephens]

We want to include how the signers are chosen and "stored".

[hstove]

Can you add state regarding how we can fetch current BTC market fees and fees paid to specific BTC transactions?

[netrome]

Can you add state regarding how we can fetch current BTC market fees and fees paid to specific BTC transactions?

Sure, I'm thinking that is something we'll fetch directly from the nodes - for example with ElectrumApi::estimate_fee.

[netrome]

I'll add some more elaborate component diagrams, and given how large and detailed the state model is I think it makes sense to break it out to it's own LLD design doc.

[netrome]

I have slimmed this down now. Dumping some of the sections that I have removed which could be useful input for LLD documents:

Signer set management

For sBTC to be operational, we must have a set of active signers and an aggregate key. These signers are governed through the following clarity functions.

Function name	Parameters	Description
set-aggregate-key	(aggregate_key, signatures)	Sets the aggregate key in the contract to the given value. signatures is a list of ECDSA signatures as defined in #36
update-signer-set	(keys_to_remove, keys_to_add, signatures)	Removes all keys in keys_to_remove and adds all the keys in keys_to_add to the signer set

The set of sBTC signers is stored in the .sbtc contract as a list of secp256k1 public keys. The signers can call a function set-aggregate-key to set the aggregate key for the sBTC system that deposit requests should be paid to. This function can be called at any point in time to change the aggregate key for sBTC deposits.
The individual keys may also be changed by the signers by collectively calling a function update-signer-set.

Coordinating DKG

To have an aggregate key, the signers must run DKG. DKG is triggered through the signer set manager, which act as the DKG coordinator. Once triggered the coordinator will do the following.

1. Run a DKG round
2. Compute the aggregate key
3. Gather signatures for calling set-aggregate-key
4. Call set-aggregate-key

Coordinating signer set update

If a signer wants to rotate keys, the signer set must be updated. This is also managed by the signer set manager. In this scenario, the signer set manager does the following.

1. Gather signatures for calling update-signer-set
2. Call update-signer-set

Signer reaction to sBTC requests

Each signer must observe Bitcoin, Stacks and the sBTC Deposit API. On every new Bitcoin block a Signer will:

1. Poll the Deposit API for any pending deposit requests in this block
2. Query Stacks for any pending withdrawal requests being confirmed by this block
   • Note: a withdrawal request must have 6 bitcoin confirmations before being considered "confirmed".
3. For each request, decide to accept or reject.
4. Persist and distribute votes to the other signers.

Coordinating signing rounds

For every bitcoin block, a coordinator is selected to coordinate signing rounds for that particular block. The coordinator will

1. Create a set of sBTC transactions to fulfill the inbound requests.
2. For each transaction:
   2.1 Coordinate a signing round for the transaction
   2.2 Gather signatures for any following contract call on Stacks
   2.3 Broadcast the transactions

[netrome]

TODO: Add another version of the component interaction chart which illustrates in which order the interactions happen for a deposit or withdrawal request.

[netrome]

I have added a walkthrough section after the component interaction chart, which goes over the pieces of the chart one by one. Let me know if this is helpful or if you'd like me to elaborate more on any aspect.

[netrome]

Closing now as the team is beginning to shift focus from design to implementation.