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

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 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 . This may also need to be extended in the future to support .

Assumptions / Considerations

Cosmos SDK uses . 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 . The "passphrase" above is user-defined, and defaults to blank if not defined.

Decision

Mnemonic import/export can be achieved using pre-existing packages and .

Using these pre-existing libraries, cheqd accounts can be recovered using the standard 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

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

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

Summary

The protocol describes a payment mechanism that can used to pay for the issuance of credentials.

It is necessary to establish which public APIs from Hyperledger Aries can be implemented in cheqd-node to provide an implementation of payments using CHEQ tokens using a well-understood SSI protocol.

Decision

Hyperledger Aries protocol has the concept of payment "decorators" ~payment_request and ~payment_receipt in requests, that can be used to pay using tokens for credential issuance.

Step 1: Credential Offer

A message is sent by the Issuer to the potential Holder, describing the credential they intend to offer and optionally, the price the issuer would be expected to be paid for said credential. This is based on the .

A payment request can then be defined using the to add information about an issuing price and address where payment should be sent.

• details.id field contains an invoice number that unambiguously identifies a credential for which payment is requested. When paying, this value should be placed in memo field for the cheqd payment transaction.

• payeeId field contains a cheqd account address in the correct format for cheqd network.

Step 2: Payment transaction flow

The payment flow can be broken down into five steps:

1. Build a request for transferring tokens. Example: cheqd_ledger::bank::build_msg_send(from_account, to_account, amount_for_transfer, denom)

   • from_account: The prospective credential holder's cheqd account address

Response format

Key fields in the response above are:

• hash: Transaction hash

• height: Ledger height

Step 3: Credential Request

This is a message sent by the potential Holder to the Issuer, to request the issuance of a credential after tokens are transferred to the nominated account using a Payment Transaction.

request_id should be the same as details.id from Payment Request and memo from Payment Transaction.

Step 4: Check payment_receipt

Issuer receives Credential Request + payment_receipt with payment transaction_id. It allows the Issuer to:

• Get the payment transaction by hash from cheqd network ledger using get_tx_by_hash(hash) method, where hash is transaction_id from previous steps.

• Check that memo field from received transaction contains the correct request_id.

Step 5: Credential issuing

If steps 1-4 are successful, the Issuer is able to confirm that the requested payment has been made using CHEQ tokens. The credential issuing process can then proceed using standard Hyperledger Aries protocol procedures.

Overview of steps 1-5

REPLACE WITH PNG

UML version

Editable version available on or as text for compatible UML diagram generators below:

Consequences

Backward Compatibility

• Credential issuance outside of the payment flow is compatible with and carried out using existing Hyperledger Aries protocol procedures. This should provide a level of compatibility with existing apps/SDKs that implement Aries protocol.

• Defining the transaction in CHEQ tokens is specific to the cheqd network.

Positive

• By defining the payment mechanism using Hyperledger Aries protocols, this allows the possibility in the future to support payments on multiple networks.

• Existing SSI app developers should already be familiar with Hyperledger Aries (if building on Hyperledger Indy) and provides a transition path to add new functionality.

Negative

• Hyperledger Aries may not be a familiar protocol for other Cosmos projects.

• Using the Payment Decorator in practice means there could be interoperability challenges at in implementations that impact credential issuance and exchange.

Neutral

• N/A

References

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

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