Status

Summary

This ADR describes how cheqd/Cosmos account keys can be imported/exported into identity wallet applications built on Evernym VDR Tools SDK.

Context

Client SDK applications such as Evernym VDR Tools need to work with cheqd accounts in identity wallets to be able to interact with the cheqd network ledger.

For example, an identity wallet application or backend application would need to pay network transaction fees for writing cheqd DIDs to the ledger. This may also need to be extended in the future to support peer-to-peer payments for credential exchange.

Assumptions / Considerations

Cosmos SDK uses known algorithms for deriving private keys from mnemonics. This can be replicated using standard crypto libraries to carry out the same steps as in Cosmos SDK:

The mnemonic above is assumed to be a pre-existing one cheqd/Cosmos CLI. The "passphrase" above is user-defined, and defaults to blank if not defined.

Decision

Mnemonic import/export can be achieved using pre-existing BIP39 packages and Cosmos SDK's Rust library cosmrs.

Using these pre-existing libraries, cheqd accounts can be recovered using the standard BIP44 HDPath for Cosmos SDK chains described below:

Consequences

Functionality will be added to VDR Tools SDK to import/export cheqd accounts using mnemonics paired with the --recover flag as done with Cosmos wallets.

Backwards Compatibility

Not applicable, since this is an entirely new feature in VDR Tools SDK for integration with the new blockchain framework.

Positive

• Adding/recovering cheqd accounts in VDR Tools SDK will follow a similar, familiar process that users have for Cosmos wallets.

Negative

N/A

Neutral

N/A

References

• Cosmos SDK account generation and keyrings

Accepted

1. ADR 001: Payment mechanism for issuing credentials

Proposed

Draft

Moved

The following ADRs have been moved to the cheqd identity documentation site

Status

Summary

The aim of this ADR is to define the smallest fraction for CHEQ tokens.

Context

Cosmos SDK doesn't provide native support for token fractions. The lowest denomination out-of-the-box that can be used in transactions is 1token.

To address this issue, similar Cosmos networks assume that they use N digits after the decimal point and multiply all values by 10^(-N) in UI.

Examples of lowest token denominations in Cosmos

Popular Cosmos networks were compared to check how many digits after the decimal point are used by them:

• Cosmos: 6

• IRIS: 6

• Fetch.ai: 18

Decision

Fractions of CHEQ tokens will be referred by their , based on the power of 10 of CHEQ tokens being referred to in context. This notation system is common across other Cosmos networks as well.

It was decided to go with 10^-9 as the smallest fraction, with the whole number token being 1 CHEQ. Based on the SI prefix system, the lowest denomination would therefore be called "nanocheq".

Consequences

Backward Compatibility

• There is no backward compatibility. To adjust the number of digits after the decimal point (lowest token denomination), the network should be restarted.

Positive

• The power of 10 chosen for the lowest denomination of CHEQ tokens is more precise than for Cosmos ATOMs, which allows transactions to be defined in smaller units.

Negative

• This decision is hard to change in the future, as changes to denominations require significant disruption when a network is already up and running.

Neutral

• N/A

References

Status

Summary

Due to the nature of the cheqd project merging concepts from the and self-sovereign identity (SSI), there are two potential options for creating Command Line Interface (CLI) tools for developers to use:

1. Cosmos-based CLI: Most likely route for Cosmos projects for their node application. Most existing Cosmos node validators will be familiar with this method of managing their node.

2. VDR CLI: Traditionally, a lot of SSI networks have used and therefore the Indy CLI tool for managing and interacting with the ledger. This has now been renamed to and is the tool that most existing SSI node operators ("stewards") would be familiar with.

Ideally, the cheqd-node project would provide a consistent set of CLI tools rather than two separate tools with varying feature sets between them.

This ADR will focus on the CLI tool architecture choice for cheqd-node.

Context

Assumptions / Considerations

Likelihood of introducing bugs or security vulnerabilities

1. Any CLI tool architecture chosen should not increase the likelihood of introducing bugs, security vulnerabilities, or design pattern deviations from upstream Cosmos SDK.

2. Actions that are carried out on ledger through a CLI tool in cheqd-node now include token functionality as well as identity functionality. E.g., if a DID gets compromised, there could be mechanisms to recover or signal that fact to issuers/verifiers. If tokens or the staking balance of node operators get compromised, this may potentially have more severe consequences for them.

User / Node Operator preferences

1. Would node operators want a single CLI to manage everything?

   1. This might be the case with node operators from an SSI / digital identity background, or node operators familiar with Hyperledger Indy CLI / VDR Tools CLI.

   2. A “single CLI” could be a single tool as far as the user sees, but actually consist of multiple modules beneath it in how it’s implemented.

Options considered

1. Keep both Cosmos CLI and VDR Tools CLI, but use them for different purposes

Pros:

• Simple to do, no changes needed in code developed.

• Differences in functionality between the two CLIs can be explained in documentation.

• Node operators with good technical skills will understand the difference.

Cons:

• Key storage for Cosmos accounts may need to be done in two different keystores.

• Potentially confusing for node operators who use both CLIs to know which one to use for what purpose.

• Potentially a steeper learning curve for existing SSI node operators.

2. Implement overlapping functionality in both CLI tools

Pros:

• Both Cosmos CLI and VDR Tools CLI would have native support for identity as well as token transactions.

• Node operators/developers could pick their preferred CLI tool.

Cons:

• Significant development effort required to implement very similar functionality two separate times, with little difference to the end user in actions that can be executed.

• VDR Tools CLI has DID / VC modules that would take significant effort to recreate in Cosmos CLI

• Cosmos CLI has token related functionality that would take significant development effort to replicate in VDR Tools CLI, and opens up the possibility that errors in implementation could introduce security vulnerabilities.

3. Create aliases for commands in one of the CLI tools in the other CLI tool

Commands in the Cosmos CLI could be made available as aliases in the VDR Tools CLI, or vice versa.

Pros:

• Single CLI tool to learn and understand for node operators.

• Development effort is simplified, as overlapping functionality is not implemented in two separate tools.

Cons:

• Less development effort required than Option 2, but greater than Option 1.

• Opens up the possibility that there's deviation in feature coverage between the two CLIs if aliases are not created to make 1:1 feature parity in both tools.

Decision

Based on the options considerations above and an analysis of development required, the decision was taken to maintain two separate CLI tools:

1. cheqd-node Cosmos CLI: Any Cosmos-specific features, such as network & node management, token functionality required by node operators, etc.

2. VDR Tools CLI: Any identity-specific features required by issuers, verifiers, holders on SSI networks.

CLI tools feature matrix

CLI components overview

(in Excalidraw format)

Consequences

Positive

• Faster time-to-market on the CLI tools, while freeing up time to build out user-facing functionality.

Negative

• Cosmos account keys may need to be replicated in two separate key storages. A potential resolution for this in the future is to integrate the ability to use a single keyring for both CLI tools.

Neutral

• Seek feedback from cheqd's open source community and node operators during testnet phase on whether the documentation and user experience is easy to understand and appropriate tools are available.

References

Status

Status

Summary

The aim of this ADR is to define how will work on cheqd network.

Context

What is "community tax"?

communityTax is a value set in genesis for each Cosmos network and defined as a percentage that is applied to the fees collected in each block.

Tokens collected through this process accumulate in the community pool. The percentage charged as communityTax can be changed by by the network.

Community tax collection

From :

The community pool gets community_tax * fees, plus any remaining dust after validators get their rewards that are always rounded down to the nearest integer value.

Community tax distribution

To spend tokens from the community pool:

1. community-pool-spend proposal can be submitted on the network.

   1. Recipient address and amount of tokens should be specified.

   2. The purpose for which the requested community pools tokens will be spent should be described.

More information about fee distribution is available in the documentation.

Decision

• cheqd's network will keep the communityTax parameter enabled, i.e., non-zero.

• The value of communityTax, based on a review of similar Cosmos networks will be set to 2%.

Consequences

Backward Compatibility

• The behavior of communityTax is the across Cosmos SDK v0.42 and v0.43.

Positive

• The cheqd network will have a pool of tokens that can be used to spend on initiatives valued by the community.

Negative

• N/A

Neutral

• cheqd's Governance Framework should provide guidance on how to submit proposals and recommended areas of investment in community efforts.

References

Status

What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?

Summary

A short (~100 word) description of the issue being addressed. "If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the ADR.

Context

This section describes the forces at play, such as business, technological, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. It should clearly explain the problem and motivation that the proposal aims to resolve.

ADR-specific Details

This section describes the implementation and/or architecture approach for the proposed changes in detail.

Consequences

This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future.

Backwards Compatibility

All ADRs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The ADR must explain how the author proposes to deal with these incompatibilities. ADR submissions without a sufficient backwards compatibility treatise may be rejected outright.

Positive

{positive consequences}

Negative

{negative consequences}

Neutral

{neutral consequences}

References

• {reference link}

Unresolved questions

{list of questions or action items}

Status

Summary

Issued credentials need to be revocable by their issuers. Revocation needs to be straightforward and fast. Testing of revocation needs to preserve privacy (be non-correlating), and it should be possible to do without contacting the issuer.

Context

This has obvious use cases for professional credentials being revoked for fraud or misconduct, e.g., a driver’s license could be revoked for criminal activity. However, it’s also important if a credential gets issued in error (e.g., has a typo in it that misidentifies the subject). The latter case is important even for immutable and permanent credentials such as a birth certificate.

In addition, it seems likely that the data inside credentials will change over time (e.g., a person’s mailing address or phone number updates). This is likely to be quite common, revocation can be used to guarantee currency of credential data when it happens. In other words, revocation may be used to force updated data, not just to revoke authorization.

Decision

REVOC_REG_DEF

Adds a Revocation Registry Definition, that Issuer creates and publishes for a particular Credential Definition. It contains public keys, maximum number of credentials the registry may contain, reference to the Credential Definition, plus some revocation registry specific data.

• value (dict):

  Dictionary with Revocation Registry Definition's data:

  • max_cred_num (integer): The maximum number of credentials the Revocation Registry can handle

Note: REVOC_REG_DEF can be updated.

State format

(owner, cred_def_id, revoc_def_type, tag) -> {data, tx_hash, tx_timestamp }

Request Example:

Reply Example:

REVOC_REG_ENTRY

The Revocation Registry Entry contains the new accumulator value and issued/revoked indices. This is just a delta of indices, not the whole list. It can be sent each time a new credential is issued/revoked.

• value (dict):

  Dictionary with revocation registry's data:

  • accum (string): The current accumulator value

Note: REVOC_REG_ENTRY can be updated.

State format

1. MARKER_REVOC_REG_ENTRY_ACCUM:revoc_reg_def_id -> {data, tx_hash, tx_timestamp }

2. MARKER_REVOC_REG_ENTRY:revoc_reg_def_id -> {data, tx_hash, tx_timestamp }

Request Example:

Reply Example:

References

Status

Summary

This ADR will define how Verifiable Credential schemas can be represented through the use of a DID URL, which when dereferenced, fetches the credential schemas a resource. The identity entities and transactions for the cheqd network are designed to support usage scenarios and functionality currently supported by .

Context

Hyperledger Indy is a verifiable data registry (VDR) built for DIDs with a strong focus on privacy-preserving techniques. It is one of the most widely-adopted SSI blockchain ledgers. Most notably, Indy is used by the .

Identity-domain transaction types in Hyperledger Indy

Our aim is to support the functionality enabled by into cheqd-node. This will partly enable the goal of allowing use cases of existing SSI networks on Hyperledger Indy to be supported by the cheqd network.

The following identity-domain transactions from Indy were considered:

1. NYM: Equivalent to "DIDs" on other networks

2. ATTRIB: Payload for DID Document generation

3. SCHEMA: Schema used by a credential

Revocation registries for credentials are not covered under the scope of this ADR. This topic is discussed separately in as there is ongoing research by the cheqd project on how to improve the privacy and scalability of credential revocations.

Decision

CL Schema

CL-Schema resource can be created via CreateResource transaction with the follow list of parameters:

MsgCreateResource:

• Collection ID: UUID ➝ (did:cheqd:...:) ➝ Parent DID identifier without a prefix

• ID: UUID ➝ specific to resource, also effectively a version number (supplied client-side)

• Name: String (e.g., CL-Schema1 ) ➝ Schema name

CLI Example:

Credential Definition

[TODO: explain that a Cred Def is simply an additional property inside of the Issuer's DID Doc]

Adds a Credential Definition (in particular, public key), which is created by an Issuer and published for a particular Credential Schema.

It is not possible to update Credential Definitions. If a Credential Definition needs to be evolved (for example, a key needs to be rotated), then a new Credential Definition needs to be created for a new Issuer DIDdoc. Credential Definitions is added to the ledger in as verification method for Issuer DIDDoc

• id: DID as base58-encoded string for 16 or 32 byte DID value with Cheqd DID Method prefix did:cheqd:<namespace>: and a resource type at the end.

• value (dict): Dictionary with Credential Definition's data if signature_type is CL:

CRED_DEF entity transaction format:

Don't store Schema DIDDoc in the State.

CredDef URL: did:cheqd:mainnet-1:N22KY2Dyvmuu2PyyqSFKue

CredDef Entity URL: did:cheqd:mainnet-1:N22KY2Dyvmuu2PyyqSFKue?service=CL-CredDef

CRED_DEF DID Document transaction format:

CRED_DEF state format:

"credDef:<id>" -> {CredDefEntity, txHash, txTimestamp}

Note: CRED_DEF cannot be updated.

Rationale and Alternatives

Schema options not used

Schema. Option 2

Schema URL: did:cheqd:mainnet-1:N22KY2Dyvmuu2PyyqSFKue#<schema_entity_id>

SCHEMA DID Document transaction format:

Schema. Option 3

Schema URL: did:cheqd:mainnet-1:N22KY2Dyvmuu2PyyqSFKue

SCHEMA DID Document transaction format:

Schema. Option 4

Schema URL: did:cheqd:mainnet-1:N22KY2Dyvmuu2PyyqSFKue#<schema_entity_id>

SCHEMA DID Document transaction format:

SCHEMA State format:

• "schema:<id>" -> {SchemaEntity, txHash, txTimestamp}

id example: did:cheqd:mainnet-1:N22KY2Dyvmuu2PyyqSFKue

Cred Def options not used

Cred Def. Option 2

Store inside Issuer DID Document

CredDef URL: did:cheqd:mainnet-1:N22KY2Dyvmuu2PyyqSFKue#<cred_def_entity_id>

CRED_DEF DID Document transaction format:

CRED_DEF state format:

Positive

• Credential Definition is a set of Issuer keys. So storing them in Issuer's DIDDoc reasonable.

Negative

• Credential Definition name means that it contains more than just a key and value field provides this flexibility.

• Adding all Cred Defs to Issuer's DIDDoc makes it too large. For every DIDDoc or Cred Def request a client will receive the whole list of Issuer's Cred Defs.

• Impossible to put a few controllers for Cred Def.

References

• official project background on Hyperledger Foundation wiki

  • GitHub repository: Server-side blockchain node for Indy ()

  • GitHub repository: Plenum Byzantine Fault Tolerant consensus protocol; used by indy-node

Status

Summary

The aim of this document is to define the genesis parameters that will be used in cheqd network testnet and mainnet.

Cosmos v0.44.3 parameters are described.

Context

Genesis consists of Tendermint consensus engine parameters and Cosmos app-specific parameters.

Tendermint consensus parameters

Tendermint requires to be defined for basic consensus conditions on any Cosmos network.

Block parameters

Evidence parameters

Validator key parameters

Cosmos SDK module parameters

Cosmos application is divided . Each module has parameters that help to adjust the module's behaviour.

auth module

bank module

cheqd module (DID module)

crisis module

distribution module

gov module

mint module

resource module

slashing module

staking module

ibc module

ibc-transfer module

Decision

The parameters above were agreed separate the cheqd mainnet and testnet parameters. We have bolded the testnet parameters that differ from mainnet.

Consequences

Backward Compatibility

• The token denomination has been changed to make the smallest denomination 10^-9 CHEQ (= 1 ncheq) instead of 1 CHEQ. This is a breaking change from the earliest versions of the cheqd testnet that which required issuing new tokens to be transferred and issued to testnet node operators.

Positive

• Inflation allows fees to be collected from block rewards in addition to transaction fees.

• In production/mainnet, parameters can only be changed via a majority vote without veto defeat according to the cheqd network governance principles. This allows for more democratic governance frameworks to be created for a self-sovereign identity network.

Negative

• Existing node operators will need to re-establish staking with new staking denomination and staking parameters.

Neutral

• Unbonding period, and deposit period have all been reduced to 2 weeks to balance the speed at which decisions can be reached vs giving enough time to validators to participate.

References