Add limitations for DR 0.1, update local devenv (#103)

* feat: add limitations * chore: replace peg with sbtc wallet, rm DR 0.2 * chore: update ports, add links, add versions, add wallet setup
stacks-network · Oct 19, 2023 · b7e190c · b7e190c
1 parent 639da0f
commit b7e190c
Show file tree

Hide file tree

Showing 11 changed files with 82 additions and 58 deletions.
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -40,7 +40,7 @@
 - [sBTC Releases](./sbtc-releases.md)
   - [sBTC 0.1](./sbtc-releases/sbtc-dev.md)
     - [FAQ](./sbtc-releases/sbtc-dev/faq.md)
-  - [sBTC 0.2](./sbtc-releases/sbtc-dev-v2.md)
+    - [Known Limitations](./sbtc-releases/sbtc-dev/limitations.md)
   - [sBTC 1.0](./sbtc-releases/sbtc-nakamoto.md)
   - [sBTC 1.1](./sbtc-releases/sbtc-nakamoto-v2.md)
 

diff --git a/src/deposit.md b/src/deposit.md
@@ -59,16 +59,16 @@ export default function DepositForm() {
       "https://bridge.sbtc.tech/bridge-api/testnet/v1/sbtc/init-ui"
     );
     const data = await response.json();
-    const pegAddress = data.sbtcContractData.sbtcWalletAddress;
+    const sbtcWalletAddress = data.sbtcContractData.sbtcWalletAddress;
 
-    // if we are working via devnet we can use the helper to get the peg address, which is associated with the first wallet
-    // const pegAccount = await testnet.getBitcoinAccount(WALLET_00);
-    // const pegAddress = pegAccount.tr.address;
+    // if we are working via devnet we can use the helper to get the sbtc wallet address, which is associated with the first wallet
+    // const sbtcWalletAccount = await testnet.getBitcoinAccount(WALLET_00);
+    // const sbtcWalletAddress = sbtcWalletAccount.tr.address;
 
     const tx = await sbtcDepositHelper({
       // comment this line out if working via devnet
       network: TESTNET,
-      pegAddress,
+      sbtcWalletAddress,
       stacksAddress: userData.profile.stxAddress.testnet,
       amountSats: satoshis,
       // we can use the helper to get an estimated fee for our transaction

diff --git a/src/local-setup.md b/src/local-setup.md
@@ -9,14 +9,14 @@ Developers should use docker to setup all required services.
 Here are the basic steps we'll need to follow to get everything running.
 
 1. Launch devnet.
-2. Deploy sbtc contract.
+2. Deploy sbtc contract (happens automatically).
 3. Launch sBTC binary (Alpha romeo engine).
-4. Use sBTC web app (sBTC Bridge) or sbtc cli.
+4. Use sBTC web app (sBTC Bridge) or sbtc cli or your own app.
 
 ### Requirements
 
 - Install [Docker](https://docs.docker.com/engine/install/).
-- Install [Clarinet](https://github.com/hirosystems/clarinet).
+- Install [Clarinet](https://github.com/hirosystems/clarinet) (version 1.8.0 or higher).
 
 ## Launch Devnet
 
@@ -38,28 +38,29 @@ This first build will take a while to complete, but once that's done we just nee
 
 Let's check to make sure things are running by visiting the Stacks explorer and the Bridge app. The Stacks explorer will take a bit get up and running.
 
-- http://localhost:3000/?chain=testnet&api=http://localhost:3999 (Stacks explorer)
-- http://127.0.0.1:8080/ (sBTC Bridge App)
+- [http://127.0.0.1:3020/?chain=testnet&api=http://127.0.0.1:3999](http://127.0.0.1:3020/?chain=testnet&api=http://127.0.0.1:3999) (Stacks explorer)
+- [http://127.0.0.1:8083](http://127.0.0.1:8083) (Bitcoin explorer)
+- [http://127.0.0.1:8080](http://127.0.0.1:8080) (sBTC Bridge App)
 
 ## Deploy Contracts
 
-The local environment defines wallets that are already funded. The deployer wallet is used to deploy the contract using clarinet deployments.
+The deployment of the Clarity contracts `asset.clar` and `clarinet-bitcoin-mini.clar` happens during the launch of devenv.sbtcWalletAddress
 
-You can take a look at the config file at `sbtc/devenv/sbtc/docker/config.json` to see the mnemonic that defines the address that will be the contract owner for sBTC. This is the mnemonic that generates the address that will actually call the `mint` function in the sBTC contract.
+Under the hood, the there is a script `utils/deploy_contracts.sh` that is used to deploy the contracts The local environment defines wallets that are already funded. The deployer wallet is used to deploy the contract using clarinet deployments.
 
-If you take a look at the `sbtc/romeo/asset-contract/settings/Devnet.toml` you can see this mnemonic associated with a specific Stacks address. This will also be the address that will be used to deploy the actual contracts. We'll do that in just a minute.
+## Prepare Wallet
+You can take a look at the config file at `sbtc/devenv/sbtc/docker/config.json` to see the mnemonic that defines the taproot address that will be the contract owner for sBTC. This is the mnemonic that generates the address that will actually call the `mint` function in the sBTC contract.
 
-Download the [Leather wallet](https://leather.io) and import the deployer address mnemonic (`twice kind fence tip hidden tilt action fragile skin nothing glory cousin green tomorrow spring wrist shed math olympic multiply hip blue scout claw`) into it to load that account locally.
-
-You can see the default generated mnemonics for the devnet in the [`devenv` repo](https://github.com/stacks-network/sbtc/devenv).
-
-Now run the following command from within the `devenv` folder to deploy the Clarity contracts `asset.clar` and `clarinet-bitcoin-mini.clar`.
+If you take a look at the `sbtc/romeo/asset-contract/settings/Devnet.toml` you can see this mnemonic associated with a specific Stacks address. This will also be the address that will be used to deploy the actual contracts.
 
+Download the [Leather wallet](https://leather.io) (version 6.11.+) and import the deployer address mnemonic into it to load that account locally.
 ```
-./utils/deploy_contracts.sh
+twice kind fence tip hidden tilt action fragile skin nothing glory cousin green tomorrow spring wrist shed math olympic multiply hip blue scout claw
 ```
 
-This will deploy the contracts and set the owner to the address we generated previously.
+You can see more default generated mnemonics for the devnet in the [`devenv` repo](https://github.com/stacks-network/sbtc/devenv).
+
+In Leather wallet, you see that Account 1 is the deployer. Nevertheless, you can use this account or Account 2 as a normal user.
 
 ## Mint some BTC and sBTC
 
@@ -69,28 +70,28 @@ There are helper scripts to create and broadcast deposit and withdrawal requests
 2. deposit.sh: deposits a random amount of less than 10,000 sats. sBTC will be received by the deployer stacks address.
 3. withdrawal.sh: withdraws a random amount of less than 2,000 sats.
 
-Before running these, make sure the Stacks devnet is running by visiting the explorer at http://127.0.0.1:3000/transactions?chain=testnet&api=http://localhost:3999.
+Before running these, make sure the Stacks devnet is running by visiting the explorer at [http://127.0.0.1:3020/transactions?chain=testnet&api=http://127.0.0.1:3999](http://127.0.0.1:3020/transactions?chain=testnet&api=http://127.0.0.1:3999).
 
 If you get an error, wait a few minutes and refresh. Once that page loads correctly you should be good to go.
 
-First, let's mine some BTC with `./utils/mine_btc.sh 200`. This will mine 200 BTC blocks and ensure our address is funded.
+First, let's mine some BTC with `./utils/mine_btc.sh 200`. This will mine 200 BTC blocks and ensure our address (Account 1 and Account 2) is funded.
 
-If you are using the Leather wallet, you'll want to run this again and make sure that this is mining to the same wallet you are going to use in your sBTC app. To do that, view the Bitcoin address displayed in Leather (make sure you are on Devnet) and add it to the `mine_btc.sh` script at the end like this:
+If you are using the Leather wallet, make sure to use the same secret key as used in devnet (deployer wallet). If you are using a different secret key you'll want to run this again and make sure that this is mining to the same wallet you are going to use in your sBTC app. To do that, view the Bitcoin address displayed in Leather (make sure you are on Devnet) and add it to the `mine_btc.sh` script at the end like this:
 
 ```bash
-$dir/../bitcoin/bin/bitcoin-cli generatetoaddress $num_blocks 'bcrt1q3tj2fr9scwmcw3rq5m6jslva65f2rqjxfrjz47'
+btc_address='bcrt1q3tj2fr9scwmcw3rq5m6jslva65f2rqjxfrjz47'
 ```
 
-Next we can initiate a deposit, which will deposit a random amount of satoshis from our Bitcoin wallet into the sBTC threshold wallet, minting sBTC in the process.
+Next we can initiate a deposit, which will deposit a random amount of satoshis from our Bitcoin wallet (Account 2) into the sBTC threshold wallet, minting sBTC in the process.
 
 We can do that with `./utils/deposit.sh`.
 
 And finally, we can do the reverse, convert our sBTC back to BTC, with `./utils/withdraw.sh`.
 
 Check the results on Stacks at our address:
-http://localhost:3000/address/ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM?chain=testnet&api=http://localhost:3999
+[http://localhost:3020/address/ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM?chain=testnet&api=http://localhost:3999](http://localhost:3020/address/ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM?chain=testnet&api=http://localhost:3999)
 
-Check the results on Bitcoin at the txs printed by the utility functions, eg. https://127.0.0.1:3002/tx/38089273be6ed7521261c3a3a7d1bd36bc67d97123c27263e880350fc519899d, replacing the txid parameter with the given tx id.
+Check the results on Bitcoin at the txs printed by the utility functions, eg. [https://127.0.0.1:8083/tx/38089273be6ed7521261c3a3a7d1bd36bc67d97123c27263e880350fc519899d](https://127.0.0.1:8083/tx/38089273be6ed7521261c3a3a7d1bd36bc67d97123c27263e880350fc519899d), replacing the txid parameter with the given tx id.
 
 ## Next Steps
 

diff --git a/src/sbtc-releases.md b/src/sbtc-releases.md
@@ -5,20 +5,19 @@ These are the planned releases:
 | Version | Name (optional)  | Released |
 |---------|------------------|----------|
 | 0.1     | sBTC Developer   |          |
-| 0.2     | sBTC Developer v2|          |
 | 1.0     | sBTC Nakamoto    |          |
 | 1.1     | sBTC Nakamoto v2 |          |
 
 
 The following table highlights the main differences between the releases
 
-|                    | 0.1   | 0.2  | 1.0   | 1.1 |
-|--------------------|-------|------|-------|-----|
-| sBTC token         | ✅    | ✅   | ✅    | ✅  |
-| OP_RETURN data     | ✅    | ✅   | ✅    | ✅  |
-| Commit-Reveal data |       | ✅   | ✅    | ✅  |
-| Mainnet            |       |      | ✅    | ✅  |
-| Open Membership    |       |      | ✅    | ✅  |
-| Consensus breaking |       |      | ✅    | ✅  |
-| Liveness ratio     |       |      |       | ✅  |
-| Recovery mode      |       |      |       | ✅  |
+|                    | 0.1   | 1.0   | 1.1 |
+|--------------------|-------|-------|-----|
+| sBTC token         | ✅    | ✅    | ✅  |
+| OP_RETURN data     | ✅    | ✅    | ✅  |
+| Commit-Reveal data |       | ✅    | ✅  |
+| Mainnet            |       | ✅    | ✅  |
+| Open Membership    |       | ✅    | ✅  |
+| Consensus breaking |       | ✅    | ✅  |
+| Liveness ratio     |       |       | ✅  |
+| Recovery mode      |       |       | ✅  |
diff --git a/src/sbtc-releases/sbtc-dev.md b/src/sbtc-releases/sbtc-dev.md
@@ -37,7 +37,7 @@ For anyone interested in tracking the high-level progress of the Alpha Romeo wor
 4. Ensure the bridge is compatible with the latest release [#86](https://github.com/stacks-network/sbtc/issues/86)
 5. Write developer docs for the release [#77](https://github.com/stacks-network/sbtc-docs/issues/77)
 
-The sBTC contract will be deployed on the Stacks testnet by an address that is still to be defined. See [sbtc/#178](https://github.com/stacks-network/sbtc/issues/178).
+The sBTC contract has be deployed on the Stacks testnet at [ST3VA3Y7A2YQ8GW69T0N1ERPAD784R1Y2YHCSNJHH.asset](https://explorer.hiro.so/txid/ST3VA3Y7A2YQ8GW69T0N1ERPAD784R1Y2YHCSNJHH.asset?chain=testnet).
 
 In sBTC 0.1, the deposit and withdrawal transactions are processed by a central authority (CA). The flow is as follows:
 
@@ -64,9 +64,17 @@ sequenceDiagram
 
 ## Web app
 
-A web interface for the sBTC contract is available at https://bridge.stx.eco/?net=testnet
+### Bridge on Testnet
+A web interface for the sBTC contract on Stacks testnet is available at [https://bridge.sbtc.tech/?net=testnet](https://bridge.sbtc.tech/?net=testnet)
 
-The web app allows to deposit and withdraw btc from the peg wallet. It also provides a list of recent deposit and withdrawal transactions.
+The web app allows to deposit and withdraw btc from the sbtc wallet. It also provides a list of recent deposit and withdrawal transactions.
+
+### Demo application
+An open source application written with next.js is availble at [https://github.com/kenrogers/lagoon](https://github.com/kenrogers/lagoon). This application allows to lend sBTC as well as to deposit and withdraw btc. It is used in the [end to end tutorial](/tutorial.md).
+
+### Wallet support
+
+These applications use sbtc SDK library that works with [Leather wallet version 6.11+](https://github.com/leather-wallet/extension/releases).
 
 ## sBTC cli
 
@@ -81,3 +89,5 @@ Documention is available at [bridge.sbtc.tech](https://bridge.sbtc.tech/bridge-a
 ## sBTC SDK
 
 stacks.js has added support for sBTC deposit and withdrawal requests. Current work in progress can be seen at [stacks.js/feat/add-sbtc-contracts](https://github.com/hirosystems/stacks.js/pull/1554).
+
+The package is published on [npmjs](https://www.npmjs.com/package/sbtc).
diff --git a/src/sbtc-releases/sbtc-dev/faq.md b/src/sbtc-releases/sbtc-dev/faq.md
@@ -2,9 +2,18 @@
 
 ## Devenv
 
-- What is the meaning of the warning in stacks logs `Relayer: Failed to submit Bitcoin transaction`?
+### What is the meaning of the warning in stacks logs `Relayer: Failed to submit Bitcoin transaction`?
   It is a warning related to stacks mining and not relevant to sBTC transactions.
 
-- When I run utils/deploy_contracts.sh, I seen an error `x Error publishing transactions: RecvError
-`. What does it mean?
-  The stacks node is not yet started. Wait for a while and try again.
+### How to check progress when starting devenv? When can I start sending deposits?
+Wait until the stacks block height (`stacks_tip_height`) is 2 or more by checking http://localhost:3999/v2/info.
+Initially, the server won't response.
+
+For more detailed information about the progress you can look at `./logs.sh stacks-api`.
+Wait until you see a message like `Proxy created: /  -> http://stacks:20443`
+
+or
+
+you can look at `./logs.sh stacks`.
+There is a time after Clarity state genesis was computed without log messages. Just keep on waiting...
+See the bitcoin blocks syncing and wait for messages like `Miner: mined anchored block ...`.
diff --git a/src/sbtc-releases/sbtc-dev/get-started-on-devnet.md b/src/sbtc-releases/sbtc-dev/get-started-on-devnet.md
@@ -25,7 +25,7 @@ The default values are set as follows using the same seed phase defined in `rome
 | field        | value                                                                                                                                                | explanation                                             |
 | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
 | seed phrase  | twice kind fence tip hidden tilt action fragile skin nothing glory cousin green tomorrow spring wrist shed math olympic multiply hip blue scout claw | main/deployer wallet, same as in get_credentials script |
-| peg wallet   | bcrt1pte5zmd7qzj4hdu45lh9mmdm0nwq3z35pwnxmzkwld6y0a8g83nnqhj6vc0                                                                                     | taproot address from seed phrase                        |
+| sbtc wallet   | bcrt1pte5zmd7qzj4hdu45lh9mmdm0nwq3z35pwnxmzkwld6y0a8g83nnqhj6vc0                                                                                     | taproot address from seed phrase                        |
 | stx deployer | ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM                                                                                                            | aka wallet.deployer, uses account index 0               |
 | btc deployer | tb1q3tj2fr9scwmcw3rq5m6jslva65f2rqjxt2t0zh                                                                                                           | p2wpkh using account index 0                            |
 | stx Alice    | ST2ST2H80NP5C9SPR4ENJ1Z9CDM9PKAJVPYWPQZ50                                                                                                            | uses account index 1                                    |

diff --git a/src/sbtc-releases/sbtc-dev/limitations.md b/src/sbtc-releases/sbtc-dev/limitations.md
@@ -0,0 +1,5 @@
+# Known Limitation
+
+## Protocol
+* The sbtc wallet is managed by a central authority, not the set of stackers
+* Bitcoin can be deposited to a contract, however, contracts can initiate a withdrawal request. Withdrawal requests can be only submitted via the Bitcoin blockchain.
diff --git a/src/stacker-responsibilities.md b/src/stacker-responsibilities.md
@@ -1,6 +1,6 @@
 # Stacker responsibilities
 
-One of the most significant changes to accomodate the sBTC design is that Stackers must now perform active work to continue receiving PoX rewards. Stackers provide partial signatures for BTC peg-out transactions[the BTC wallet] for the duration of each reward cycle in which their STX are locked. This chapter outlines the new role of the stackers, and how they interact with each other to fulfill their duties.
+One of the most significant changes to accomodate the sBTC design is that Stackers must now perform active work to continue receiving PoX rewards. Stackers provide partial signatures for BTC withdrawal fulfillment transactions[the BTC wallet] for the duration of each reward cycle in which their STX are locked. This chapter outlines the new role of the stackers, and how they interact with each other to fulfill their duties.
 
 ## sBTC wallet address generation
 

diff --git a/src/tutorial.md b/src/tutorial.md
@@ -517,15 +517,15 @@ export default function DepositForm() {
       "https://bridge.sbtc.tech/bridge-api/testnet/v1/sbtc/init-ui"
     );
     const data = await response.json();
-    const pegAddress = data.sbtcContractData.sbtcWalletAddress;
+    const sbtcWalletAddress = data.sbtcContractData.sbtcWalletAddress;
 
     // if we are working via devnet
-    // const pegAccount = await testnet.getBitcoinAccount(WALLET_00);
-    // const pegAddress = pegAccount.tr.address;
+    // const sbtcWalletAccount = await testnet.getBitcoinAccount(WALLET_00);
+    // const sbtcWalletAddress = sbtcWalletAccount.tr.address;
     const tx = await sbtcDepositHelper({
       // comment this line out if working via devnet
       network: TESTNET,
-      pegAddress,
+      sbtcWalletAddress,
       stacksAddress: userData.profile.stxAddress.testnet,
       amountSats: satoshis,
       feeRate: await testnet.estimateFeeRate("low"),
@@ -996,7 +996,7 @@ export default function WithdrawForm() {
 
     const tx = await sbtcWithdrawHelper({
       network: TESTNET,
-      pegAddress: data.sbtcContractData.sbtcWalletAddress,
+      sbtcWalletAddress: data.sbtcContractData.sbtcWalletAddress,
       bitcoinAddress: userData.profile.btcAddress.p2wpkh.testnet,
       amountSats: satoshis,
       signature,

diff --git a/src/withdrawal.md b/src/withdrawal.md
@@ -87,16 +87,16 @@ export default function WithdrawForm() {
       "https://bridge.sbtc.tech/bridge-api/testnet/v1/sbtc/init-ui"
     );
     const data = await response.json();
-    const pegAddress = data.sbtcContractData.sbtcWalletAddress;
+    const sbtcWalletAddress = data.sbtcContractData.sbtcWalletAddress;
 
-    // if we are working via devnet we can use the helper to get the peg address, which is associated with the first wallet
-    // const pegAccount = await testnet.getBitcoinAccount(WALLET_00);
-    // const pegAddress = pegAccount.tr.address;
+    // if we are working via devnet we can use the helper to get the sbtc wallet address, which is associated with the first wallet
+    // const sbtcWalletAccount = await testnet.getBitcoinAccount(WALLET_00);
+    // const sbtcWalletAddress = sbtcWalletAccount.tr.address;
 
     const tx = await sbtcWithdrawHelper({
       // comment this line out if working via devnet
       network: TESTNET,
-      pegAddress,
+      sbtcWalletAddress,
       bitcoinAddress: btcAddress,
       amountSats: satoshis,
       signature,