:toc: macro

= tBTC

https://circleci.com/gh/keep-network/tbtc[image:https://circleci.com/gh/keep-network/tbtc.svg?style=svg&circle-token=ec728f5ca814b6cb2db5ffeb7258151b752a207e[CircleCI Build Status]] http://docs.keep.network/tbtc/solidity/[image:https://img.shields.io/badge/docs-website-green.svg[Docs]] https://discord.gg/4R6RGFf[image:https://img.shields.io/badge/chat-Discord-blueViolet.svg[Chat with us on Discord]]

tBTC is a trustlessly Bitcoin-backed ERC-20 token.

The goal of the project is to provide a stronger 2-way peg than federated sidechains like https://blockstream.com/liquid/[Liquid], expanding use cases possible via today's Bitcoin network, while bringing superior money to other chains.

This repo contains the Solidity link:solidity/[smart contracts] and link:docs/[specification].

toc::[]

== Getting started

• Read the link:./docs/introduction-to-tbtc.md[introduction to tBTC].
• Read the http://docs.keep.network/tbtc/[specification].
• Consult http://docs.keep.network/tbtc/solidity/[Solidity API documentation].
• For questions and support, join the #tbtc-protocol channel on https://discord.gg/4R6RGFf[Discord].

== Installation

tBTC contracts are currently published in the NPM Registry as the package https://www.npmjs.com/package/@keep-network/tbtc[`@keep-network/tbtc`]. Packages have versions corresponding to their network:

• -pre packages contain prerelease packages for the internal Keep testnet.
• -rc packages contain prerelease packages for the Ropsten Ethereum testnet.

Note that only the latest package in a series is expected to reference contracts that have a backing set of signers.

To install the package:

$ npm install @keep-network/tbtc

== Usage

NOTE: tBTC contracts require solc v0.5.17 or higher. You may have to https://www.trufflesuite.com/docs/truffle/reference/configuration#compiler-configuration[configure solc in your truffle-config.js].

Once installed, you can use the contracts in the library by importing them:

[source,sol]

pragma solidity ^0.5.17;

import "@keep-network/tbtc/contracts/deposit/Deposit.sol";

contract MySystem { function checkTerm(address _depositAddress) external { uint256 remainingTerm = Deposit(_depositAddress).remainingTerm(); } }

== Security

tBTC's first 6-week audit was completed by ConsenSys Diligence on March 27, 2020, against https://github.com/keep-network/tbtc/commit/fbb2018c41456d19ec20eb28a17070ee2b10eb5d[fbb2018c41]. They've published a detailed https://diligence.consensys.net/audits/2020/02/thesis-tbtc-and-keep/[audit report] and https://diligence.consensys.net/audits/2020/03/thesis-cryptographic-review/[cryptographic review].

A Bitcoin-focused audit was conducted by security researcher https://twitter.com/sr_gi[Sergi Delgado] from May 25 to May 31, 2020. You can https://srgi.me/resources/reports/tbtc_audit.pdf[review Sergi's results on his site].

https://www.trailofbits.com/[Trail of Bits] conducted an audit of tBTC in June, 2020, and published a https://github.com/trailofbits/publications/blob/db9414def9f575465a47fef5489eb54d9c543eb5/reviews/thesis-summary.pdf[a summary of their results]. https://github.com/samczsun[`@samczsun`] opened issues he discovered https://github.com/keep-network/tbtc/issues?q=is%3Aissue+author%3Asamczsun[on the repo], all of which have been addressed.

A focused treatment of tBTC's security model can be https://tbtc.network/developers/tbtc-security-model/[found here].

Please dislose any security issues you find or suspect to mailto:[email protected][[email protected]], or to https://keybase.io/shadowfiend[`@shadowfiend`], https://keybase.io/frdwrd[`@frdwrd`], or https://keybase.io/mhluongo[`@mhluongo`] via Keybase.

== Contributing

All contributions are welcome. To report bugs, please create an issue on this repository. To start a discussion, prefer https://discord.gg/4R6RGFf[Discord] over GitHub issues.

Read the https://github.com/keep-network/tbtc/blob/master/CONTRIBUTING.md[Contributing guidelines].

=== Setup environment

You should have installed:

• Node.js, https://docs.npmjs.com/cli/install[npm].
• A local Ethereum blockchain. We recommend https://www.trufflesuite.com/ganache[Ganache].
• https://www.trufflesuite.com/docs/truffle/overview[Truffle framework].

=== Build

Clone and install dependencies:

[source,sh]

git clone https://github.com/keep-network/tbtc cd tbtc/solidity npm install

Deploy contracts:

[source,sh]

truffle migrate --reset

=== Test

Tests are written in JS using Mocha.

To run the test suite, execute truffle test.

To run specific tests, add https://jaketrent.com/post/run-single-mocha-test/[`.only`] to the contract block:

[source,js]

contract.only('TBTCToken', function(accounts) {

=== Lint

We use https://eslint.org/[ESLint] and https://github.com/duaraghav8/Ethlint[Ethlint] for linting code. To run:

[source,sh]

npm run sol:lint:fix npm run js:lint:fix

== Documentation

The documentation includes a project overview and rationale, as well as the on-chain specification. Docs should always be updated before or in tandem with code.

=== Prerequisites

Docs are written in http://asciidoctor.org/[AsciiDoctor], with diagrams in https://asciidoctor.org/docs/asciidoctor-diagram/#mermaid[Mermaid].

==== macOS

Install the dependencies via CLI: + [source,sh]

gem install asciidoctor-pdf --pre brew install poppler

=== Build

[source,sh]

cd docs

Generate index.pdf

asciidoctor-pdf index.adoc

== License

tBTC is released under the link:LICENSE[MIT License].