keep-core
keep-core copied to clipboard
The smart contracts and reference client behind the Keep network
= keep-core
https://github.com/keep-network/keep-core/actions/workflows/contracts-v1.yml[image:https://img.shields.io/github/workflow/status/keep-network/keep-core/Solidity/master?event=push&label=Solidity build[Solidity contracts build status]] https://github.com/keep-network/keep-core/actions/workflows/client.yml[image:https://img.shields.io/github/workflow/status/keep-network/keep-core/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 core contracts and reference client implementation behind the Keep network, a privacy, interoperability, and censorship-resistance toolkit for developers on Ethereum.
== What's a keep?
The network offers application developers keeps, small off-chain data containers for private storage and computation that can be opened, closed, and managed by smart contracts autonomously.
Keeps are maintained by stakers, actors who run nodes and have skin in the game, and collect fees for operating the network. When a new keep is opened, the requisite number of stakers are chosen via a link:https://blog.keep.network/whats-in-a-beacon-12c34b0bc078[BLS-based random beacon] to maintain the keep, using a process called link:https://en.wikipedia.org/wiki/Sortition[sortition].
The first type of keep launching with the network is the BondedECDSAKeep
,
allowing smart contracts to generate private keys and sign messages without
endangering key material. ECDSA keeps mean decentralized signing, cross-chain
applications, and new tools for custodial applications — from Solidity. This
capability is used heavily by https://tbtc.network/[tBTC].
To learn more about ECDSA keeps, check out https://github.com/keep-network/keep-ecdsa[keep-ecdsa].
== Getting Started
A good place to start is the link:docs/[the docs directory].
=== Running a Node
To run your own node in the Keep network, follow the link:docs/run-random-beacon.adoc[run Random Beacon doc]. Feedback on this process and the documentation https://github.com/keep-network/keep-core/issues[is appreciated!]
=== Moving to a new random beacon
The legacy core contracts of the random beacon are moved to the link:solidity-v1/[solidity-v1/
]
directory which can be referred as "v1". The newest "v2" random beacon contracts can
be found in link:solidity/random-beacon/[solidity/random-beacon
] directory.
The full specification of the "v2" random beacon is written in link:/docs/rfc/rfc-19-random-beacon-v2.adoc[rfc-19-random-beacon-v2.adoc
].
=== dApp Developers
dApp developers will be most interested in the smart contracts exposing Keep's on-chain facilities.
The core contracts can be found in the link:solidity-v1/[solidity-v1/
] directory.
They can be used to request
link:solidity-v1/contracts/IRandomBeacon.sol[miner-resistant random numbers], as
well as creating and managing keeps. To generate new ECDSA key material and
request signatures, the contracts can be found in
link:https://github.com/keep-network/keep-ecdsa/blob/main/solidity/contracts/api/IBondedECDSAKeep.sol[keep-ecdsa
].
=== Client Developers
Client developers will be most interested in the link:./main.go[reference Keep Go client] and link:./CONTRIBUTING.adoc[CONTRIBUTORS file], as well as the link:docs/rfc/[RFCs] and repo directory structure 👇
==== Directory structure
The directory structure used in this repository is very similar to that used in other Go projects:
keep-core/
Dockerfile
main.go, *.go
docs/
solidity/ <1>
ecdsa/
random-beacon/
solidity-v1/ <2>
cmd/ <3>
pkg/ <4>
net/
net.go, *.go <5>
libp2p/
chain/
chain.go, *.go <5>
ethereum/
gen/
gen.go <6>
relay/
relay.go, *.go
<1> Core contracts of the Keep contracts. Random beacon contracts are stored under
/solidity/random-beacon
whereas ECDSA under /solidity/ecdsa
.
<2> Legacy core contracts of the random beacon (v1). While the Keep network only uses
Solidity at the moment, the directory structure allows for other contract
languages.
<3> Keep client 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.
<4> All additional packages live in pkg/
.
<5> The high-level interfaces for a package mypackage
live in mypackage.go
.
net
and chain
are interface packages that expose a common interface
to network and blockchain layers. Their subpackages provide particular
implementations of these common interfaces. Only cmd/
and the main
package should interact with the implementations directly.
<6> 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.