keep-ecdsa
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.
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.shDirectory 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-
Keep smart contracts are implemented here.
-
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.
-
All additional packages live in
pkg/. -
The high-level interfaces for a package
mypackagelive inmypackage.go.chainis an interface package that expose a common interface to blockchain layer. Its subpackages provide particular implementations. Onlycmd/and the main package should interact with the implementations directly. -
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:generateannotation to trigger appropriate code generation. All code generation is done with a single invocation ofgo generateat 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:
-
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.1622664847754The 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