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 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" } } 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..a8f2c5bc7 --- /dev/null +++ b/typescript/README.md @@ -0,0 +1,141 @@ +# tBTC v2 SDK + +[![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/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 +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).