Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add diagrams to architecture overview #154

Merged
merged 1 commit into from
Jan 31, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,27 @@ There are several components that make up chain-signatures. This includes but is

Note that this list only includes components vital to creating signatures and not the components required to do foreign chain interactions like sending the signature over to ethereum or any other chain. Each of these will be explained further in the following sections.

But first, here is a visual high-level overview.

![diagram](./doc/System%20Architecture%20Overview%20-%20High%20Level.svg)

### NEAR Smart Contract

The contract is simple in terms of functionality. It provides two main functions for users or developers to call into.

- The most common of which is `sign`, which when called will yield back a signature for the user to consume however they wish to. For example, this signature can be used to sign into arbitrary chains given the derivation path of the account of that chain. For more info on how the MPC node picks these `sign` request, refer to the NEAR Lake Indexer section.
- The second method (and should realistically only be used by the MPC nodes themselves), are the `vote_*` methods. These allow the MPC nodes to each individually act as voters into the MPC network, and facilitates the way new nodes join or current nodes get kicked out.

Besides the two methods for users, there are also methods only used by the MPC nodes.

- `respond` is the sibling of `sign`. It takes the completed signature from the MPC network, wakes up a waiting `sign` call and return it back to the calling user.
- `state` and `config` are view calls used by the MPC nodes to read the shared network state.
- `system_load` and `version` are for debugging

The diagram below shows everything the Near smart contract does, combining the network management with the singing functionality, all in one contract.

![diagram](./doc/System%20Architecture%20Overview%20-%20Smart%20Contract.svg)

#### MPC State

Note that each MPC node does not maintain its own state, but rather queries the contract for the contract's state and then directly switch to the corresponding MPC node state. This is how state transitions also happen -- whenever the contract determines it is time to reshare or refresh the shares of the keys, the nodes themselves will properly transition to these corresponding states.
Expand Down
1 change: 1 addition & 0 deletions doc/System Architecture Overview - High Level.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions doc/System Architecture Overview - Smart Contract.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading