ADR 001: Payment mechanism for issuing credentials
Last updated
Last updated
Category | Status |
---|---|
The Hyperledger Aries 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.
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.
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 Hyperledger Aries credential offer RFC.
A payment request can then be defined using the Hyperledger Aries Payment Decorator 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.
The payment flow can be broken down into five steps:
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
to_account
: Same as payeeId
from the Payment Request
amount_for_transfer
: Price of credential issuance defined as details.total.amount.value
from the Payment Request
denom
: Defined in details.total.amount.currency
from the Payment Request
Build a transaction with the request from the previous step Example: cheqd_ledger::auth::build_tx(pool_alias, pub_key, builded_request, account_number, account_sequence, max_gas, max_coin_amount, denom, timeout_height, memo)
memo
: This should be the same as details.id
from the Payment Request
Sign the transaction Example:cheqd_keys::sign(wallet_handle, key_alias, tx)
.
Broadcast the signed transaction Example: cheqd_pool::broadcast_tx_commit(pool_alias, signed)
.
Key fields in the response above are:
hash
: Transaction hash
height
: Ledger height
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.
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
.
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.
REPLACE WITH PNG
Editable version available on swimlanes.io or as text for compatible UML diagram generators below:
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.
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.
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.
N/A
Authors
Ankur Banerjee
ADR Stage
PROPOSED
Implementation Status
Not Implemented
Start Date
2021-09-01