keep-ecdsa

README

:toc: macro

= keep-ecdsa

https://github.com/keep-network/keep-ecdsa/actions/workflows/contracts.yml[image:https://img.shields.io/github/workflow/status/keep-network/keep-ecdsa/Solidity/master?event=push&label=Solidity build[Solidity contracts build status]]
https://github.com/keep-network/keep-ecdsa/actions/workflows/client.yml[image:https://img.shields.io/github/workflow/status/keep-network/keep-ecdsa/Solidity/master?event=push&label=Go build[Go client build status]]
https://discord.gg/wYezN7v[image:https://img.shields.io/badge/chat-Discord-blueViolet.svg[Chat with us on Discord]]

The on- and off-chain pieces of ECDSA keeps and Bonded ECDSA keeps
for the Keep network. Builds on top of and requires the
https://github.com/keep-network/keep-core/[core system]

This is development documentation, to see how to run ECDSA client on
mainnet or testnet, please visit link:docs/run-keep-ecdsa.adoc[Run Keep ECDSA client].

toc::[]



== Contracts

See link:./solidity/[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.

==== link:docs/[`docs/`]

Specifically developer documentation for the various parts of Keep ECDSA.

=== link:solidity/[`solidity/`]

The smart contracts behind the ECDSA keeps.

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

=== link:pkg/[`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:

* https://docs.keep.network/development/local-keep-network.html[set
up local ethereum chain],
* link:#Configuration[config file for the single client] (default name:
`+config.toml+`),
* link:./solidity/README.md#NPM-dependencies[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
https://github.com/golang/go/wiki/Modules[Modules] feature.


==== Build

To build execute a command:

[source,sh]
----
# Regenerate Solidity bindings
go generate ./...

go build .
----

==== Test

To test execute a command:

[source,sh]
----
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:

[source,sh]
----
cd solidity/
truffle exec integration/smoke_test.js --network local
----