keep-ecdsa

❗	This repository has been archived. tBTC v1 is no longer actively maintained and has been superseded by tBTC v2. tBTC v2 smart contract code is available in the keep-network/tbtc-v2 repository. tBTC v2 client code is available in the keep-network/keep-core repository.

The on- and off-chain pieces of ECDSA keeps and Bonded ECDSA keeps for the Keep network. Builds on top of and requires the core system

This is development documentation, to see how to run ECDSA client on mainnet or testnet, please visit Run Keep ECDSA client.

Table of Contents

• Contracts
• Getting Set Up
• Directory structure
  • docs/
  • solidity/
  • pkg/
  • Building
  • Go client

Contracts

See solidity directory.

Getting Set Up

If you’re on macOS, install Homebrew and run scripts/macos-setup.sh. Note that if you don’t have Homebrew or you’re not on macOS, the below information details what you’ll need. The script additionally sets up pre-commit hooks.

./scripts/macos-setup.sh

Directory structure

The directory structure used in this Keep repository is very similar to that used in other Go projects:

keep-ecdsa/
  Dockerfile
  main.go, *.go
  docs/
  solidity/ (1)
  cmd/ (2)
  pkg/ (3)
    chain/
      chain.go, *.go (4)
      ethereum/
        gen/
          gen.go (5)
    client/
      client.go, *.go
    ecdsa/
      ecdsa.go, *.go

1. Keep smart contracts are implemented here.

2. Keep subcommands are implemented here, though they should be minimal and deal solely with user interaction. The meat of the commands should exist in a package fit for the appropriate purpose.

3. All additional packages live in pkg/.

4. The high-level interfaces for a package mypackage live in mypackage.go. chain is an interface package that expose a common interface to blockchain layer. Its subpackages provide particular implementations. Only cmd/ and the main package should interact with the implementations directly.

5. When a package requires generated code, it should have a subpackage named gen/. This subpackage should contain a single file, gen.go, with a // go:generate annotation to trigger appropriate code generation. All code generation is done with a single invocation of go generate at build time.

docs/

Specifically developer documentation for the various parts of Keep ECDSA.

solidity/

The smart contracts behind the ECDSA keeps.

They handle creating and managing ECDSA keeps, bridging off-chain secret storage and the public blockchain.

pkg/

The heart of the ECDSA keep Go client.

It runs hosts ECDSA keep nodes, and participates in keep computations.

Building

Currently the easiest way to build the client is using the Dockerfile at the root of the repository. A simple docker build should get you a functioning container.

To build manually, you’ll need to install jq+, truffle, and npm. Then you can follow the steps in the next section.

Quick installation

To quickly install and start a single client use the installation script.

Prerequisites

To run the script some manual preparation is needed:

• set up local ethereum chain,

• config file for the single client (default name: config.toml),

• npm authorized to access private packages in GitHub’s Package Registry.

Please note that the client config file doesn’t have to be pre-configured with contracts addresses as they will be populated during installation.

Install script

The install.sh script will:

• fetch external contracts addresses,

• migrate contracts,

• build client.

The script will ask you for the password to previously created ethereum accounts.

To start the installation execute:

./scripts/install.sh

Initialize script

The initialize.sh script should be called after external customer application contract (i.e. TBTCSystem) using keep-ecdsa is known. The script will:

• set address to the customer application,

• initialize contracts,

• update client contracts configuration.

The script will ask for the client config file path.

It also requires an external client application address which is an address of an external contract that will be requesting keeps creation. For local smoke test execution this address should be the same as the account you will use in the smoke test to request keep opening.

To start the initialization execute:

./scripts/initialize.sh

Start client

To start the client execute:

./scripts/start.sh

Go client

Prerequisites

Building keep-ecdsa requires Go version 1.13 or later.

Dependencies are managed by Modules feature.

Build

To build execute a command:

# Regenerate Solidity bindings
go generate ./...

go build .

Test

To test execute a command:

go test ./...

Configuration

configs/config.toml is default path to the config file. To provide custom configuration CLI supports --config flag. Sample configuration can be found in [config.toml.SAMPLE](configs/config.toml.SAMPLE).

Storage

Users configure the root storage directory at Storage.DataDir. The storage layout looks like:

.
├── archive
│   ├── 0x08E0__ADDRESS__7695fCeb63A70FF85454B683E
│   │   └── membership_046__MEMBERSHIP_ADDRESS__bfa1e3535ae57de
│   ├── 0x33ed__ADDRESS__Bb76baD50EeedfE422793E4ED
│   │   └── membership_046__MEMBERSHIP_ADDRESS__bfa1e3535ae57de
├── bitcoin
│   ├── derivation_indexes
│   │   ├── xpub_zCAk9sk1
│   │   │   └── 513
│   │   ├── ypub_6Z2Yy4ZH
│   │   │   └── 8982
│   │   └── zpub_VDaZuQT9
│   │       └── 8559
├── current
│   ├── 0x14AF__ADDRESS__d8E28c35Ad802d85b3fE12b6c
│   │   └── membership_046__MEMBERSHIP_ADDRESS__bfa1e3535ae57de
│   ├── 0x173b__ADDRESS__A418DdcF2fEb2592A21cd610A
│   │   └── membership_046__MEMBERSHIP_ADDRESS__bfa1e3535ae57de
└── snapshot
    ├── 0x08E0__ADDRESS__7695fCeb63A70FF85454B683E
    │   └── membership_046__MEMBERSHIP_ADDRESS__bfa1e3535ae57de.1622814956119
    └── 0x14AF__ADDRESS__d8E28c35Ad802d85b3fE12b6c
        └── membership_046__MEMBERSHIP_ADDRESS__bfa1e3535ae57de.1622664847754

The archive, current, and snapshot directories are for storing key material. The current directory represents currently active keeps, and the archive directory contains closed and terminated keeps. The snapshot directory exists to guarentee persistence of the key material before it is published on chain.

The bitcoin/derivation_indexes directory is used to store used derivation indexes for extended public keys. Each folder represents a truncated public key and each 0-byte file within those folders represents the largest used index.

Smoke Test

To run a smoke test execute:

cd solidity/
truffle exec integration/smoke_test.js --network local