From 9134a58ced38316367ccc58e47fee64a593031aa Mon Sep 17 00:00:00 2001 From: Lukasz Zimnoch Date: Thu, 2 Nov 2023 12:43:56 +0100 Subject: [PATCH 1/8] Rework root-level `README` document Push some small updates to the root `README` document. --- CONTRIBUTING.adoc | 4 +-- README.adoc | 81 +++++++++++++++++------------------------------ 2 files changed, 31 insertions(+), 54 deletions(-) diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index a3d6a959b..d92c23f53 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -11,8 +11,8 @@ propose changes to this document in a pull request. 1. Fork https://github.com/keep-network/tbtc-v2[`keep-network/tbtc-v2`] 2. Clone your fork -3. Follow the - link:README.adoc#Installation[installation & build steps] in the README. +3. Each module has their own setup instructions. Follow the README of the + specific module you want to contribute to. 4. Set up the <>. 5. Open a PR against the `main` branch and describe the change you are intending to undertake in the PR description. diff --git a/README.adoc b/README.adoc index 47b109de5..92a6449a6 100644 --- a/README.adoc +++ b/README.adoc @@ -2,9 +2,9 @@ = TBTC v2 -https://github.com/keep-network/tbtc-v2/actions/workflows/contracts.yml[image:https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/contracts.yml?branch=main&event=push&label=TBTC%20contracts%20build[TBTC contracts build status]] -https://github.com/keep-network/tbtc-v2/actions/workflows/typescript.yml[image:https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/typescript.yml?branch=main&event=push&label=TypeScript%20bindings%20build[TypeScript bindings build status]] -https://github.com/keep-network/tbtc-v2/actions/workflows/yearn.yml[image:https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/yearn.yml?branch=main&vent=push&label=Yearn%20build[Yearn build status]] +https://github.com/keep-network/tbtc-v2/actions/workflows/contracts.yml[image:https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/contracts.yml?branch=main&event=push&label=Core%20contracts%20build[Core contracts build status]] +https://github.com/keep-network/tbtc-v2/actions/workflows/typescript.yml[image:https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/typescript.yml?branch=main&event=push&label=SDK%20build[SDK build status]] +https://github.com/keep-network/tbtc-v2/actions/workflows/yearn.yml[image:https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/yearn.yml?branch=main&vent=push&label=Yearn%20contracts%20build[Yearn contracts build status]] https://github.com/keep-network/tbtc-v2/actions/workflows/system-tests.yml[image:https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/system-tests.yml?branch=main&event=schedule&label=System%20tests[System tests status]] https://github.com/keep-network/tbtc-v2/actions/workflows/monitoring.yml[image:https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/monitoring.yml?branch=main&event=push&label=Monitoring%20build[Monitoring build status]] @@ -37,17 +37,7 @@ math, not hardware or people. Additionally, TBTC v2 is open and accessible to anyone. TBTC v2 allows anyone to use Bitcoin in the expanding DeFi and Web3 universe -without a third-party intermediary. - -This repository contains: - -- TBTC v2 link:solidity/[Solidity smart contracts], -- TBTC v2 link:typescript/[Typescript library], -- TBTC v2 link:system-tests/[System tests] -- TBTC v2 link:docs/[documentation], -- TBTC v2 Yearn vault link:yearn/[Solidity smart contracts], -- TBTC v2 link:monitoring/[monitoring tool], -- TBTC v2 Cross-chain link:cross-chain/[smart contracts]. +without a third-party intermediary. toc::[] @@ -64,41 +54,28 @@ Depositing Bitcoin into the tBTCv2 bridge grants a transferable Bank balance, wh can be used to mint a supply-pegged ERC-20: TBTC. For an in-depth explanation about the design, see link:docs/rfc/rfc-1.adoc[RFC 1: tBTCv2 Design]. -== Installation - -=== Prerequisites -* clone the repository -* link:https://nodejs.org/en/[Node.js] v14.21.2 -* yarn: `$ npm install -g yarn` -* configure git to use https - -``` -git config --global url."https://".insteadOf git:// -``` - -* Python 3.11.1 for `node-gyp`. It is - https://opensource.com/article/19/5/python-3-default-mac[suggested] to use - `pyenv` to manage multiple Python versions. -``` -brew install pyenv -pyenv install 3.11.1 -``` - -=== Install and Test Contracts - -``` -cd solidity -yarn install --frozen-lockfile -yarn build -yarn test -yarn test:integration -``` - -=== Install and Test TypeScript Library - -``` -cd typescript -yarn install --frozen-lockfile -yarn build -yarn test -``` +== Repository structure + +This repository contains the following modules: + +- link:solidity/[Core smart contracts], +- link:typescript/[SDK TypeScript library], +- link:system-tests/[System tests] +- link:docs/[Documentation], +- link:yearn/[Yearn vault smart contracts], +- link:monitoring/[Monitoring tool], +- link:cross-chain/[Cross-chain smart contracts]. + +Please refer module-level README for specific module's installation and +usage instructions. + +== Contributing + +Contributions are always welcome! Feel free to open any issue or send a +pull request. Please see link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] to +learn more. + +== Security + +Please see link:SECURITY.adoc[SECURITY.adoc] to learn more about +tBTC v2 security policy. \ No newline at end of file From d7b7b1d357ea2ad66171f142e13e9ed0890c7341 Mon Sep 17 00:00:00 2001 From: Lukasz Zimnoch Date: Thu, 2 Nov 2023 14:34:37 +0100 Subject: [PATCH 2/8] Rework `README` of the typescript SDK Here we rework the SDK `README` document by providing basic guidance for both contributors and integrators. Apart from that, we are changing the file type from `*.adoc` to `*.md`. This is because only Markdown files are properly displayed in the npm registry and. Moreover, we do not use AsciiDoc features in this file anyway. --- typescript/README.adoc | 55 ------------------ typescript/README.md | 127 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 127 insertions(+), 55 deletions(-) delete mode 100644 typescript/README.adoc create mode 100644 typescript/README.md diff --git a/typescript/README.adoc b/typescript/README.adoc deleted file mode 100644 index 9d518ab76..000000000 --- a/typescript/README.adoc +++ /dev/null @@ -1,55 +0,0 @@ -:toc: macro - -= tBTC v2 TypeScript bindings - -https://github.com/keep-network/tbtc-v2/actions/workflows/typescript.yml[image:https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/typescript.yml?branch=main&event=push&label=TypeScript%20bindings%20build[TypeScript bindings build status]] - -This package provides TypeScript bindings to the tBTC v2 system. - -toc::[] - -== Build, test and deploy - -=== Prerequisites - -Please make sure you have the following prerequisites installed on your machine: - -- https://nodejs.org[Node.js] >=16 -- https://yarnpkg.com[Yarn] >=1.22.19 - -=== Install dependencies - -To install dependencies, run: -``` -yarn install -``` - -**NOTE:** The `@keep-network/tbtc.ts` package contains an indirect dependency to -`@summa-tx/relay-sol@2.0.2` package, which downloads one of its sub-dependencies -via unathenticated `git://` protocol. That protocol is no longer supported by -GitHub. This means that in certain situations installation of the package or -update of its dependencies using Yarn may result in `The unauthenticated git -protocol on port 9418 is no longer supported` or `fatal: unable to connect -to github.com` errors. - -As a workaround, we advise changing Git configuration to use `https://` protocol -instead of `git://` by executing: - -``` -git config --global url."https://".insteadOf git:// -``` - -=== Build - -To build the library, invoke: -``` -yarn build -``` -A `dist` directory containing the resulting artifacts will be created. - -=== Test - -To run unit tests, do: -``` -yarn test -``` \ No newline at end of file diff --git a/typescript/README.md b/typescript/README.md new file mode 100644 index 000000000..7b3e28ed4 --- /dev/null +++ b/typescript/README.md @@ -0,0 +1,127 @@ +# tBTC v2 SDK + +![SDK build status](https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/typescript.yml?branch=main&event=push&label=SDK%20build) + +tBTC SDK is a TypeScript library that provides effortless access to the +fundamental features of the tBTC Bitcoin bridge. The SDK allows developers +to integrate tBTC into their own applications and offer the power of +trustless tokenized Bitcoin to their users. + +**Table of contents:** + +* [Quickstart](#quickstart) + * [Installation](#installation) + * [Usage](#usage) +* [Contributing](#contributing) + * [Prerequisites](#prerequisites) + * [Install dependencies](#install-dependencies) + * [Build](#build) + * [Test](#test) + * [Format](#format) +* [Documentation](#documentation) + +## Quickstart + +Here you can find instructions explaining how to use the SDK in your own +project. + +### Installation + +To install the tBTC SDK in your project using `yarn`, run: +```bash +yarn add @keep-network/tbtc-v2.ts +``` +If you prefer to use `npm`, do: +```bash +npm i @keep-network/tbtc-v2.ts +``` + +Please note that you will also need to install the +[ethers v5](https://docs.ethers.org/v5) library to initialize +a signer or provider. To do so using `yarn`, invoke: +```bash +yarn add ethers@legacy-v5 +``` +To do the same using `npm`, run: +```bash +npm i ethers@legacy-v5 +``` + +> The SDK depends on ethers v5. Proper support for newer ethers versions +> is not guaranteed right now. + +### Usage + +Here is a short example demonstrating SDK usage: +```typescript +// Import SDK entrypoint component. +import { TBTC } from "@keep-network/tbtc-v2.ts" + +// Create an instance of ethers signer. +const signer = (...) + +// Initialize the SDK. +const sdk = await TBTC.initializeMainnet(signer) + +// Access SDK features. +sdk.deposits.(...) +sdk.redemptions.(...) + +// Access tBTC smart contracts directly. +sdk.tbtcContracts.(...) + +// Access Bitcoin client directly. +sdk.bitcoinClient.(...) +``` + +## Contributing + +Contributions are always welcome! Feel free to open any issue or send a pull request. +Please refer the repository-level +[CONTRIBUTING.adoc](https://github.com/keep-network/tbtc-v2/blob/main/CONTRIBUTING.adoc) +document for general contribution guidelines. Below, you can find how to set up +the SDK module for development. + +### Prerequisites + +Please make sure you have the following prerequisites installed on your machine: + +* [node.js](https://nodejs.org) >=16 +* [yarn](https://classic.yarnpkg.com) >=1.22 or [npm](https://github.com/npm/cli) >=8.11 + +> Although the below commands use `yarn` you can easily use `npm` instead. + +### Install dependencies + +To install dependencies, run: +```bash +yarn install +``` + +### Build + +To build the library, invoke: +```bash +yarn build +``` +A `dist` directory containing the resulting artifacts will be created. + +### Test + +To run unit tests, do: +```bash +yarn test +``` + +### Format + +To format code automatically, invoke: +```bash +yarn format:fix +``` + +## Documentation + +This README provides just a basic guidance. Comprehensive documentation for +this SDK can be found on the +[Threshold Network Docs website](https://docs.threshold.network/app-development/tbtc-v2/tbtc-sdk). \ No newline at end of file From 309dcc38a4ed6496f9a743c860c2d531af2a6d9a Mon Sep 17 00:00:00 2001 From: Lukasz Zimnoch Date: Thu, 2 Nov 2023 14:36:17 +0100 Subject: [PATCH 3/8] Add SDK repository info to the `package.json` --- solidity/package.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/solidity/package.json b/solidity/package.json index 1cf41a0a5..7cf2be864 100644 --- a/solidity/package.json +++ b/solidity/package.json @@ -76,5 +76,10 @@ }, "engines": { "node": ">= 14.0.0" + }, + "repository": { + "type": "git", + "url": "https://github.com/keep-network/tbtc-v2.git", + "directory": "typescript" } } From 063608958f26257ead3bee326c391d1142475fff Mon Sep 17 00:00:00 2001 From: Lukasz Zimnoch Date: Thu, 2 Nov 2023 14:45:56 +0100 Subject: [PATCH 4/8] Re-format SDK `README` file --- typescript/README.md | 58 ++++++++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 23 deletions(-) diff --git a/typescript/README.md b/typescript/README.md index 7b3e28ed4..230fa55bd 100644 --- a/typescript/README.md +++ b/typescript/README.md @@ -2,57 +2,64 @@ ![SDK build status](https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/typescript.yml?branch=main&event=push&label=SDK%20build) -tBTC SDK is a TypeScript library that provides effortless access to the -fundamental features of the tBTC Bitcoin bridge. The SDK allows developers -to integrate tBTC into their own applications and offer the power of +tBTC SDK is a TypeScript library that provides effortless access to the +fundamental features of the tBTC Bitcoin bridge. The SDK allows developers +to integrate tBTC into their own applications and offer the power of trustless tokenized Bitcoin to their users. **Table of contents:** -* [Quickstart](#quickstart) - * [Installation](#installation) - * [Usage](#usage) -* [Contributing](#contributing) - * [Prerequisites](#prerequisites) - * [Install dependencies](#install-dependencies) - * [Build](#build) - * [Test](#test) - * [Format](#format) -* [Documentation](#documentation) +- [Quickstart](#quickstart) + - [Installation](#installation) + - [Usage](#usage) +- [Contributing](#contributing) + - [Prerequisites](#prerequisites) + - [Install dependencies](#install-dependencies) + - [Build](#build) + - [Test](#test) + - [Format](#format) +- [Documentation](#documentation) ## Quickstart -Here you can find instructions explaining how to use the SDK in your own +Here you can find instructions explaining how to use the SDK in your own project. ### Installation To install the tBTC SDK in your project using `yarn`, run: + ```bash yarn add @keep-network/tbtc-v2.ts ``` + If you prefer to use `npm`, do: + ```bash npm i @keep-network/tbtc-v2.ts ``` -Please note that you will also need to install the -[ethers v5](https://docs.ethers.org/v5) library to initialize +Please note that you will also need to install the +[ethers v5](https://docs.ethers.org/v5) library to initialize a signer or provider. To do so using `yarn`, invoke: + ```bash yarn add ethers@legacy-v5 ``` + To do the same using `npm`, run: + ```bash npm i ethers@legacy-v5 ``` -> The SDK depends on ethers v5. Proper support for newer ethers versions +> The SDK depends on ethers v5. Proper support for newer ethers versions > is not guaranteed right now. ### Usage Here is a short example demonstrating SDK usage: + ```typescript // Import SDK entrypoint component. import { TBTC } from "@keep-network/tbtc-v2.ts" @@ -77,23 +84,24 @@ sdk.bitcoinClient.(...) ## Contributing Contributions are always welcome! Feel free to open any issue or send a pull request. -Please refer the repository-level +Please refer the repository-level [CONTRIBUTING.adoc](https://github.com/keep-network/tbtc-v2/blob/main/CONTRIBUTING.adoc) -document for general contribution guidelines. Below, you can find how to set up +document for general contribution guidelines. Below, you can find how to set up the SDK module for development. ### Prerequisites Please make sure you have the following prerequisites installed on your machine: -* [node.js](https://nodejs.org) >=16 -* [yarn](https://classic.yarnpkg.com) >=1.22 or [npm](https://github.com/npm/cli) >=8.11 +- [node.js](https://nodejs.org) >=16 +- [yarn](https://classic.yarnpkg.com) >=1.22 or [npm](https://github.com/npm/cli) >=8.11 > Although the below commands use `yarn` you can easily use `npm` instead. ### Install dependencies To install dependencies, run: + ```bash yarn install ``` @@ -101,14 +109,17 @@ yarn install ### Build To build the library, invoke: + ```bash yarn build ``` + A `dist` directory containing the resulting artifacts will be created. ### Test To run unit tests, do: + ```bash yarn test ``` @@ -116,12 +127,13 @@ yarn test ### Format To format code automatically, invoke: + ```bash yarn format:fix ``` ## Documentation -This README provides just a basic guidance. Comprehensive documentation for +This README provides just a basic guidance. Comprehensive documentation for this SDK can be found on the -[Threshold Network Docs website](https://docs.threshold.network/app-development/tbtc-v2/tbtc-sdk). \ No newline at end of file +[Threshold Network Docs website](https://docs.threshold.network/app-development/tbtc-v2/tbtc-sdk). From 9337e82c5ed3d517614e5c35e179dee1d5cd1c47 Mon Sep 17 00:00:00 2001 From: Lukasz Zimnoch Date: Thu, 2 Nov 2023 15:17:31 +0100 Subject: [PATCH 5/8] Add npm badge to the SDK module --- typescript/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/typescript/README.md b/typescript/README.md index 230fa55bd..053adbb43 100644 --- a/typescript/README.md +++ b/typescript/README.md @@ -1,6 +1,7 @@ # tBTC v2 SDK ![SDK build status](https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/typescript.yml?branch=main&event=push&label=SDK%20build) +![npm](https://img.shields.io/npm/v/%40keep-network%2Ftbtc-v2.ts) tBTC SDK is a TypeScript library that provides effortless access to the fundamental features of the tBTC Bitcoin bridge. The SDK allows developers From e3c135a5d0e03ffea16a6f0b1012673893a065cc Mon Sep 17 00:00:00 2001 From: Lukasz Zimnoch Date: Thu, 2 Nov 2023 15:24:10 +0100 Subject: [PATCH 6/8] Fix badges links in the SDK module --- typescript/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/typescript/README.md b/typescript/README.md index 053adbb43..65fa41b3c 100644 --- a/typescript/README.md +++ b/typescript/README.md @@ -1,7 +1,7 @@ # tBTC v2 SDK -![SDK build status](https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/typescript.yml?branch=main&event=push&label=SDK%20build) -![npm](https://img.shields.io/npm/v/%40keep-network%2Ftbtc-v2.ts) +[![build](https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/typescript.yml?branch=main&event=push&label=build)](https://github.com/keep-network/tbtc-v2/actions/workflows/typescript.yml) +[![npm](https://img.shields.io/npm/v/%40keep-network%2Ftbtc-v2.ts)](https://www.npmjs.com/package/@keep-network/tbtc-v2.ts) tBTC SDK is a TypeScript library that provides effortless access to the fundamental features of the tBTC Bitcoin bridge. The SDK allows developers From 28e5bfb857811c2301eb382e54cd6f64325c1a99 Mon Sep 17 00:00:00 2001 From: Lukasz Zimnoch Date: Thu, 2 Nov 2023 16:02:37 +0100 Subject: [PATCH 7/8] Add GitBook documentation badge to the SDK module --- typescript/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/typescript/README.md b/typescript/README.md index 65fa41b3c..a1eb5e383 100644 --- a/typescript/README.md +++ b/typescript/README.md @@ -2,6 +2,7 @@ [![build](https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/typescript.yml?branch=main&event=push&label=build)](https://github.com/keep-network/tbtc-v2/actions/workflows/typescript.yml) [![npm](https://img.shields.io/npm/v/%40keep-network%2Ftbtc-v2.ts)](https://www.npmjs.com/package/@keep-network/tbtc-v2.ts) +[![documentation](https://badgen.net/static/GitBook/Documentation/blue)](https://docs.threshold.network/app-development/tbtc-v2/tbtc-sdk) tBTC SDK is a TypeScript library that provides effortless access to the fundamental features of the tBTC Bitcoin bridge. The SDK allows developers From 6f8ec87a169ac42b106e1fa231e9dc7a4d2f04d3 Mon Sep 17 00:00:00 2001 From: Lukasz Zimnoch Date: Thu, 2 Nov 2023 16:10:57 +0100 Subject: [PATCH 8/8] Change GitBook badge color --- typescript/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/typescript/README.md b/typescript/README.md index a1eb5e383..a8f2c5bc7 100644 --- a/typescript/README.md +++ b/typescript/README.md @@ -2,7 +2,7 @@ [![build](https://img.shields.io/github/actions/workflow/status/keep-network/tbtc-v2/typescript.yml?branch=main&event=push&label=build)](https://github.com/keep-network/tbtc-v2/actions/workflows/typescript.yml) [![npm](https://img.shields.io/npm/v/%40keep-network%2Ftbtc-v2.ts)](https://www.npmjs.com/package/@keep-network/tbtc-v2.ts) -[![documentation](https://badgen.net/static/GitBook/Documentation/blue)](https://docs.threshold.network/app-development/tbtc-v2/tbtc-sdk) +[![documentation](https://badgen.net/static/GitBook/Documentation/yellow)](https://docs.threshold.network/app-development/tbtc-v2/tbtc-sdk) tBTC SDK is a TypeScript library that provides effortless access to the fundamental features of the tBTC Bitcoin bridge. The SDK allows developers