You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Migrate Credentials docs from opensource.ripple.com
Apply suggestions from @tequdev review
Co-authored-by: tequ <git@tequ.dev>
Add credential transactions and amendment to common links
Add not-enabled warnings on Credentials docs.
description: Create and manage credentials on the blockchain, which can provide authorization for payments or other features, while respecting privacy and decentralization.
5
+
status: not_enabled
6
+
---
7
+
# Credentials
8
+
9
+
The Credentials feature is a set of tools for managing authorization and compliance requirements using the XRP Ledger blockchain, while respecting privacy and decentralization. This feature extends and interconnects with other features of the XRP Ledger including [Deposit Authorization](../../concepts/accounts/depositauth.md)). The goal of this feature is to streamline the process of compliance checks such as [KYC (Know Your Customer)](https://en.wikipedia.org/wiki/Know_your_customer) and to enable further trust-based applications within the XRP Ledger ecosystem.
10
+
11
+
The design of the Credentials standard draws from the [W3C Verifiable Credentials standard](https://www.w3.org/TR/vc-data-model-2.0/). It is intended to be compatible to an extent that makes sense in the context of the XRP Ledger. There are some differences in data structures and formatting: for example, the subject of a credential is identified by an XRP Ledger address rather than a URL.
12
+
13
+
_(Requires the [Credentials amendment][] {% not-enabled /%})_
14
+
15
+
## Overview
16
+
17
+
_Credentials_ are signed statements that can be stored in the ledger and can attest to a user's identity, legal status, or other status. This feature includes issuance, storage, and verification of credentials directly on the XRP Ledger, while still supporting the privacy needs of users.
18
+
19
+
This feature set is designed for an ecosystem of parties with the following roles:
20
+
21
+
-_Authorizers_ who want to limit specific actions or interactions to users who possess the correct credentials.
22
+
-_Issuers_ who provide credentials to users who meet their criteria.
23
+
-_Users_ who obtain credentials from issuers and use those credentials to interact with authorizers.
24
+
25
+
Each credential applies to a specific user's XRP Ledger account, and is attested by a specific credential issuer. The exact qualifications that a credential entails are open-ended, and defined by their issuers. They can range from trivial to serious, or broad to narrow. Some examples of things a credential could state:
26
+
27
+
- That a user is not a subject of sanctions by a particular nation or set of nations.
28
+
- That a user has accredited investor status in the US.
29
+
- That a user has reached a specific level in a particular video game.
30
+
31
+
### Uses
32
+
33
+
Within the XRP Ledger, you can use Deposit Authorization to automatically allow senders with the correct set of credentials, instead of approving sending accounts individually. Future amendments could further extend credentials to gate access to other features such as holding tokens, participating in lending pools, or contributing to an AMM.
34
+
35
+
Credentials stored in the XRP Ledger can also be used to authorize off-ledger activities, especially in association with a decentralized identifier.
36
+
37
+
## Usage Flow
38
+
39
+
A typical flow to use Credentials involves three parties with different roles, as described in the following example:
40
+
41
+
* Verity is a regulated business that wants to interact only with properly KYC'd accounts, to ensure legal compliance. This makes Verity an _authorizer_ because they configure which accounts are allowed (authorized) to interact with them.
42
+
* Isabel is a credential issuer who vets accounts and issues credentials attesting that the accounts are who they say they are.
43
+
* Alice is a user who wants to interact with Verity.
44
+
45
+
All three parties need XRP Ledger accounts. The flow works as follows:
46
+
47
+
1. Verity sets up their account so that only authorized accounts can interact with them. Since they trust Isabel to properly vet accounts and issue relevant credentials, they configure their account to accept credentials issued by Isabel.
48
+
2. Alice submits whatever documents are necessary to Isabel privately, off-chain.
49
+
3. Isabel examines Alice's documents and creates a credential attesting to Alice's trustworthiness.
50
+
4. Alice accepts the credential, making it valid.
51
+
5. Alice can now interact with/send funds to Verity.
52
+
53
+
Importantly, the documents that Alice sends to Isabel can include personally identifiable or private information that's needed to verify Alice's identity, but this information is never published or stored on the blockchain and Verity does not need to see it. Also, other businesses that trust Isabel can accept the same credentials so Alice does not need to repeatedly re-verify for every party she wants to interact with.
54
+
55
+
To revoke a credential, Isabel can delete it from the ledger. Alice can also delete her own credentials.
@@ -56,9 +57,10 @@ In addition to the general fields above, you must specify *exactly 1* of the fol
56
57
{% admonition type="warning" name="Caution" %}If you specify more than 1 of these type-specific fields in a request, the server retrieves results for only 1 of them. It is not defined which one the server chooses, so you should avoid doing this.{% /admonition %}
57
58
58
59
59
-
### Get Ledger Object by ID
60
+
### Get Ledger Entry by ID
61
+
<aid="get-ledger-object-by-id"></a><!-- legacy ID -->
60
62
61
-
Retrieve any type of ledger object by its unique ID.
63
+
Retrieve any type of ledger entry by its unique ID.
@@ -111,7 +113,8 @@ You can use this type of request to get any singleton ledger entry, if it exists
111
113
112
114
113
115
114
-
### Get AccountRoot Object
116
+
### Get AccountRoot Entry
117
+
<aid="get-accountroot-object"></a><!-- legacy ID -->
115
118
116
119
Retrieve an [AccountRoot entry](../../../protocol/ledger-data/ledger-entry-types/accountroot.md) by its address. This is roughly equivalent to the [account_info method][].
|`credential`| Object or String | Yes | Specify the Credential to retrieve. If a string, must be the [ledger entry ID][] of the entry, as hexadecimal. If an object, requires `subject`, `issuer`, and `credential_type` sub-fields. |
309
+
|`credential.subject`| String - [Address][]| Yes | The account that is the subject of the credential. |
310
+
|`credential.issuer`| String - [Address][]| Yes | The account that issued the credential. |
311
+
|`credential.credential_type`| String - Hexadecimal | Yes | The type of the credential, as issued. |
<aid="get-directorynode-object"></a><!-- legacy ID -->
298
357
299
358
Retrieve a [DirectoryNode](../../../protocol/ledger-data/ledger-entry-types/directorynode.md), which contains a list of other ledger objects. Can be provided as string (object ID of the Directory) or as an object.
Retrieve an [Offer entry](../../../protocol/ledger-data/ledger-entry-types/offer.md), which defines an offer to exchange currency. Can be provided as string (unique index of the Offer) or as an object.
Retrieve an [Escrow entry](../../../protocol/ledger-data/ledger-entry-types/escrow.md), which holds XRP until a specific time or condition is met. Can be provided as string (object ID of the Escrow) or as an object.
<aid="get-depositpreauth-object"></a><!-- legacy ID -->
665
731
666
732
Retrieve a [DepositPreauth entry](../../../protocol/ledger-data/ledger-entry-types/depositpreauth.md), which tracks preauthorization for payments to accounts requiring [Deposit Authorization](../../../../concepts/accounts/depositauth.md).
|`deposit_preauth`| Object or String | Specify the DepositPreauth to retrieve. If a string, must be the [ledger entry ID](../../../protocol/ledger-data/common-fields.md) of the DepositPreauth entry, as hexadecimal. If an object, requires `owner` and `authorized` sub-fields. |
671
-
|`deposit_preauth.owner`| String - [Address][]|_(Required if `deposit_preauth` is specified as an object)_ The account that provided the preauthorization. |
672
-
|`deposit_preauth.authorized`| String - [Address][]|_(Required if `deposit_preauth` is specified as an object)_ The account that received the preauthorization. |
|`deposit_preauth`| Object or String | Yes | Specify the DepositPreauth to retrieve. If a string, must be the [ledger entry ID][] of the DepositPreauth entry, as hexadecimal. If an object, requires `owner` sub-field and either `authorized` or `authorize_credentials` sub-field. |
737
+
|`deposit_preauth.owner`| String - [Address][]| Yes | The account that provided the preauthorization. |
738
+
|`deposit_preauth.authorized`| String - [Address][]| No | The account that received the preauthorization. |
739
+
|`deposit_preauth.authorized_credentials`| Array | No | A set of credentials that received the preauthorization. |
740
+
741
+
Each member of the `deposit_preauth.authorized_credentials` array, if provided, must include the following nested fields:
Retrieve a [Ticket entry](../../../protocol/ledger-data/ledger-entry-types/ticket.md), which represents a [sequence number][] set aside for future use. _(Added by the [TicketBatch amendment][])_
0 commit comments