distributed-compliance-ledger

module
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 18, 2022 License: Apache-2.0

README

Distributed Compliance Ledger

License Unit Tests

If you are interested in how to build and run the project locally, please look at README-DEV

Please note, that the only officially supported platform now is Linux. It's recommended to develop and deploy the App on Ubuntu 18.04 or Ubuntu 20.04.

Please note, that there were breaking changes in DCL 0.6 (migration to the latest Cosmos SDK), so the current master and DCL releases 0.6+ are not compatible with pools and Test Nets running DCL 0.5.

Overview

DC Ledger is a public permissioned Ledger which can be used for two main use cases:

  • ZB/Matter compliance certification of device models
  • Public key infrastructure (PKI)

More information about use cases can be found in DC Ledger Overview and Use Case Diagrams.

DC Ledger is based on Tendermint and Cosmos SDK.

DC Ledger is a public permissioned ledger in the following sense:

In order to send write transactions to the ledger you need:

  • Have a private/public key pair
  • Have an Account created on the ledger via ACCOUNT transaction (see Use Case Txn Auth).
    • The Account stores the public part of the key
    • The Account has an associated role. The role is used for authorization policies.
  • Sign every transaction by the private key.

Main Components

Pool of Nodes
  • A network of Tendermint-based validator nodes (Validators and Observers) maintaining the ledger.
  • Every validator node (dcld binary) runs DC Ledger application code (based on Cosmos SDK) implementing the use cases.
  • See the proposed deployment in deployment and deployment-detailed.
Node Types
  • Full Node: contains a full replication of data (ledger, state, etc.):
    • Validator Node (VN): a full node participating in consensus protocol (ordering transactions).
    • Sentry Node: a full nodes that doesn't participate in consensus and wraps the validator node representing it for the rest of the network as one of the ways for DDoS protection.
      • Private Sentry Node: connected to other Validators or Sentry nodes only; should not be accessed by clients.
      • Public Sentry Node: clients and other nodes can access it; basically the same as an Observer node.
    • Observer Node (ON): a full node that doesn't participate in consensus. Should be used to receive read/write requests from the clients. Technically can be a Public Sentry node.
  • Light Client Proxy Node: doesn't contain a full replication of data. Can be used as a proxy to untrusted Full nodes for single-value query requests sent via CLI or Tendermint RPC. It will verify all state proofs automatically.
  • Seed Node: provides a list of peers which a node can connect to.

See

Clients

For interactions with the pool of nodes (sending write and read requests).

Every client must be connected to a Node (either Observer or Validator).

If there is no trusted node for connection, a Light Client Proxy can be used. A Light Client Proxy can be connected to multiple nodes and will verify the state proofs for every single value query request.

Please note, that multi-value queries don't have state proofs support and should be sent to trusted nodes only.

Please make sure that TLS is enabled in gRPC, REST or Light Client Proxy for secure communication with a Node.

Public UI (Outdated, doesn't work with DCL 0.6+)
  • based on the REST API
  • can be used to browse the ledger
    • please note that it doesn't show all the accounts on the ledger
    • it shows only the default (demo) accounts created on the UI server
  • for demo purposes only: can be used for sending write requests from the default (demo) accounts
  • source code and documentation are located in dcl-ui directory

How To

CLI
  • The same dcld binary as a Node
  • A full list of all CLI commands can be found there: transactions.md.
  • CLI can be used for write and read requests.
  • Please configure the CLI before using (see how-to.md).
  • If there are no trusted Observer or Validator nodes to connect a CLI, then a Light Client Proxy can be used.
Light Client Proxy

Should be used if there are no trusted Observer or Validator nodes to connect.

It can be a proxy for CLI or direct requests from code done via Tendermint RPC.

Please note, that CLI can use a Light Client proxy only for single-value query requests. A Full Node (Validator or Observer) should be used for multi-value query requests and write requests.

Please note, that multi-value queries don't have state proofs support and should be sent to trusted node only.

See Run Light Client Proxy for details how to run it.

REST
gRPC
Tendermint RPC and Light Client
  • Tendermint RPC is exposed by every running node at port 26657. See https://docs.cosmos.network/master/core/grpc_rest.html#tendermint-rpc.
  • Tendermint RPC supports state proofs. Tendermint's Light Client library can be used to verify the state proofs. So, if Light Client API is used, then it's possible to communicate with non-trusted nodes.
  • Please note, that multi-value queries don't have state proofs support and should be sent to trusted nodes only.
  • There are currently no DC Ledger specific API libraries for various platforms and languages, but they may be provided in the future.
  • The following libraries can be used as light clients:
Instructions

After the CLI or REST API is configured and Account with an appropriate role is created, the following instructions from how-to.md can be used for every role (see Use Case Diagrams):

  • Trustee
    • propose new accounts
    • approve new accounts
    • propose revocation of accounts
    • approve revocation of accounts
    • propose X509 root certificates
    • approve X509 root certificates
    • propose revocation of X509 root certificates
    • approve revocation of X509 root certificates
    • publish X509 certificates
    • revoke X509 certificates
  • CA
    • propose X509 root certificates
    • publish X509 certificates
    • revoke X509 certificates
  • Vendor
    • publish vendor info
    • publish device model info
    • publish device model version
    • publish X509 certificates
    • revoke X509 certificates
  • Certification Center
    • certify or revoke certification of device models
    • publish X509 certificates
    • revoke X509 certificates
  • Node Admin
    • add a new Validator node
    • publish X509 certificates
    • revoke X509 certificates
Run a local pool of nodes in Docker

See Run local pool section in README-DEV.md.

Deploy a persistent pool of nodes

A recommended way for deployment and client connection: diagram and diagram-detailed.

One can either deploy its own network of validator nodes or join one of the persistent DC Ledger Networks.

  • If you want to deploy your own network for debug purposes, you can use the provided Ansible Playbook: ansible/readme.md.
  • If you want to join an existing network (either a custom or persistent) as a validator node, please follow the Running Node or a more detailed Running a Validator Node instructions.
  • If you want to join an existing network as an observer node, please follow the Running Node or a more detailed Running an Observer Node instructions.
  • If you want to deploy your own persistent network, you will need to create a genesis node and a genesis file first as described in Running Node or a more detailed Running a Genesis Validator Node. Please note, that these instructions describe the case when the genesis block consists of a single node only. This is done just for simplicity, and nothing prevents you from adding more nodes to the genesis file by adapting the instructions accordingly.

Directories

Path Synopsis
cmd
integration_tests
testutil
cli
nullify
Package nullify provides methods to init nil values structs for test assertion.
Package nullify provides methods to init nil values structs for test assertion.
cli
x
compliance/types
Package types is a reverse proxy.
Package types is a reverse proxy.
dclauth/types
Package types is a reverse proxy.
Package types is a reverse proxy.
dclupgrade/types
Package types is a reverse proxy.
Package types is a reverse proxy.
model/types
Package types is a reverse proxy.
Package types is a reverse proxy.
pki
pki/types
Package types is a reverse proxy.
Package types is a reverse proxy.
validator/types
Package types is a reverse proxy.
Package types is a reverse proxy.
vendorinfo/types
Package types is a reverse proxy.
Package types is a reverse proxy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL