§ Verifiable Public Registry v2 Specification
Specification Status: Preview
Latest Draft: verana-labs/verifiable-trust-vpr-spec
- Editors:
- Contributors:
- Participate:
§ Abstract
The internet is broken. Existing communication channels are insecure and outdated. Because they rely on public identifiers - like email addresses, usernames, or phone numbers - anyone who knows your identifier can reach you, whether you invited them or not.
Worse, there’s no reliable way to verify the identity of either service providers or users. This leaves the door wide open to spam, phishing, fraud, and identity theft.
On the service side, each provider imposes its own fragmented registration process, often with complex password requirements or forced reliance on federated login systems, effectively handing control over to large third-party platforms.
Although the World Wide Web was originally built for openness and interoperability, dominant players have reshaped it into a closed, centralized system that most people and organizations now depend on. Privacy has become an afterthought, and personal data is routinely harvested, exploited, or leaked.
To rebuild a trustworthy internet, we need new communication channels - channels that are secure by design, based on mutual verification, and governed by decentralized trust.
Connecting to a service, proving who you are, or creating an account should be as simple and safe as presenting a verifiable credential.
A universal, open trust layer is essential for this vision to succeed.
That’s the purpose of Verifiable Trust. The concept of Verifiable Trust is specified in the Verifiable Trust spec.
This specification deals with the Verifiable Public Registry (VPR), a decentralized registry of registries, part of the Verifiable Trust concept.
§ About this Document
In order to fully understand the concepts developed in this document, you should have some basic knowledge of DID, DIDComm, VS, trust registry, ledger-based applications, and more generally, all terms present in the Terminology section.
Before exploring this spec, it is highly recommended to first read the Verifiable Trust Spec.
§ Introduction
§ What is a Trust Registry?
This section is non-normative.
A trust registry is an approved list of recognized ecosystem participants, such as trust registry operators, credential issuers and verifiers that are authorized to onboard ecosystem participants, and or issue/verify certain credentials in an ecosystem.
A trust registry typically expose APIs that are consumed by services that would like to query its database, and take decisions based on the returned result:
- can participant #1 issue credential for
schema
ABC ofecosystem
E1? - can participant #2 request credential presentation of credential issued by
issuer
DEF fromschema
GHI ofecosystem
E2, forjurisdiction
France incontext
CONTEXT?
§ What is a Verifiable Public Registry?
This section is non-normative.
A Verifiable Public Registry (VPR) is a “registry of registries”, a public service that provides foundational infrastructure for decentralized trust ecosystems. It offers:
-
trust registry management:
ecosystems can create and manage their own trust registries, each with:- defined credential schemas
- assigned roles for issuers, verifiers, and grantors (trust registry operators)
- custom business models and permission policies
-
query API for trust resolution:
A standardized API used by verifiable services (VSs) and verifiable user agents (VUAs) to perform trust resolution, enabling them to query registry data and validate roles and permissions in real time.
Additionally, a VPR provides a DID directory, a simple repository of service identifiers (DIDs).
Any account registered in the VPR can add a DID to the DID directory.
This directory is intended to be crawled by indexers, which resolve the listed DIDs, identify associated verifiable services, and index them.
Indexers may expose this data through APIs for querying the indexed services or use it to build a search engine for querying the database of indexed verifiable services.
§ Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.
§ Terminology
- account:
- A verifiable public registry account.
- applicant:
- A account that starts a validation process.
- controller:
- An account which is the controller of a specific resource in an VPR.
- credential schema:
- An VPR resource which represents a verifiable credential definition and the associated permissions and business rules for issuing, verifying or holding a credential linked to this credential schema.
- credential schema permission:
- A permission, linked to a credential schema, that represent, in a given ecosystem, a grant for being issuer, verifier, issuer grantor, or verifier grantor of a credential schema.
- decentralized identifier:
- A decentralized identifier, as specified in [DID-CORE].
- decentralized identifier communication:
- DIDComm uses DIDs to establish confidential, ongoing connections.
- decentralized identifier document:
- A DID Document, as specified in [DID-CORE].
- decentralized web nodes:
- Decentralized web nodes, see DIF spec
- denom:
- Native token of a VPR, example: VNA.
- DID Directory:
- A repository of DIDs in a VPR.
ecosystem: a network of interacting entities, both technical and human, that work together to establish and maintain digital trust. It encompasses applications, credentials, governance frameworks, and the underlying technical infrastructure, all designed to facilitate trustworthy interactions.
- ecosystem governance framework:
- The governance framework (GF) of an ecosystem].
- :
- The governance authority (GA) of an ecosystem.
- entity:
- An account controller.
- estimated transaction fees:
- Estimated fees required, in denom, that is passed when execute a transaction in an VPR. Usually, a estimated transaction fees are always slightly greater than transaction fees, to make sure the execution of the transaction will not be aborted for an out-of-gas situation. Unused gas is refunded to account.
- governance framework:
- The governance framework (GF) of a VPR.
- :
- The governance authority (GA) of a VPR.
- grantor:
- A role an entity is granted by an ecosystem for operating its trust registry.
- holder:
- A role an entity might perform by possessing one or more verifiable credentials and generating verifiable presentations from them. A holder is often, but not always, a subject of the verifiable credentials they are holding. Holders store their credentials in credential repositories. Example holders include organizations, persons, things.
- issuer:
- A role an entity is granted by an ecosystem or an issuer grantor for issuing credentials of a given credential schema to holders.
- issuer grantor:
- A trust registry operator role an entity is granted by an ecosystem for a given credential schema for adding or revoking issuers.
- json schema
- a Json Schema, as specified in https://json-schema.org/specification.
- keeper:
- A storage map(key, value) in the ledger of an VPR.
- linked-vp:
- A presentation of a verifiable credential as specified in LINKED-VP.
- participant:
- An entity that is recognized by one or several ecosystem(s) in a VPR.
- query:
- A read-only action that perform some reading in an VPR and returns value.
- subject:
- A thing about which claims are made. Example subjects include human beings, animals, things, and organization, a DID…
- transaction:
- An action that modifies the ledger of an VPR and which execution requires transaction fees.
- transaction fees:
- Fees required, in denom, to execute a transaction in an VPR.
- trust deposit:
- A financial deposit that is used as a trust guarantee. For a given controller, its trust deposit is increased when running validation process (either as an applicant or as a validator), or when registering DID in the DID directory.
- trust fee:
- Fees paid by a participant that are distributed to other participants.
- network fee:
- Fees paid by a participant that are distributed to network validators and trust deposit holders.
- trust unit:
- Price, in denom, of one unit of trust.
- trust registry
- An approved list of issuers and verifiers that are authorized to issue/verify certain credentials in an ecosystem.
- URI
- An Universal Resource Identifier, as specified in rfc3986.
- valid permission:
- For a given country code, a credential schema permission of a given type, which (country attribute is null or equals to the given country code), and effective_from timestamp is lower than current timestamp, and (effective_until timestamp is null or greater than current timestamp), and revoked is null and terminated is null and slashed is null.
- validation process:
- A process run by applicants that want to, for a specific credential schema, be a issuer, be a verifier, or simply hold a verifiable credential linked to the credential schema.
- validator:
- A role an entity performs by participating in validation processes with applicants in order to register them as issuer, or verifier of a credential schema, or to deliver a verifiable credential to them.
- verifiable public registry:
- a public, normally decentralized, ledger-based network, which provides: trust registry features, that can be used by all its participants: create trust registries, for each trust registry, define its credential schemas, who can issue, verify credential of a specific credential schema,… and a tokenized business model for charging/rewarding participants.
- verifiable service:
- A service, identified by a resolvable DID that can be deployed anywhere by its owner, and that is conforming to this spec and has a resolvable Proof-of-Trust. See VT Spec.
- verifiable user agent:
- A user agent for accessing and using VSs. To be considered a VUA, a user agent must conform and enforce this spec, such as presenting a proof of trust to end user before accepting connecting to VS compliant services, and refuse connecting to not compliant services. See VT Spec.
- Verifiable Trust Specification:
- see VT Spec.
- verifier:
- A role an entity is granted by an ecosystem or a verifier grantor for verifying credentials of a given credential schema.
- verifier grantor:
- A trust registry operator role an entity is granted by an ecosystem for a given credential schema for adding or revoking verifiers.
- verifiable credential:
- A verifiable credential as defined in [VC-DATA-MODEL].
§ Naming Conventions
§ In this spec
- For clarity, Camel Case is used for naming Modules, Entities, Objects, etc.
§ In Implementations
- All APIs MUST return valid JSON.
- All JSON content MUST use Snake Case for object, attribute… names.
- Object attributes and Json Content in general can be returned in any order.
§ Features of a Verifiable Public Registry (VPR)
§ Trust Registry Management
This section is non-normative.
In an VPR, any account can create (and become the controller of) a TrustRegistry
entry that represents a trust registry of an ecosystem. Each TrustRegistry
entry must provide, at a minimum:
- an ecosystem controlled resolvable DID;
- one or more ecosystem governance framework document(s);
- zero or more credential schemas.
The Verifiable Public Registry (VPR) is agnostic to the specific DID methods used. Trust resolution is performed externally, outside the VPR, allowing flexibility and interoperability across ecosystems.
§ Credential Schemas and Permissions
This section is non-normative.
Credential schemas are created and managed by trust registry controller (ecosystems). Each Credential schema includes, at a minimum:
- A JSON Schema that defines the structure of the corresponding verifiable credential
- A PermissionManagementMode for issuance policy, which determines how
ISSUER
permissions are granted. Modes include:OPEN
: Anyone can issue credentials of this schemaECOSYSTEM
:ISSUER
permissions are granted directly by the ecosystem, the trust registry controllerGRANTOR
:ISSUER
permissions are granted by one or several issuer grantor(s) (trust registry operator(s) responsible for selecting issuers for the credential schema of this ecosystem), selected by the ecosystem.
- A PermissionManagementMode for verification policy, which determines how
VERIFIER
permissions are granted. Modes include:OPEN
: Anyone can act as a verifier for this schemaECOSYSTEM
:VERIFIER
permissions are granted directly by the ecosystem, the Trust Registry controllerGRANTOR
:VERIFIER
permissions are granted by one or several verifier grantor(s) (trust registry operator(s) responsible for selecting verifiers for the credential schema of this ecosystem), selected by the ecosystem.
- A Permission tree that defines the roles and relationships involved in managing the schema’s lifecycle. Each created permission in the tree can define business rules, see below Business Models.
Participant roles are defined in the table below:
Participant Role | Description |
---|---|
Ecosystem | Create and control trust registries and credential Schemas. Recognize other participants by granting permission(s) to them. |
Issuer Grantor | Trust Registry operator that grants Issuer permissions to candidate issuers. |
Verifier Grantor | Trust Registry operator that grants Verifier permissions to candidate verifiers. |
Issuer | Can issue credentials of this schema. |
Verifier | Can request presentation of credentials of this schema. |
Holder | Holds a credential. |
Example of a Json Schema credential schema:
{
"$id": "vpr:verana:mainnet/cs/v1/js/VPR_CREDENTIAL_SCHEMA_ID",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "ExampleCredential",
"description": "ExampleCredential using JsonSchema",
"type": "object",
"properties": {
"credentialSubject": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uri"
},
"firstName": {
"type": "string",
"minLength": 0,
"maxLength": 256
},
"lastName": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"expirationDate": {
"type": "string",
"format": "date"
},
"countryOfResidence": {
"type": "string",
"minLength": 2,
"maxLength": 2
}
},
"required": [
"id",
"lastName",
"birthDate",
"expirationDate",
"countryOfResidence"
]
}
}
}
To participate in an ecosystem and assume a role associated with a specific credential schema, an entity must have an account in the VPR and complete a validation process to obtain the required permission.
The validation process involves two parties:
- The applicant — the entity requesting permission for a credential schema within the ecosystem.
- The validator — an entity that already holds permission for the same credential schema and has been delegated authority to validate applicants and issue permissions.
Running a validation process typically involves the payment of trust fees. Trust fee amount to be paid by the applicant is defined in the permission of the validator involved in the validation process:
If an issuer chooses to charge trust fees to a credential holder using the tokenized payment system of the VPR, a validation process must take place and the holder (applicant) MUST have an account to complete the transaction.
Alternatively, the issuer may opt not to use the VPR validation process for holder verification. In such cases, validation occurs outside the VPR, and the issuer is free to use external payment methods (e.g., credit card) to collect fees from the holder candidate.
§ DID Directory Management
This section is non-normative.
The DID directory is a public database of services that can be used by crawlers to index the metadata associated with verifiable services.
Search engines can iterate over the DID directory and index VSs by resolving the service identifier (at the moment a DID, that could be extended in the future), verify if service is a verifiable service, and in such a case extracting their verifiable metadata, such as linked-vp presented credentials.
The DID directory is particularly important for verifiable user agents, such as social browsers, CDN enabled browsers… However, it can also be leveraged by traditional, form-based search engines, which may return simple links for accessing VSs.
Any participant can register a DID in the DID directory by executing a transaction involving network fees and requiring trust deposit.
§ Business models
§ Trust Deposit
This section is non-normative.
In a VPR, each account is associated with a trust deposit.
This trust deposit is automatically funded through transactions involving trust operations, such as:
- Creating trust-related objects int the VPR (e.g., ecosystem trust registries, credential schemas, DIDs in the DID directory)
- Paying trust fees between participants when enforcing ecosystem governance rules for services, credential issuance, or presentation…
The trust deposit is fundamental to the “Proof-of-Trust” (PoT) mechanism of the Verifiable Trust Specification, and it operates as follows:
- The more you use the VPR, the more your trust deposit grows.
- Trust deposits generate yield: block execution fees are distributed not only to network validators, but also to trust deposit holders.
- network-level penalties: If a participant violates the governance framework of the VPR or engages in fraudulent activity, their trust deposit may be partially or fully slashed by the VPR's governance authority.
- ecosystem-level penalties: If a participant operates within an ecosystem (e.g., as a grantor, issuer, verifier, or holder,…) and fails to comply with that ecosystem’s governance framework (EGF), their ecosystem-specific trust deposit can be slashed by the corresponding ecosystem governance authority.
- A slashed deposit must be refilled to continue using the services that triggered the penalty.
- When a participant withdraws from an ecosystem, the associated accumulated trust deposit may be released.
- Released deposits can be reused in other services or withdrawn, however, withdrawals incur penalties, and a portion of the withdrawn amount is burned.
- Holding a large trust deposit does not grant governance rights in the VPR: participants who generate high transaction volume cannot gain control over the governance of the VPR solely through usage or deposit size.
This system ensures that participation in the trust ecosystem is backed by economic accountability, reinforcing the integrity, governability and verifiability of the VPR.
§ Object creation
This section is non-normative.
Creating the following objects requires both a contribution to the trust deposit and the payment of applicable network fees:
- Trust Registries: requires
trust_registry_trust_deposit
trust units, plus associated network fees - Credential Schemas: requires
credential_schema_trust_deposit
trust units, plus associated network fees - DID Directory entries: requires
did_directory_trust_deposit
trust units, plus associated network fees
The following operations only require payment of network fees (no trust deposit is involved):
- Updating the governance framework documents of an ecosystem trust registry
- Removing a DID from the DID Directory
§ Validation process trust fees
This section is non-normative.
We’ve explained in the Credential Schemas and Permissions section above what is a validation process.
The table below summarizes the possible combinations of applicants and validators:
Payee → Payer ↓ | Ecosystem | Issuer Grantor | Verifier Grantor | Issuer | Verifier | Holder |
---|---|---|---|---|---|---|
Issuer Grantor | renewable subscription (1) | |||||
Verifier Grantor | renewable subscription (2) | |||||
Issuer | renewable subscription (3) | renewable subscription (1) | ||||
Verifier | renewable subscription (4) | renewable subscription (2) | ||||
Holder | renewable subscription |
- (1): if issuer mode is set to GRANTOR.
- (2): if verifier mode is set to GRANTOR.
- (3): if issuer mode is set to ECOSYSTEM.
- (4): if verifier mode is set to ECOSYSTEM.
Validation process is started by the applicant.
Example of a candidate issuer (applicant) that would like to be granted an ISSUER permission for a credential schema of an ecosystem, by a validator that has a ISSUER_GRANTOR permission:
The total fees paid by the applicant consists of:
- The validation trust fees defined in the permission of the validator participating in the validation process, plus
- An additional amount equal to the
trust_deposit_rate
of that validation trust fees, which is allocated to the applicant’s trust deposit when the validation process begins. - network fees (not part of the escrowed amount).
Example, using 20% for trust_deposit_rate
:
Upon completion of the validation process, escrowed trust fees are distributed to the validator as follows:
- A portion defined by
trust_deposit_rate
is allocated to the validator’s trust deposit. - The remaining amount is transferred directly to the validator’s wallet.
§ “Pay-Per” trust fees
This section is non-normative.
Pay-per-issuance and pay-per-verification trust fees are defined at the permission level for each role within the ecosystem.
Entities acting as issuers or verifiers for a given credential schema may be required to pay trust fees based on the schema’s configuration and permission tree.
If trust fee payment is required, the entity must execute a transaction in the VPR to pay the appropriate trust fees before issuing or verifying a credential.
Key Points for “Pay-Per” Business Models
-
For a given credential schema, ecosystem and their participants may define pay-per-issuance (or pay-per-verification) trust fees in their respective permissions.
-
In such cases, a participant ISSUER (or VERIFIER) must pay:
- The corresponding issuance (or verification) trust fees for each involved permission;
- An additional amount equal to the
trust_deposit_rate
of the calculated trust fees, allocated to the applicant’s trust deposit; - An amount equal to
wallet_user_agent_reward_rate
of the calculated trust fees, used to reward the Wallet User Agent; - An amount equal to
user_agent_reward_rate
of the calculated trust fees, used to reward the User Agent.
Fee Distribution Model
Trust fees are consistently distributed across participants:
- A portion defined by
trust_deposit_rate
is allocated to the participant’s trust deposit. - The remaining portion is transferred directly to the participant’s wallet.
Wallet User Agents and User Agents that implement the VT spec must verify that the ISSUER or VERIFIER has fulfilled the required trust fee payment.
If not, they must reject the issuance or verification request.
Note: The User Agent and Wallet User Agent may refer to the same implementation.
Distribution example for the issuance by ISSUER #C of a credential, using the permission tree above, 20% for trust_deposit_rate
, 10% for wallet_user_agent_reward_rate
and user_agent_reward_rate
.
Distribution example for the verification by VERIFIER #E of a credential issued by ISSUER #C, using the permission tree above, 20% for trust_deposit_rate
, 10% for wallet_user_agent_reward_rate
and user_agent_reward_rate
.
§ Governance of a VPR
This section is non-normative.
A governance framework must define the governance rules that apply to a VPR.
A designated governance authority is responsible for enforcing these rules and, when necessary, applying financial sanctions to participants who violate the rules.
Ecosystem Governance Frameworks (EGFs) operate independently from the VPR governance framework.
While the VPR governance framework defines the global rules for operating the Verifiable Public Registry (e.g., trust deposits, fee distribution, slashing conditions), each ecosystem must define its own EGF to govern roles, permissions, credential policies, and compliance within its specific domain.
This separation ensures that ecosystems remain autonomous and can tailor governance to their unique needs, without being constrained by the global rules of the VPR.
§ Data model
For simplicity, the data model is presented using an object-relational structure. However, this representation may not be optimal for all implementation scenarios.
Implementors are responsible for adapting the data model to suit their chosen architecture.
For example, a key-value store may be more appropriate for a ledger-based implementation than a relational model.
§ TrustRegistry
TrustRegistry
:
id
(uint64) (mandatory): the id of the trust registry.did
(string) (mandatory): the did of the ecosystem.controller
(account) (mandatory): account that controls this entry.created
(timestamp) (mandatory): timestamp this TrustRegistry has been created.modified
(timestamp) (mandatory): timestamp this TrustRegistry has been modified.archived
(timestamp) (mandatory): timestamp this TrustRegistry has been archived.deposit
(number) (mandatory): trust deposit (indenom
)aka
(string) (optional): optional additional URI of this trust registry.language
(string(2)) (mandatory): primary language alpha-2 code (ISO 3166) of this trust registry.active_version
(int): (mandatory) active governance framework version.
§ GovernanceFrameworkVersion
GovernanceFrameworkVersion
:
id
(uint64) (mandatory): the id of the schema.tr_id
(uint64) (mandatory): the id of the trust registry that controls thisGovernanceFrameworkVersion
entry.created
(timestamp) (mandatory): timestamp this GovernanceFrameworkVersion has been created.version
(int) (mandatory): version of this GF. MUST Starts with 1.
§ GovernanceFrameworkDocument
GovernanceFrameworkDocument
id
(uint64) (mandatory): the id of the schema.gfv_id
(uint64) (mandatory): the id of theGovernanceFrameworkVersion
entry.created
(timestamp) (mandatory): timestamp this GovernanceFrameworkDocument has been created.language
(string(2)) (mandatory): primary language alpha-2 code (ISO 3166) of this trust registry.url
(string) (mandatory): URL where the document is published.digest_sri
(string) (mandatory): digest_sri of the document.
§ CredentialSchema
CredentialSchema
:
General Info:
id
(uint64) (mandatory): the id of the schema.tr_id
(uint64) (mandatory): the id of the trust registry that controls thisCredentialSchema
entry.created
(timestamp) (mandatory): timestamp this CredentialSchema has been created.modified
(timestamp) (mandatory): timestamp this CredentialSchema has been modified.archived
(timestamp) (mandatory): timestamp this CredentialSchema has been archived.deposit
(number) (mandatory): trust deposit (indenom
)json_schema
(string) (mandatory): Json Schema used for issuing credentials based on this schema.issuer_grantor_validation_validity_period
(number) (mandatory): number of days after which an issuer grantor validation process expires and must be renewed.verifier_grantor_validation_validity_period
(number) (mandatory): number of days after which a verifier grantor validation process expires and must be renewed.issuer_validation_validity_period
(number) (mandatory): number of days after which an issuer validation process expires and must be renewed.verifier_validation_validity_period
(number) (mandatory): number of days after which a verifier validation process expires and must be renewed.holder_validation_validity_period
(number) (mandatory): number of days after which an holder validation process expires and must be renewed.issuer_perm_management_mode
(PermissionManagementMode) (mandatory): defines how permissions are managed for issuers of thisCredentialSchema
. OPEN means anyone can issue credential of this schema; GRANTOR means a validation process MUST be run between a candidate ISSUER and an ISSUER_GRANTOR in order to create an ISSUER permission; ECOSYSTEM means a validation process MUST be run between a candidate ISSUER and the trust registry owner (ecosystem) of theCredentialSchema
entry in order to create an ISSUER permission;verifier_perm_management_mode
(PermissionManagementMode) (mandatory): defines how permissions are managed for verifiers of thisCredentialSchema
. OPEN means anyone can verify credentials of this schema (does not implies that a payment is not necessary); GRANTOR means a validation process MUST be run between a candidate VERIFIER and a VERIFIER_GRANTOR in order to create a VERIFIER permission; ECOSYSTEM means a validation process MUST be run between a candidate VERIFIER and the trust registry owner (ecosystem) of theCredentialSchema
entry in order to create a VERIFIER permission;
§ Permission
Permission
:
id
(uint64) (mandatory): the id of the perm.schema_id
(uint64) (mandatory): the id of the relatedCredentialSchema
entry.type
(PermissionType): ISSUER, VERIFIER, ISSUER_GRANTOR, VERIFIER_GRANTOR, ECOSYSTEM, HOLDERdid
(string) (optional): DID this permission refers to. MUST conform to [RFC3986].grantee
(account) (mandatory): account this permission refers to (account granted to act astype
for schemaschema_id
).created
(timestamp) (mandatory): timestamp thisPermission
has been created.created_by
(account) (mandatory): account that created this permission.extended
(timestamp) (mandatory): timestamp thisPermission
has been extended.extended_by
(account) (mandatory): account that extended this permission.slashed
(timestamp) (mandatory): timestamp thisPermission
has been slashed.slashed_by
(account) (mandatory): account that slashed this permission.repaid
(timestamp) (mandatory): timestamp thisPermission
has been repaid.repaid_by
(account) (mandatory): account that repaid this permission.effective_from
(timestamp) (optional): timestamp from which (inclusive) thisPermission
is effective.effective_until
(timestamp) (optional): timestamp until when (exclusive) thisPermission
is effective, null if no time limit has been set for this permission.modified
(timestamp) (mandatory): timestamp this Permission has been modified.validation_fees
(number) (mandatory): price to pay by an applicant to a validator (grantee of this perm) for running a validation process for a given validation period, in trust unit. Default to 0.issuance_fees
(number) (mandatory): fees requested by grantee of this perm when a credential is issued, in trust unit. Default to 0.verification_fees
(number) (mandatory): fees requested by grantee of this perm when a credential is verified, in trust unit. Default to 0.deposit
(number) (mandatory): accumulated grantee deposit in the context of the use of this permission (including the validation process), indenom
. Usually, it is incremented when for example, for a ISSUER typePermission
perm
, issuer issues credentials that require paying issuance fees: an additional % of the fees is charged to issuer and sent to its deposit, corresponding deposit amount increases thisperm.deposit
value as well. Ifperm
is, let’s say revoked, then correspondingperm.deposit
value is freed fromperm.grantee
Trust Deposit.slashed_deposit
(number) (mandatory): part of the deposit that has been slashed.repaid_deposit
(number) (mandatory): part of the slashed deposit that has been repaid.revoked
(timestamp) (optional): manual revocation timestamp of this Perm.revoked_by
(account) (mandatory): account that revoked this permission.terminated
(timestamp) (optional): manual termination (by grantee) timestamp of this Perm.terminated_by
(account) (mandatory): account that terminated this permission.country
(string) (optional): country, as an alpha-2 code (ISO 3166), this permission refers to. If null, it means permission is not linked to a specific country.validator_perm_id
(uint64) (optional): permission of the validator assigned to the validation process of this permission, ie parent node in thePermission
tree.vp_state
(enum) (mandatory): one of PENDING, VALIDATED, TERMINATED, TERMINATION_REQUESTED.vp_exp
(timestamp) (optional): validation expiration timestamp. This expiration timestamp is for the validation process itself, not for the issued credential orPermission
expiration timestamp.vp_last_state_change
(timestamp) (mandatory)vp_validator_deposit
: number (optional): accumulated validator trust deposit, in denom.vp_current_fees
(number) (mandatory): current action escrowed fees that will be paid to validator upon validation process completion, in denom.vp_current_deposit
(number) (mandatory): current action trust deposit, in denom.vp_summary_digest_sri
(digest_sri) (optional): an optional digest_sri, set by validator, of a summary of the information, proofs… provided by the applicant.vp_term_requested
(timestamp) (optional): set when controller requests the termination of this entry.
§ PermissionSession
PermissionSession
:
id
(uuid) (mandatory): session uuid.controller
(account) (mandatory): account that controls the entry.agent_perm_id
(uint64) (mandatory): permission id of the agent.modified
(timestamp) (mandatory): timestamp this PermissionSession has been modified.created
(timestamp) (mandatory): timestamp this PermissionSession has been created.authz
(uint64 (Permission id), uint64 (Permission id), uint64 (Permission id))[] (mandatory): permission(s) linked to this session (issuer, verifier, wallet_agent).
§ DIDDirectory
DidDirectory
:
did
(string) (mandatory) (key): the DID. MUST conform to [RFC3986].controller
(account) (mandatory): account that created the DID.created
(timestamp) (mandatory): timestamp this DID has been added.modified
(timestamp) (mandatory): timestamp this DID has been modified.exp
(timestamp) (mandatory): expiration timestamp.deposit
(number) (mandatory): effective trust deposit for this DID (indenom
)
§ TrustDeposit
TrustDeposit
:
share
(number) (mandatory): share of the module total deposit.account
(account) (mandatory) (key): the accountamount
(number) (mandatory): amount of deposit indenom
.claimable
(number) (mandatory): amount of claimable deposit indenom
.slashed_deposit
(number) (optional): amount of slashed deposit indenom
.repaid_deposit
(number) (optional): amount of slashed deposit indenom
.last_slashed
(timestamp) (optional): last time this trust deposit has been slashed.last_repaid
(timestamp) (optional): last time this trust deposit has been slashed.slash_count
(number) (optional): number of times this account has been slashed.last_repaid_by
(account) (optional): account that repaid the last slash.
§ GlobalVariables
GlobalVariables
:
Trust Unit:
trust_unit_price
(number) (mandatory): trust unit price, in denom.
Credential Schema:
credential_schema_trust_deposit
(number) (mandatory): default trust deposit value for creating a credential schema, in trust units.credential_schema_schema_max_size
(number) (mandatory): maximum size of theschema
string attribute for aCredentialSchema
.credential_schema_issuer_grantor_validation_validity_period_max_days
(number) (mandatory): maximum number of days an issuer grantor validation can be valid for.credential_schema_verifier_grantor_validation_validity_period_max_days
(number) (mandatory): maximum number of days an verifier grantor validation can be valid for.credential_schema_issuer_validation_validity_period_max_days
(number) (mandatory): maximum number of days an issuer validation can be valid for.credential_schema_verifier_validation_validity_period_max_days
(number) (mandatory): maximum number of days an verifier validation can be valid for.credential_schema_holder_validation_validity_period_max_days
(number) (mandatory): maximum number of days an holder validation can be valid for.
Validation:
validation_term_requested_timeout_days
(number) (mandatory): after this number of days, validation applicant can confirm termination of a validation if validator didn’t do it.
Trust Registry:
trust_registry_trust_deposit
(number) (mandatory): default trust deposit value for creating a trust registry, in trust units.
DID Directory:
did_directory_trust_deposit
(number) (mandatory): default trust deposit value, in trust units.did_directory_grace_period_days
(number) (mandatory): default grace period, in days.
Trust Deposit:
trust_deposit_reclaim_burn_rate
(number) (mandatory): percentage of burnt deposit when an account execute a reclaim of capital amount.trust_deposit_share_value
(number) (mandatory): Value of one share of trust deposit, indenom
. Default an initial value: 1. Increase over time, when yield is produced.trust_deposit_rate
(number) (mandatory): Rate used for dynamically calculating trust deposits from trust fees. Default value: 20% (0.20)wallet_user_agent_reward_rate
(number) (mandatory): Rate used for dynamically calculating wallet user agent rewards from trust fees. Default value: 20% (0.20)user_agent_reward_rate
(number) (mandatory): Rate used for dynamically calculating user agent rewards from trust fees. Default value: 20% (0.20)
§ Module Requirements
All VPR modules MUST, at least, provide:
- A keeper(s), used to access the module’s store(s) and update the state.
- A Msg service, used to process messages when they are routed to the module by BaseApp and trigger state-transitions.
- A query service, used to process user queries.
- Interfaces, for end users to query the subset of the state defined by the module and create messages of the custom types defined in the module.
Note about Query REST API:
- all query methods MUST return valid JSON.
- objects MUST be nested when needed, such as when returning a trust registry.
- JSON formatting MUST obey to data model regarding attribute names. A method that returns a
TrustRegistry
entry MUST return an entry called “trust_registry”. A method that returns a list of Trust Registries MUST return an entry called “trustRegistries” that contain a list ofTrustRegistry
entries.
Examples:
Get a TrustRegistry
"trust_registry": {
{
"active_version": 0,
"aka": "string",
"controller": "string",
"created": "2025-01-14T19:40:37.967Z",
"deposit": "string",
"did": "string",
"id": "string",
"language": "string",
"modified": "2025-01-14T19:40:37.967Z",
"versions": [
{
"active_since": "2025-01-14T19:40:37.967Z",
"created": "2025-01-14T19:40:37.967Z",
"id": "string",
"tr_id": "string",
"version": 0,
"documents": [
{
"created": "2025-01-14T19:40:37.967Z",
"gfv_id": "string",
"digest_sri": "string",
"id": "string",
"language": "string",
"url": "string"
}
]
}
]
}
"trustRegistries": [ {
{
"active_version": 0,
"aka": "string",
"controller": "string",
"created": "2025-01-14T19:40:37.967Z",
"deposit": "string",
"did": "string",
"id": "string",
"language": "string",
"modified": "2025-01-14T19:40:37.967Z",
"versions": [
{
"active_since": "2025-01-14T19:40:37.967Z",
"created": "2025-01-14T19:40:37.967Z",
"id": "string",
"tr_id": "string",
"version": 0,
"documents": [
{
"created": "2025-01-14T19:40:37.967Z",
"gfv_id": "string",
"digest_sri": "string",
"id": "string",
"language": "string",
"url": "string"
}
]
}
]
}, {
"active_version": 0,
"aka": "string",
"controller": "string",
"created": "2025-01-14T19:40:37.967Z",
"deposit": "string",
"did": "string",
"id": "string",
"language": "string",
"modified": "2025-01-14T19:40:37.967Z",
"versions": [
{
"active_since": "2025-01-14T19:40:37.967Z",
"created": "2025-01-14T19:40:37.967Z",
"id": "string",
"tr_id": "string",
"version": 0,
"documents": [
{
"created": "2025-01-14T19:40:37.967Z",
"gfv_id": "string",
"digest_sri": "string",
"id": "string",
"language": "string",
"url": "string"
}
],
}
]
}
]
For Msg methods, all precondition checks MUST be verified first for accepting the Msg, and MUST be verified again upon method execution
A VPR implementation MUST implement all the following requirements.
The relative REST path is the path suffix. Implementer can set any prefix, like https://example/verana/tr/v1/get.
Module | Method Name | Relative REST API path | Type | Requirements |
---|---|---|---|---|
Trust Registry | Create a Trust Registry | Msg | [MOD-TR-MSG-1] | |
Add Governance Framework Document | Msg | [MOD-TR-MSG-2] | ||
Increase Active Version | Msg | [MOD-TR-MSG-3] | ||
Update Trust Registry | Msg | [MOD-TR-MSG-4] | ||
Archive Trust Registry | Msg | [MOD-TR-MSG-5] | ||
Update TR Module Parameters | Msg | [MOD-TR-MSG-6] | ||
Get Trust Registry | /tr/v1/get | Query | [MOD-TR-QRY-1] | |
List Trust Registries | /tr/v1/list | Query | [MOD-TR-QRY-2] | |
List TR Module Parameters | /tr/v1/params | Query | [MOD-TR-QRY-3] | |
Credential Schema | Create a Credential Schema | Msg | [MOD-CS-MSG-1] | |
Update a Credential Schema | Msg | [MOD-CS-MSG-2] | ||
Archive Credential Schema | Msg | [MOD-CS-MSG-3] | ||
Update CS Module Parameters | Msg | [MOD-CS-MSG-4] | ||
List Credential Schemas | /cs/v1/list | Query | [MOD-CS-QRY-1] | |
Get a Credential Schema | /cs/v1/get | Query | [MOD-CS-QRY-2] | |
Render Json Schema | /cs/v1/js | Query | [MOD-CS-QRY-3] | |
List CS Module Parameters | /cs/v1/params | Query | [MOD-TR-QRY-3] | |
Permission | Start Permission VP | Msg | [MOD-PERM-MSG-1] | |
Renew a Permission VP | Msg | [MOD-PERM-MSG-2] | ||
Set Permission VP to Validated | Msg | [MOD-PERM-MSG-3] | ||
Request Permission VP Termination | Msg | [MOD-PERM-MSG-4] | ||
Confirm Permission VP Termination | Msg | [MOD-PERM-MSG-5] | ||
Cancel Permission VP Last Request | Msg | [MOD-PERM-MSG-6] | ||
Create Root Permission | Msg | [MOD-PERM-MSG-7] | ||
Extend Permission | Msg | [MOD-PERM-MSG-8] | ||
Revoke Permission | Msg | [MOD-PERM-MSG-9] | ||
Create or update Permission Session | Msg | [MOD-PERM-MSG-10] | ||
Update Permission Module Parameters | Msg | [MOD-PERM-MSG-11] | ||
Slash Permission Trust Deposit | Msg | [MOD-PERM-MSG-12] | ||
Repay Permission Slashed Trust Deposit | Msg | [MOD-PERM-MSG-13] | ||
Create Permission | Msg | [MOD-PERM-MSG-14] | ||
List Permissions | /perm/v1/list | Query | [MOD-PERM-QRY-1] | |
Get a Permission | /prem/v1/get | Query | [MOD-PERM-QRY-2] | |
Find Permissions With DID | /perm/v1/find_with_did | Query | [MOD-PERM-QRY-3] | |
Find Beneficiaries | /perm/v1/beneficiaries | Query | [MOD-PERM-QRY-4] | |
Get Permission Session | /perm/v1/get_session | Query | [MOD-PERM-QRY-5] | |
List Permission Module Parameters | Query | [MOD-PERM-QRY-6] | ||
List Permission Sessions | Query | [MOD-PERM-QRY-7] | ||
DID Directory | Add a DID | Msg | [MOD-DD-MSG-1] | |
Renew a DID | Msg | [MOD-DD-MSG-2] | ||
Remove a DID | Msg | [MOD-DD-MSG-3] | ||
Touch a DID | Msg | [MOD-DD-MSG-4] | ||
Update TD Module Parameters | Msg | [MOD-DD-MSG-5] | ||
List DIDs | /dd/v1/list | Query | [MOD-DD-QRY-1] | |
Get a DID | /dd/v1/get | Query | [MOD-DD-QRY-2] | |
List DD Module Parameters | /dd/v1/params | Query | [MOD-DD-QRY-3] | |
Trust Deposit | Adjust Trust Deposit | Msg | [MOD-TD-MSG-1] | |
Reclaim Trust Deposit Yield | Msg | [MOD-TD-MSG-2] | ||
Reclaim Trust Deposit | Msg | [MOD-TD-MSG-3] | ||
Update TD Module Parameters | Msg | [MOD-TD-MSG-4] | ||
Slash Trust Deposit | Msg | [MOD-TD-MSG-5] | ||
Repay Slashed Trust Deposit | Msg | [MOD-TD-MSG-6] | ||
Burn Ecosystem Slashed Trust Deposit | Msg | [MOD-TD-MSG-7] | ||
Get Trust Deposit | /td/v1/get | Query | [MOD-TD-QRY-1] | |
List TD Module Parameters | /td/v1/params | Query | [MOD-TD-QRY-2] |
Any method failure in the precondition/basic checks SHOULD lead to a CLI ERROR / HTTP BAD REQUEST error with a human readable message giving a clue of the reason why method failed.
§ Trust Registry Module
§ [MOD-TR-MSG-1] Create New Trust Registry
Any account CAN execute this method.
§ [MOD-TR-MSG-1-1] Create New Trust Registry parameters
An account that would like to create a trust registry MUST call this method by specifying:
did
(string) (mandatory): the did of the trust registry.aka
(string) (optional): optional additional URI of this trust registry.language
(string(17)) (mandatory): primary language tag (rfc1766) of this trust registry.doc_url
(string) (mandatory): URL where the document is published.doc_digest_sri
(string) (mandatory): digest_sri of the document.
Provided document must be of the same language that the primary language of the trust registry.
§ [MOD-TR-MSG-1-2] Create New Trust Registry precondition checks
If any of these precondition checks fail, method MUST abort.
§ [MOD-TR-MSG-1-2-1] Create New Trust Registry basic checks
-
if a mandatory parameter is not present, method MUST abort.
-
did
(string) (mandatory): MUST conform to the DID Syntax, as specified [DID-CORE]. -
aka
(string) (optional): optional additional URI of this trust registry. MUST be an URI. -
language
(string(17)) (mandatory): MUST be a language tag (rfc1766). -
doc_url
(string) (mandatory): MUST be a valid URL . -
doc_digest_sri
(string) (mandatory): MUST be a valid digest_sri as specified in integrity of related resources spec. Example:sha384-MzNNbQTWCSUSi0bbz7dbua+RcENv7C6FvlmYJ1Y+I727HsPOHdzwELMYO9Mz68M26
.
It is not a problem if several trust registries are created with the same ecosystem DID. Identifier of a TrustRegistry
is its id, and the Verifiable Trust Spec includes the id of the TrustRegistry
in the DID Document. DID unique constraint is then not needed.
§ [MOD-TR-MSG-1-2-2] Create New Trust Registry fee checks
Applicant MUST have an available balance in its account, to cover the following:
- the required estimated transaction fees in its account.
- the required
trust_deposit_in_denom
:GlobalVariables.trust_registry_trust_deposit
*GlobalVariables.trust_unit_price
.
TrustRegistry
trust deposit is not reclaimable.
§ [MOD-TR-MSG-1-3] Create New Trust Registry execution
If all precondition checks passed, method is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
use [MOD-TD-MSG-1] to increase by
trust_deposit_in_denom
:GlobalVariables.trust_registry_trust_deposit
*GlobalVariables.trust_unit_price
the trust deposit of account running the method and transfer the corresponding amount toTrustDeposit
module. -
create and persist a new
TrustRegistry
entrytr
: -
tr.id
: auto-incremented uint64 -
tr.did
:did
-
tr.controller
: account running the method -
tr.created
: current timestamp -
tr.modified
:tr.created
-
tr.aka
:aka
-
tr.language
:language
-
tr.active_version
: 1 -
tr.deposit
:trust_deposit_in_denom
-
create and persist a new
GovernanceFrameworkVersion
entrygfv
: -
gfv.id
: auto-incremented uint64 -
gfv.tr_id
:tr.id
-
gfv.created
: current timestamp -
gfv.version
: 1 -
gfv.active_since
: current timestamp -
create and persist a new
GovernanceFrameworkDocument
entrygfd
: -
gfd.id
: auto-incremented uint64 -
gfd.gfv_id
:gfv.id
-
gfd.created
: current timestamp -
gfd.language
:language
-
gfd.url
:doc_url
-
gfd.digest_sri
:doc_digest_sri
§ [MOD-TR-MSG-2] Add Governance Framework Document
Any account CAN execute this method.
§ [MOD-TR-MSG-2-1] Add Governance Framework Document parameters
An account that would like to add a governance framework document MUST call this method by specifying:
tr_id
(uint64) (mandatory): the id of the trust registry.doc_language
(string(2)) (mandatory): language tag (rfc1766) of the EGF document, provided by the EGA.doc_url
(string) (mandatory): URL where the document is published.doc_digest_sri
(string) (mandatory): digest_sri of the document.version
(int) (mandatory): targeted version.
If for a given language, a document already exists, the execution of this transaction would replace the corresponding entry. Else, a new entry is created.
§ [MOD-TR-MSG-2-2] Add Governance Framework Document precondition checks
If any of these precondition checks fail, method MUST abort.
§ [MOD-TR-MSG-2-2-1] Add Governance Framework Document basic checks
-
if a mandatory parameter is not present, method MUST abort.
-
id
(uint64) (mandatory): aTrustRegistry
entry with this id MUST exist and account executing the method MUST be the controller of theTrustRegistry
entry. -
version
: there MUST exist aGovernanceFrameworkVersion
entrygfv
wheregfv.tr_id
is equal toid
andgfv.version
=version
, orversion
MUST be exactly equal to the biggest foundgfv.version
+ 1 of allGovernanceFrameworkVersion
entries found for thisgfv.tr_id
equal toid
.version
MUST be greater than thetr.active_version
. -
doc_language
(string(2)) (mandatory): MUST be a language tag (rfc1766). -
doc_url
(string) (mandatory): MUST be a valid URL. -
doc_digest_sri
(string) (mandatory): MUST be a valid digest_sri as specified in integrity of related resources spec. Example:sha384-MzNNbQTWCSUSi0bbz7dbua+RcENv7C6FvlmYJ1Y+I727HsPOHdzwELMYO9Mz68M26
.
§ [MOD-TR-MSG-2-2-2] Add Governance Framework Document fee checks
Account MUST have the required estimated transaction fees in its account.
§ [MOD-TR-MSG-2-3] Add Governance Framework Document execution
If all precondition checks passed, method is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
load GovernanceFrameworkVersion
entry gfv
for the requested version, or create a new GovernanceFrameworkVersion
gfv
if required:
-
gfv.id
: auto-incremented uint64 -
gfv.tr_id
:id
-
gfv.created
: current timestamp -
gfv.version
: 1 -
gfv.active_since
: null -
create and persist or (replace if already exist) a
GovernanceFrameworkDocument
entrygfd
: -
gfd.id
: auto-incremented uint64 -
gfd.gfv_id
:gfv.id
-
gfd.created
: current timestamp -
gfd.language
:doc_language
-
gfd.url
:doc_url
-
gfd.digest_sri
:doc_digest_sri
§ [MOD-TR-MSG-3] Increase Active Governance Framework Version
Any account CAN execute this method.
§ [MOD-TR-MSG-3-1] Increase Active Governance Framework Version parameters
An account that would like to add a governance framework document MUST call this method by specifying:
id
(uint64) (mandatory): the id of the trust registry.
§ [MOD-TR-MSG-3-2] Increase Active Governance Framework Version precondition checks
If any of these precondition checks fail, method MUST abort.
§ [MOD-TR-MSG-3-2-1] Increase Active Governance Framework Version basic checks
-
if a mandatory parameter is not present, method MUST abort.
-
id
(uint64) (mandatory): aTrustRegistry
entry with this id MUST exist and account executing the method MUST be the controller of theTrustRegistry
entry. -
load
TrustRegistry
entrytr
from itsid
. Find aGovernanceFrameworkVersion
entrygfv
where version is equal totr.active_version
+ 1. If none is found, transaction MUST abort. -
find
GovernanceFrameworkDocument
gfd
forgfd.gfv_id
=gfv.id
andgfd.language
=tr.language
. If no document is found (and thus no document exist for the default language of this version for this trust registry), transaction MUST abort.
§ [MOD-TR-MSG-3-2-2] Increase Active Governance Framework Version fee checks
Account MUST have the required estimated transaction fees in its account.
§ [MOD-TR-MSG-3-3] Increase Active Governance Framework Version execution
If all precondition checks passed, method is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
- load
TrustRegistry
entrytr
from itsid
. Find aGovernanceFrameworkVersion
entrygfv
where version is equal totr.active_version
+ 1. If none is found, transaction MUST abort. Else, updatetr.active_version
totr.active_version
+ 1. Settr.modified
to current timestamp, and setgfv.active_since
to current timestamp and persist changes.
§ [MOD-TR-MSG-4] Update Trust Registry
Any account CAN execute this method.
§ [MOD-TR-MSG-4-1] Update Trust Registry parameters
An account that would like to update a trust registry MUST call this method by specifying:
id
(uint64) (mandatory): the id of the trust registry.did
(string) (mandatory): the did of the trust registry.aka
(string) (optional): optional additional URI of this trust registry. If null, it means replace existing value with null.
§ [MOD-TR-MSG-4-2] Update Trust Registry precondition checks
If any of these precondition checks fail, method MUST abort.
§ [MOD-TR-MSG-4-2-1] Update Trust Registry basic checks
-
if a mandatory parameter is not present, method MUST abort.
-
id
(uint64) (mandatory): aTrustRegistry
entrytr
with idid
MUST exist and account executing the method MUST be the controller of theTrustRegistry
entrytr
. -
did
(string) (mandatory): MUST conform to the DID Syntax, as specified [DID-CORE]. -
aka
(string) (optional): optional additional URI of this trust registry. MUST be an URI or null.
§ [MOD-TR-MSG-4-2-2] Update Trust Registry fee checks
Applicant MUST have an available balance in its account, to cover the required transaction fees.
§ [MOD-TR-MSG-4-3] Update Trust Registry execution
If all precondition checks passed, method is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
load
TrustRegistry
entrytr
fromid
and set: -
tr.did
:did
-
tr.aka
:aka
-
tr.modified
: current timestamp
§ [MOD-TR-MSG-5] Archive Trust Registry
Any account CAN execute this method.
§ [MOD-TR-MSG-5-1] Archive Trust Registry parameters
An account that would like to archive or unarchive a trust registry MUST call this method by specifying:
id
(uint64) (mandatory) id of the trust registry (mandatory);archive
(boolean) (mandatory), true means archive, false means unarchive.
§ [MOD-TR-MSG-5-2] Archive Trust Registry precondition checks
If any of these precondition checks fail, method MUST abort.
§ [MOD-TR-MSG-5-2-1] Archive Trust Registry basic checks
-
if a mandatory parameter is not present, method MUST abort.
-
load
TrustRegistry
tr
fromid
.tr.controller
MUST be the account executing the method, else MUST abort. -
archive
(boolean) (mandatory) MUST be a boolean.- If
archive
is true andtr.archived
is not null, MUST abort asTrustRegistry
is already archived. - If
archive
is false andtr.archived
is null, MUST abort asTrustRegistry
is already not archived.
- If
§ [MOD-TR-MSG-5-2-2] Archive Trust Registry fee checks
Account MUST have an available balance in its account to cover the required transaction fees.
§ [MOD-TR-MSG-5-3] Archive Trust Registry execution
If all precondition checks passed, method is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
- update
TrustRegistry
entrytr
withtr.id
equal toid
: - if
archived
is true: setcs.archived
to current timestamp. - if
archived
is false: setcs.archived
to null. tr.modified
: current timestamp
§ [MOD-TR-MSG-6] Update Module Parameters
Update Module Parameters.
Can only be executed through a governance proposal.
§ [MOD-TR-MSG-6-1] Update Module Parameters parameters
params
(KeySet<String, String>): the parameters to update and their values.
§ [MOD-TR-MSG-6-2] Update Module Parameters precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-TR-MSG-6-2-1] Update Module Parameters basic checks
params
: size ofparams
MUST be greater than 0. For eachparam
<key
,value
>key
MUST exist, else abort.
§ [MOD-TR-MSG-6-2-2] Update Module Parameters fee checks
provided transaction fees MUST be sufficient for execution
§ [MOD-TR-MSG-6-3] Update Module Parameters execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
for each parameter param
<key
, value
> in parameters
:
- update parameter set value =
value
where key =key
.
§ [MOD-TR-QRY-1] Get Trust Registry
Anyone CAN execute this method.
§ [MOD-TR-QRY-1-1] Get Trust Registry parameters
id
(uint64) (mandatory): id of the trust registry.active_gf_only
(boolean) (optional): if true, include only current governance framework data. If false or null, returns everything.preferred_language
(string) (optional): if set, return only one document per version, with language=preferred_language
when possible, else if no document exist with this language, return language. If not set, return all documents of all languages.
§ [MOD-TR-QRY-1-2] Get Trust Registry checks
§ [MOD-TR-QRY-1-3] Get Trust Registry execution
return found TrustRegistry
entry (if any), as well as all its nested GovernanceFrameworkVersion
and GovernanceFrameworkDocument
entries. If latest_gf_only
is true, return only nested GovernanceFrameworkVersion
and GovernanceFrameworkDocument
entries for the active version.
§ [MOD-TR-QRY-2] List Trust Registries
This method is used to query the DID Directory keeper. Returned result MUST be ordered by TrustRegistry.modified
asc.
§ [MOD-TR-QRY-2-1] List Trust Registries query parameters
The following parameters are optional:
controller
(account) (optional): if specified, filter by controller.modified_after
(timestamp) (optional): if specified, returns onlyTrustRegistry
entries withTrustRegistry.modified
greater thanmodified
.active_gf_only
(boolean) (optional): if true, include only current governance framework data. If false or null, returns everything.preferred_language
(string) (optional): if set, return only one document per version, with language=preferred_language
when possible, else if no document exist with this language, return language. If not set, return all documents of all languages.response_max_size
(small number) (optional): default to 64. Max 1,024.
§ [MOD-TR-QRY-2-2] List Trust Registries query checks
If any of these checks fail, query MUST fail.
response_max_size
must be between 1 and 1,024. Default to 64 if unspecified.
§ [MOD-TR-QRY-2-3] List Trust Registries execution of the query
If all precondition checks passed, query is executed and result (may be empty) returned. If modified_after
is specified, order by modified_after
desc.
§ [MOD-TR-QRY-3] List Module Parameters
Anyone CAN run this query.
§ [MOD-TR-QRY-3-2] List Module Parameters parameters
§ [MOD-TR-QRY-3-2] List Module Parameters query checks
§ [MOD-TR-QRY-3-3] List Module Parameters execution of the query
Return the list of the existing parameters and their values.
§ [MOD-TR-QRY-3-4] List Module Parameters API result example
{
"params": {
"key1": "value1",
"key2": "value2",
...
...
}
}
§ Credential Schema Module
§ [MOD-CS-MSG-1] Create New Credential Schema
Any account CAN execute this method.
§ [MOD-CS-MSG-1-1] Create New Credential Schema parameters
An account that would like to create a credential schema MUST call this method by specifying:
tr_id
id of the trust registry (mandatory);json_schema
the Json Schema of the credential (mandatory).issuer_grantor_validation_validity_period
(mandatory), default to 0 (days).verifier_grantor_validation_validity_period
(mandatory), default to 0 (days).issuer_validation_validity_period
(mandatory), default to 0 (days).verifier_validation_validity_period
(mandatory), default to 0 (days).holder_validation_validity_period
(mandatory), default to 0 (days).issuer_perm_management_mode
(PermissionManagementMode) (mandatory).verifier_perm_management_mode
(PermissionManagementMode) (mandatory).
§ [MOD-CS-MSG-1-2] Create New Credential Schema precondition checks
If any of these precondition checks fail, method MUST abort.
§ [MOD-CS-MSG-1-2-1] Create New Credential Schema basic checks
- if a mandatory parameter is not present, method MUST abort.
tr_id
MUST represent an existingTrustRegistry
entrytr
andtr.controller
MUST be the account executing the method.json_schema
MUST be a valid Json Schema, and size must not be greater thanGlobalVariables.credential_schema_schema_max_size
.$id
of the Json Schema must be a valid https URL that terminates with string/vpr/v1/cs/js/VPR_CREDENTIAL_SCHEMA_ID
as specified in [MOD-CS-QRY-3]. VPR_CREDENTIAL_SCHEMA_ID will be replaced during execution by the auto-generated id of thisCredentialSchema
.issuer_grantor_validation_validity_period
must be between 0 (never expire) andGlobalVariables.credential_schema_issuer_grantor_validation_validity_period_max_days
days.verifier_grantor_validation_validity_period
must be between 0 (never expire) andGlobalVariables.credential_schema_verifier_grantor_validation_validity_period_max_days
days.issuer_validation_validity_period
must be between 0 (never expire) andGlobalVariables.credential_schema_issuer_validation_validity_period_max_days
days.verifier_validation_validity_period
must be between 0 (never expire) andGlobalVariables.credential_schema_verifier_validation_validity_period_max_days
days.holder_validation_validity_period
must be between 0 (never expire) andGlobalVariables.credential_schema_holder_validation_validity_period_max_days
days.issuer_perm_management_mode
(PermissionManagementMode) (mandatory) MUST be a valid PermissionManagementMode.verifier_perm_management_mode
(PermissionManagementMode) (mandatory) MUST be a valid PermissionManagementMode.
§ [MOD-CS-MSG-1-2-2] Create New Credential Schema fee checks
Applicant MUST have an available balance in its account, to cover the following fees:
- the required estimated transaction fees in its account.
- the required
trust_deposit_in_denom
:GlobalVariables.credential_schema_trust_deposit
*GlobalVariables.trust_unit_price
.
Credential Schema trust deposit is not reclaimable.
§ [MOD-CS-MSG-1-3] Create New Credential Schema execution
If all precondition checks passed, method is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
use [MOD-TD-MSG-1] to increase by
trust_deposit_in_denom
:GlobalVariables.trust_registry_trust_deposit
*GlobalVariables.trust_unit_price
the trust deposit of account running the method and transfer the corresponding amount toTrustDeposit
module. -
create and persist a new
CredentialSchema
entrycs
:cs.id
: auto-incremented uint64.cs.tr_id
: id of theTrustRegistry
entry that will be the owner ofcs
.cs.json_schema
:json_schema
, with VPR_CREDENTIAL_SCHEMA_ID string replaced by generatedcs.id
.cs.issuer_grantor_validation_validity_period
:issuer_grantor_validation_validity_period
cs.verifier_grantor_validation_validity_period
:verifier_grantor_validation_validity_period
cs.issuer_validation_validity_period
:issuer_validation_validity_period
cs.verifier_validation_validity_period
:verifier_validation_validity_period
cs.holder_validation_validity_period
:holder_validation_validity_period
cs.issuer_perm_management_mode
:issuer_perm_management_mode
cs.verifier_perm_management_mode
:verifier_perm_management_mode
cs.created
: current timestampcs.modified
:cs.created
.
If needed, depending on configuration mode, Trust Registry controller MAY need to create a ECOSYSTEM Permission
so that validation processes can be run.
§ [MOD-CS-MSG-2] Update Credential Schema
Any account CAN execute this method.
§ [MOD-CS-MSG-2-1] Update Credential Schema parameters
An account that would like to update a credential schema MUST call this method by specifying:
id
id of the credential schema (mandatory);issuer_grantor_validation_validity_period
(mandatory), default to 0 (days).verifier_grantor_validation_validity_period
(mandatory), default to 0 (days).issuer_validation_validity_period
(mandatory), default to 0 (days).verifier_validation_validity_period
(mandatory), default to 0 (days).holder_validation_validity_period
(mandatory), default to 0 (days).
other attributes are immutables and cannot be updated.
§ [MOD-CS-MSG-2-2] Update Credential Schema precondition checks
If any of these precondition checks fail, method MUST abort.
§ [MOD-CS-MSG-2-2-1] Update Credential Schema basic checks
-
if a mandatory parameter is not present, method MUST abort.
-
id
MUST represent an existingCredentialSchema
entrycs
. -
load
TrustRegistry
tr
fromcs.tr_id
.tr.controller
MUST be the account executing the method, else MUST abort. -
issuer_grantor_validation_validity_period
MUST be between 0 (never expire) andGlobalVariables.credential_schema_issuer_grantor_validation_validity_period_max_days
days. -
verifier_grantor_validation_validity_period
MUST be between 0 (never expire) andGlobalVariables.credential_schema_verifier_grantor_validation_validity_period_max_days
days. -
issuer_validation_validity_period
MUST be between 0 (never expire) andGlobalVariables.credential_schema_issuer_validation_validity_period_max_days
days. -
verifier_validation_validity_period
MUST be between 0 (never expire) andGlobalVariables.credential_schema_verifier_validation_validity_period_max_days
days. -
holder_validation_validity_period
MUST be between 0 (never expire) andGlobalVariables.credential_schema_holder_validation_validity_period_max_days
days.
§ [MOD-CS-MSG-2-2-2] Update Credential Schema fee checks
Account MUST have an available balance in its account to cover the required transaction fees.
§ [MOD-CS-MSG-2-3] Update Credential Schema execution
If all precondition checks passed, method is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
update
CredentialSchema
entrycs
withcs.id
equal toid
:cs.issuer_grantor_validation_validity_period
:issuer_grantor_validation_validity_period
cs.verifier_grantor_validation_validity_period
:verifier_grantor_validation_validity_period
cs.issuer_validation_validity_period
:issuer_validation_validity_period
cs.verifier_validation_validity_period
:verifier_validation_validity_period
cs.holder_validation_validity_period
:holder_validation_validity_period
cs.updated
: current timestamp.
§ [MOD-CS-MSG-3] Archive Credential Schema
Any account CAN execute this method.
§ [MOD-CS-MSG-3-1] Archive Credential Schema parameters
An account that would like to archive or unarchive a credential schema MUST call this method by specifying:
id
(uint64) (mandatory) id of the credential schema (mandatory);archive
(boolean) (mandatory), true means archive, false means unarchive.
§ [MOD-CS-MSG-3-2] Archive Credential Schema precondition checks
If any of these precondition checks fail, method MUST abort.
§ [MOD-CS-MSG-3-2-1] Archive Credential Schema basic checks
-
if a mandatory parameter is not present, method MUST abort.
-
id
MUST represent an existingCredentialSchema
entrycs
. -
load
TrustRegistry
tr
fromcs.tr_id
.tr.controller
MUST be the account executing the method, else MUST abort. -
archive
(boolean) (mandatory) MUST be a boolean.- If
archive
is true andcs.archived
is not null, MUST abort as Credential Schema is already archived. - If
archive
is false andcs.archived
is null, MUST abort as Credential Schema is already not archived.
- If
§ [MOD-CS-MSG-3-2-2] Archive Credential Schema fee checks
Account MUST have an available balance in its account to cover the required transaction fees.
§ [MOD-CS-MSG-3-3] Archive Credential Schema execution
If all precondition checks passed, method is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
update
CredentialSchema
entrycs
withcs.id
equal toid
: -
if
archived
is true: setcs.archived
to current timestamp. -
if
archived
is false: setcs.archived
to null. -
set
cs.modified
to current timestamp.
§ [MOD-CS-MSG-4] Update Module Parameters
Update Module Parameters.
Can only be executed through a governance proposal.
§ [MOD-CS-MSG-4-1] Update Module Parameters parameters
params
(KeySet<String, String>): the parameters to update and their values.
§ [MOD-CS-MSG-4-2] Update Module Parameters precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-CS-MSG-4-2-1] Update Module Parameters basic checks
params
: size ofparams
MUST be greater than 0. For eachparam
<key
,value
>key
MUST exist, else abort.
§ [MOD-CS-MSG-4-2-2] Update Module Parameters fee checks
provided transaction fees MUST be sufficient for execution
§ [MOD-CS-MSG-4-3] Update Module Parameters execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
for each parameter param
<key
, value
> in parameters
:
- update parameter set value =
value
where key =key
.
§ [MOD-CS-QRY-1] List Credential Schemas
Anyone CAN execute this method. Returned result MUST be ordered by CredentialSchema.created
asc.
§ [MOD-CS-QRY-1-1] List Credential Schemas parameters
tr_id
(string) (optional): to filter by trust registry id.modified_after
(timestamp) (optional): show schemas modified after this timestamp.response_max_size
(small number) (optional): default to 64. Max 1,024.
§ [MOD-CS-QRY-1-2] List Credential Schemas checks
modified_after
must be a timestamp.response_max_size
must be between 1 and 1,024.
§ [MOD-CS-QRY-1-3] List Credential Schemas execution
return a list of found entry, or an empty list if nothing found. Results MUST be ordered by modified
ASC.
§ [MOD-CS-QRY-2] Get Credential Schema
Anyone CAN execute this method.
§ [MOD-CS-QRY-2-1] Get Credential Schema parameters
id
of the credential schema (mandatory);
§ [MOD-CS-QRY-2-2] Get Credential Schema checks
id
must be a uint64.
§ [MOD-CS-QRY-2-3] Get Credential Schema execution
return found entry (if any).
§ [MOD-CS-QRY-3] Render Json Schema
Anyone CAN execute this method.
§ [MOD-CS-QRY-3-1] Render Json Schema parameters
id
of the credential schema (mandatory);
§ [MOD-CS-QRY-3-2] Render Json Schema checks
id
must be a uint64.
§ [MOD-CS-QRY-3-3] Render Json Schema execution
Render found entry (if any). In case value is returned by a REST API, content type MUST be set to “application/schema+json”.
§ [MOD-CS-QRY-4] List Module Parameters
Anyone CAN run this query.
§ [MOD-CS-QRY-4-2] List Module Parameters parameters
§ [MOD-CS-QRY-4-2] List Module Parameters query checks
§ [MOD-CS-QRY-4-3] List Module Parameters execution of the query
Return the list of the existing parameters and their values.
§ [MOD-CS-QRY-4-4] List Module Parameters API result example
{
"params": {
"key1": "value1",
"key2": "value2",
...
...
}
}
§ Permission Module
§ Permission Module Overview
This section is non-normative.
Permission are linked to a Credential Schema and representable as a tree.
The ECOSYSTEM type permissions are created by the Credential Schema owner. All other permissions are created by running a Validation Process.
A Validation Process (VP) is a process which involves an applicant (which is the controller of validation entry stored in a validation keeper), a validator permission, and optional fees plus transaction fees.
Validation is used by applicants that want to:
- be an issuer of a specific credential schema;
- be a verifier of a specific credential schema;
- be an issuer grantor of a specific credential schema;
- be a verifier grantor of a specific credential schema;
- get issued a credential of a specific credential schema;
- optionally get created a HOLDER permission (HOLDER permission may be used in combination with credentials, example for User Agent credentials).
In all cases, the process is very similar. Example execution of a validation process:
- Applicant starts a validation process by running the [start new validation] transaction. Validation process may be subject to paying validation fees, as defined by validator.
- Validation process usually requires that applicant connects to a validation VS identified by its DID, and execute a some validation steps, required for the validation process to conclude.
- If applicant qualifies, validator updates the validation entry by running the [set to validated] transaction, and applicant is granted new permissions, and/or gets issued a credential.
Validation is valid for a specific period, for example 365 days, as configured in the credential schema for credential schema related validations, or set by trust registry for user-agent validation.
In some cases, even if the validation is valid for a period of time, the resulting created permission or issued credential might have a shorter expiration timestamp because the validated attribute(s) might expire before validation expiration: in this case, the applicant must provide updated information to the validator before attribute expiration, in order to get issued an updated new permission and/or an updated credential.
If validation is set to expire, applicant that wishes to extend the expiration timestamp must renew its validation.
At any time, applicant can cancel the validation process.
Some special unexpected situation may arise and must be mitigated. Examples:
- if selected validator permission is revoked while applicant’s validation is in PENDING state: Applicant CAN cancel the validation process [MOD-PERM-MSG-6].
- if selected validator permission is revoked while applicant is in VALIDATED state: Applicant CAN renew the validation process by choosing a new validator [MOD-PERM-MSG-2].
- if selected validator permission is revoked while applicant is in TERMINATION_REQUESTED state and validator action is required: applicant MUST be able to set the validation state to TERMINATED.
§ [MOD-PERM-MSG-1] Start Permission VP
Any account CAN execute this method.
§ [MOD-PERM-MSG-1-1] Start Permission VP parameters
An Applicant that would like to start a permission validation process MUST execute this method by specifying:
type
(PermissionType) (mandatory): (ISSUER_GRANTOR, VERIFIER_GRANTOR, ISSUER, VERIFIER, HOLDER): the permission that the Applicant would like to get;validator_perm_id
(uint64) (optional): the validator permission (parent permission in the tree), chosen by the applicant.country
(string) (mandatory): a country of residence, alpha-2 code (ISO 3166), where applicant is located.
Available compatible perms can be found by using [MOD-PERM-QRY-1] and presented in a front-end so applicant can choose its validator.
§ [MOD-PERM-MSG-1-2] Start Permission VP precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-1-2-1] Start Permission VP basic checks
if a mandatory parameter is not present, transaction MUST abort.
type
(PermissionType) (mandatory) MUST be a valid PermissionType: ISSUER_GRANTOR, VERIFIER_GRANTOR, ISSUER, VERIFIER, HOLDER.validator_perm_id
(uint64) (mandatory): see MOD-PERM-MSG-1-2-2.country
(string) (mandatory) MUST be a valid alpha-2 code (ISO 3166).did
, if specified, MUST conform to the DID Syntax, as specified [DID-CORE].
A holder MAY directly connect to the DID VS of an issuer in order to get issued a credential. It’s up to the issuer to decide if running the validation process (for charging fees) is REQUIRED or not.
§ [MOD-PERM-MSG-1-2-2] Start Permission VP permission checks
-
Load
Permission
entryvalidator_perm
fromvalidator_perm_id
. It MUST be a valid permission AND (validator_perm.country
MUST be equal tocountry
, orvalidator_perm.country
MUST be null), else transaction MUST abort. -
Load
CredentialSchema
entrycs
fromvalidator_perm.schema_id
. It MUST exist. -
if
type
(PermissionType) is equal to ISSUER:-
if
cs.issuer_perm_management_mode
is equal to GRANTOR:validator_perm.type
MUST be ISSUER_GRANTOR, else MUST abort. -
else if
cs.issuer_perm_management_mode
is equal to ECOSYSTEM:validator_perm.type
MUST be ECOSYSTEM, else MUST abort. -
else MUST abort.
-
-
else if
type
(PermissionType) is equal to ISSUER_GRANTOR:-
if
cs.issuer_perm_management_mode
is equal to GRANTOR:validator_perm.type
MUST be ECOSYSTEM, else MUST abort. -
else abort.
-
-
else if
type
(PermissionType) is equal to VERIFIER:-
if
cs.verifier_perm_management_mode
is equal to GRANTOR:validator_perm.type
MUST be VERIFIER_GRANTOR, else MUST abort. -
else if
cs.verifier_perm_management_mode
is equal to ECOSYSTEM:validator_perm.type
MUST be ECOSYSTEM, else MUST abort. -
else abort.
-
-
else if
type
(PermissionType) is equal to VERIFIER_GRANTOR:-
if
cs.verifier_perm_management_mode
is equal to GRANTOR:validator_perm.type
MUST be ECOSYSTEM, else MUST abort. -
else abort.
-
-
else if
type
(PermissionType) is equal to HOLDER:-
if
cs.verifier_perm_management_mode
is equal to GRANTOR or ECOSYSTEM:validator_perm.type
MUST be ISSUER, else MUST abort. -
else abort.
-
At the end, if a valid permission validator_perm
is not found, transaction MUST abort.
§ [MOD-PERM-MSG-1-2-3] Start Permission VP fee checks
Load Permission
entry validator_perm
of the selected validator.
Applicant MUST have an available balance in its account, to cover the following fees:
- the required estimated transaction fees;
- the required
validation_fees_in_denom
:validator_perm.validation_fees
*GlobalVariables.trust_unit_price
. - the required
validation_trust_deposit_in_denom
:validation_fees_in_denom
*GlobalVariables.trust_deposit_rate
.
§ [MOD-PERM-MSG-1-3] Start Permission VP execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
Load
Permission
entryvalidator_perm
of the selected validator. -
calculate
validation_fees_in_denom
:validator_perm.validation_fees
*GlobalVariables.trust_unit_price
. -
calculate
validation_trust_deposit_in_denom
:validation_fees_in_denom
*GlobalVariables.trust_deposit_rate
. -
use [MOD-TD-MSG-1] to increase by
validation_trust_deposit_in_denom
the trust deposit of account running the method and transfer the corresponding amount toTrustDeposit
module. -
send
validation_fees_in_denom
to validation escrow account, if greater than 0. -
define
now
: current timestamp. -
create an persist a new permission entry
applicant_perm
:applicant_perm.id
: auto-incremented uint64.applicant_perm.grantee
: applicant's account.applicant_perm.type
:type
.applicant_perm.created
:now
applicant_perm.modified
:now
applicant_perm.deposit
:validation_trust_deposit_in_denom
.applicant_perm.validation_fees
: 0.applicant_perm.issuance_fees
: 0.applicant_perm.verification_fees
: 0.applicant_perm.validator_perm_id
:validator_perm_id
.applicant_perm.vp_last_state_change
:now
applicant_perm.vp_state
: PENDING.applicant_perm.vp_current_fees
(number):validation_fees_in_denom
.applicant_perm.vp_current_deposit
(number):validation_trust_deposit_in_denom
.applicant_perm.vp_summary_digest_sri
: null.applicant_perm.vp_term_requested
: null.applicant_perm.vp_validator_deposit
: 0.
§ Connecting to the VS of the Validator
This section is non-normative, and provided for understanding only.
This action must be initiated by the applicant.
During a validation process, if the associated validator_perm
includes a specific did
, the applicant should establish a secure connection with the validator’s VS (Verifiable Service) using a secure communication protocol such as DIDComm or DWN.
Upon connecting to the VS, the applicant should be required by the validator to complete one or more of the following tasks:
- Prove control over the controller account that initiated the validation process (e.g., via blind signature or cryptographic challenge).
- Provide requested information, such as filling out forms, submitting documents, or other forms of disclosure as required by the validation VS.
- If the requested permission includes a VS DID, the applicant should prove control over the corresponding DID to the validator’s VS.
Once the validator determines that the process is complete, they may terminate the validation process and create the permission accordingly. This permission configuration usually include:
validation_fees
issuance_fees
verification_fees
country
(jurisdictional scope)permission expiration
The validator may compile a summary file of the validation process, documenting exchanged data, proofs, and decisions, and share it with the applicant via the VS connection or another secure channel.
For audit or governance purposes, the validator should register a digest (e.g., hash or SRI) of this summary in applicant_perm.vp_summary_digest_sri
.
§ [MOD-PERM-MSG-2] Renew Permission VP
This section is non-normative.
- Requesting a renewal has no effect on permission expiration or issued credentials.
- Renewal is only possible with the same validator.
- If validator permission is not valid anymore, applicant MUST perform a new validation process with another validator.
- Renewal does not allow changing the
perm.country
,perm.validation_fees
,perm.issuance_fees
,perm.verification_fees
. To change these values, applicant MUST start a new validation process.
§ [MOD-PERM-MSG-2-1] Renew Permission VP parameters
An account controller of a permission entry that would like to renew a validation process for this permission MUST execute this method by specifying:
id
(uint64) (mandatory): id of the permission for which applicant would like to renew the validation process;
§ [MOD-PERM-MSG-2-2] Renew Permission VP precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-2-2-1] Renew Permission VP basic checks
if a mandatory parameter is not present, transaction MUST abort.
id
MUST be a valid uint64 and a permission entry with the same id MUST exist.
§ [MOD-PERM-MSG-2-2-2] Renew Permission VP permission checks
- Load
Permission
entryapplicant_perm
. account running the operation MUST beapplicant_perm.grantee
, else MUST abort.applicant_perm
MUST be a valid permission. - Load
Permission
entryvalidator_perm
fromapplicant_perm.validator_perm_id
. It MUST exist, and be a valid permission, else MUST abort.
§ [MOD-PERM-MSG-2-2-3] Renew Permission VP fee checks
- Load
Permission
entryvalidator_perm
fromapplicant_perm.validator_perm_id
.
Applicant MUST have an available balance in its account, to cover the following fees:
- the required estimated transaction fees;
- the required
validation_fees_in_denom
:validator_perm.validation_fees
*GlobalVariables.trust_unit_price
. - the required
validation_trust_deposit_in_denom
:validation_fees_in_denom
*GlobalVariables.trust_deposit_rate
.
§ [MOD-PERM-MSG-2-3] Renew Permission VP execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
Load
Permission
entryapplicant_perm
. -
Load
Permission
entryvalidator_perm
fromapplicant_perm.validator_perm_id
. -
calculate
validation_fees_in_denom
:validator_perm.validation_fees
*GlobalVariables.trust_unit_price
. -
calculate
validation_trust_deposit_in_denom
:validation_fees_in_denom
*GlobalVariables.trust_deposit_rate
. -
use [MOD-TD-MSG-1] to increase by
validation_trust_deposit_in_denom
the trust deposit of account running the method and transfer the corresponding amount toTrustDeposit
module. -
send
validation_fees_in_denom
to validation escrow account, if greater than 0. -
define
now
: current timestamp. -
update permission entry:
applicant_perm.vp_state
: PENDING.applicant_perm.vp_last_state_change
: current timestamp.applicant_perm.deposit
:applicant_perm.applicant_deposit
+validation_trust_deposit_in_denom
.applicant_perm.vp_current_fees
(number):validation_fees_in_denom
.applicant_perm.vp_current_deposit
(number):validation_trust_deposit_in_denom
.applicant_perm.modified
:now
§ [MOD-PERM-MSG-3] Set Permission VP to Validated
Any account CAN execute this method.
§ [MOD-PERM-MSG-3-1] Set Permission VP to Validated parameters
An account that would like to set a validation entry to VALIDATED MUST execute this method by specifying:
id
(uint64) (mandatory): id of the validation process;effective_until
(timestamp) (optional): timestamp until when (exclusive) thisPermission
is effective, null if no time limit should been set for this permission or if we want it to be aligned with the validation process expiration timestamp calculated by this method.validation_fees
(number) (optional): Agreed validation_fees for this permission. Can be set only the first time this method is called (cannot be set for renewals).issuance_fees
(number) (optional): Agreed issuance_fees for this permission. Can be set only the first time this method is called (cannot be set for renewals).verification_fees
(number) (optional): Agreed verification_fees for this permission. Can be set only the first time this method is called (cannot be set for renewals).country
(string) (optional): country, as an alpha-2 code (ISO 3166), this permission refers to. If null, it means permission is not linked to a specific country. Can be set only the first time this method is called (cannot be set for renewals).vp_summary_digest_sri
(digest_sri) (optional): an optional digest_sri, set by validator, of a summary of the information, proofs… provided by the applicant.
§ [MOD-PERM-MSG-3-2] Set Permission VP to Validated precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-3-2-1] Set Permission VP to Validated basic checks
if a mandatory parameter is not present, transaction MUST abort.
id
MUST be a valid uint64.- Load
Permission
entryapplicant_perm
fromid
. If no entry found, abort. applicant_perm.vp_state
MUST be equal to PENDING, else abort.validation_fees
(number) (optional): If specified, MUST be zero or a positive number. Ifapplicant_perm.effective_from
is not null (we are in renewal)validation_fees
MUST be equal toapplicant_perm.validation_fees
, else abort.issuance_fees
(number) (optional): If specified, MUST be zero or a positive number. Ifapplicant_perm.effective_from
is not null (we are in renewal)issuance_fees
MUST be equal toapplicant_perm.issuance_fees
or, else abort.verification_fees
(number) (optional): If specified, MUST be zero or a positive number. Ifapplicant_perm.effective_from
is not null (we are in renewal)verification_fees
MUST be equal toapplicant_perm.verification_fees
, else abort.country
(string) (optional): MUST be a valid alpha-2 code (ISO 3166), or null. Ifapplicant_perm.effective_from
is not null (we are in renewal)country
MUST be equal toapplicant_perm.country
, else abort.vp_summary_digest_sri
(digest_sri) (optional): MUST be null ifvalidation.type
is set to HOLDER (for HOLDER, proofs can be stored in credentials). Else, MUST be a valid digest_sri as specified in integrity of related resources spec. Example:sha384-MzNNbQTWCSUSi0bbz7dbua+RcENv7C6FvlmYJ1Y+I727HsPOHdzwELMYO9Mz68M26
.
Calculation of vp_exp
, the validation process expiration timestamp, required to verify provided effective_until
:
-
Load
CredentialSchema
cs
fromapplicant_perm.schema_id
. -
let’s define
validity_period
=cs.issuer_grantor_validation_validity_period
(ifapplicant_perm.type
is ISSUER_GRANTOR),cs.verifier_grantor_validation_validity_period
(ifapplicant_perm.type
is VERIFIER_GRANTOR),cs.issuer_validation_validity_period
(ifapplicant_perm.type
is ISSUER),cs.verifier_validation_validity_period
(ifapplicant_perm.type
is VERIFIER), orcs.holder_validation_validity_period
(ifapplicant_perm.type
is HOLDER). -
if
validity_period
is NULL:vp_exp
= NULL. -
else if
applicant_perm.vp_exp
is null,vp_exp
= timestamp of now() plusvalidity_period
. -
else
vp_exp
=applicant_perm.vp_exp
plusvalidity_period
Now, let’s verify effective_until
:
- if
effective_until
is NULL, no issue. - else if
applicant_perm.effective_until
is NULL,effective_until
MUST be greater than current current timestamp AND, ifvp_exp
is not null, lower or equal tovp_exp
. - else
effective_until
MUST be greater thanapplicant_perm.effective_until
AND, ifvp_exp
is not null, lower or equal tovp_exp
.
§ [MOD-PERM-MSG-3-2-2] Set Permission VP to Validated validator perms
- load
validator_perm
fromapplicant_perm.validator_perm_id
.validator_perm
MUST be a valid permission. - account running the method MUST be
validator_perm.grantee
.
This section is non-normative.
If validator_perm
is not a valid permission (expired, revoked, slashed…) then applicant should start a new validation process.
§ [MOD-PERM-MSG-3-2-3] Set Permission VP to Validated fee checks
Validator MUST have the required estimated transaction fees in its account, else transaction MUST abort.
§ [MOD-PERM-MSG-3-3] Set Permission VP to Validated execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
- Load
Permission
entryapplicant_perm
fromid
. - Load
Permission
entryvalidator_perm
fromapplicant_perm.validator_perm_id
. - define
now
timestamp of now().
Calculate vp_exp
:
-
Load
CredentialSchema
cs
fromapplicant_perm.schema_id
. -
let’s define
validity_period
=cs.issuer_grantor_validation_validity_period
(ifapplicant_perm.type
is ISSUER_GRANTOR),cs.verifier_grantor_validation_validity_period
(ifapplicant_perm.type
is VERIFIER_GRANTOR),cs.issuer_validation_validity_period
(ifapplicant_perm.type
is ISSUER),cs.verifier_validation_validity_period
(ifapplicant_perm.type
is VERIFIER), orcs.holder_validation_validity_period
(ifapplicant_perm.type
is HOLDER). -
if
validity_period
is NULL:vp_exp
= NULL. -
else if
applicant_perm.vp_exp
is null,vp_exp
= timestamp of now() plusvalidity_period
. -
else
vp_exp
=applicant_perm.vp_exp
plusvalidity_period
.
Change value of provided effective_until
if needed, and abort if needed:
-
if provided
effective_until
is NULL:- change value of provided
effective_until
tovp_exp
.
- change value of provided
-
else if
applicant_perm.effective_until
is NULL:- verify that provided
effective_until
is greater thannow
else MUST abort - if
vp_exp
is not null, verify that providedeffective_until
is lower or equal tovp_exp
else MUST abort
- verify that provided
-
else:
effective_until
MUST be greater thanapplicant_perm.effective_until
else MUST abort- if
vp_exp
is not null, verify that providedeffective_until
is lower or equal tovp_exp
else MUST abort.
Update Permission
applicant_perm
:
- set
applicant_perm.modified
tonow
. - set
applicant_perm.vp_state
to VALIDATED. - set
applicant_perm.vp_last_state_change
tonow
. - set
applicant_perm.vp_current_fees
to 0; - set
applicant_perm.vp_current_deposit
to 0; - set
applicant_perm.vp_summary_digest_sri
tovp_summary_digest_sri
. - set
applicant_perm.vp_exp
tovp_exp
. - set
applicant_perm.effective_until
toeffective_until
. - if
applicant_perm.effective_from
IS NULL (first time method is called for this perm, and thus we are not in a renewal):- set
applicant_perm.validation_fees
tovalidation_fees
; - set
applicant_perm.issuance_fees
toissuance_fees
; - set
applicant_perm.verification_fees
toverification_fees
; - set
applicant_perm.country
tocountry
; - set
applicant_perm.effective_from
tonow
.
- set
Fees and Trust Deposits:
- transfer the full amount
applicant_perm.vp_current_fees
from escrow account to validator accountvalidator_perm.grantee
; - Calculate
validator_trust_deposit
=applicant_perm.vp_current_fees
*GlobalVariables.trust_deposit_rate
; - Increase validator perm trust deposit: use [MOD-TD-MSG-1] to increase by
validator_trust_deposit
the trust deposit of account running the method and transfer the corresponding amount toTrustDeposit
module. Setapplicant_perm.validator_deposit
toapplicant_perm.validator_deposit
+validator_trust_deposit
.
§ [MOD-PERM-MSG-4] Request Permission VP Termination
This section is non-normative.
At any time, applicant may request termination of the validation process current action.
Requesting termination of the validation process set permission entry to the TERMINATION_REQUESTED state so that corresponding permissions can be terminated. Then, the applicant or the validator (if type is not HOLDER) or the validator (if type is HOLDER) MUST confirm termination transaction for the validation entry to be set to TERMINATED and trust deposits to be freed.
§ [MOD-PERM-MSG-4-1] Request Permission VP Termination parameters
An account that would like to set a Permission
entry to TERMINATION_REQUESTED MUST execute this method by specifying:
id
(uint64) (mandatory): id of the validation process;
§ [MOD-PERM-MSG-4-2] Request Permission VP Termination precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-4-2-1] Request Permission VP Termination basic checks
if a mandatory parameter is not present, transaction MUST abort.
id
MUST be a valid uint64.- Load
Permission
entryapplicant_perm
with this id. It MUST exist. applicant_perm.vp_state
must be VALIDATED.
If validation process already expired, either party can terminate the validation process to reclaim the deposit. Else, only the grantee can terminate the vp.
- if
applicant_perm.vp_exp
is lower thannow
:- Load
Permission
entryvalidator_perm
with id equal toapplicant_perm.validator_perm_id
. account running the transaction MUST be eitherapplicant_perm.grantee
ORvalidator_perm.grantee
.
- Load
- else account running the transaction MUST be
applicant_perm.grantee
.
§ [MOD-PERM-MSG-4-2-2] Request Permission VP Termination fee checks
Applicant MUST have the required estimated transaction fees in its account, else transaction MUST abort.
§ [MOD-PERM-MSG-4-3] Request Permission VP Termination execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
Define vars:
- define
now
current timestamp.
Update perm:
- set
applicant_perm.modified
tonow
. - set
applicant_perm.vp_term_requested
to current timestamp. - set
applicant_perm.vp_last_state_change
tonow
. ifapplicant_perm.type
is not HOLDER, orapplicant_perm.vp_exp
is lower thannow
: - set
applicant_perm.vp_state
to TERMINATED. - set
applicant_perm.terminated
tonow
- set
applicant_perm.terminated_by
to account executing the method. else - set
applicant_perm.vp_state
to TERMINATION_REQUESTED.
Update deposits if state is TERMINATED:
If applicant_perm.vp_state
has been set to TERMINATED:
-
if
applicant_perm.deposit
> 0:- call [MOD-TD-MSG-1] to reduce
applicant_perm.grantee
trust deposit byapplicant_perm.deposit
. - set
applicant_perm.deposit
to 0.
- call [MOD-TD-MSG-1] to reduce
-
if
applicant_perm.validator_deposit
> 0:- load
Permission
validator_perm
fromapplicant_perm.validator_perm_id
. Call [MOD-TD-MSG-1] to reducevalidator_perm.grantee
trust deposit byapplicant_perm.validator_deposit
. - set
applicant_perm.validator_deposit
to 0.
- load
if applicant_perm.type
is HOLDER, then validator SHOULD revoke the corresponding credential and then call the confirm validation method to free the trust deposits.
§ [MOD-PERM-MSG-5] Confirm Permission VP Termination
This method is called by a validator to confirm the termination of a vp when permission type is HOLDER, usually after revoking (or not) the verifiable credential of the holder. It can be although called by the grantee after a timeout, defined in GlobalVariables.validation_term_requested_timeout_days
.
§ [MOD-PERM-MSG-5-1] Confirm Permission VP Termination parameters
An account that would like to set confirm validation entry termination MUST execute this method by specifying:
id
(uint64) (mandatory): id of the validation process;
§ [MOD-PERM-MSG-5-2] Confirm Permission VP Termination precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-5-2-1] Confirm Permission VP Termination basic checks
if a mandatory parameter is not present, transaction MUST abort.
id
MUST be a valid uint64 and a validation entry with the same id MUST exist.Permission
entry must be in state TERMINATION_REQUESTED.
§ [MOD-PERM-MSG-5-2-2] Confirm Permission VP Termination permission checks
id
MUST be a valid uint64.- Load
Permission
entryapplicant_perm
with this id. It MUST exist.
Timeout not reached: only validator can call the method:
if applicant_perm.term_requested
+ GlobalVariables.validation_term_requested_timeout_days
is after or equal to current timestamp:
- Load
Permission
entryvalidator_perm
with idapplicant_perm.validator_perm_id
. It MUST exist, andvalidator_perm.grantee
MUST be the account executing the method. Else MUST abort.
Timeout reached: either the validator or the applicant can call the method:
if applicant_perm.term_requested
+ GlobalVariables.validation_term_requested_timeout_days
is before now:
- Load
Permission
entryvalidator_perm
with idapplicant_perm.validator_perm_id
. It MUST exist, andvalidator_perm.grantee
CAN be the account executing the method. ORapplicant_perm.grantee
CAN be the account executing the method.
Else MUST abort.
For HOLDER type validation, if validation has not expired, only the validator can terminate the validation, unless GlobalVariables.validation_term_requested_timeout_days
have passed since termination request and validator did not answered.
§ [MOD-PERM-MSG-5-2-3] Confirm Permission VP Termination fee checks
Account executing the method MUST have the required estimated transaction fees.
§ [MOD-PERM-MSG-5-3] Confirm Permission VP Termination execution
If all precondition checks passed, transaction is executed.
Define vars:
- define
now
current timestamp.
Update:
-
set
applicant_perm.modified
tonow
. -
set validation entry
validation.state
to TERMINATED. -
set
validation.last_state_change
:now
. -
if
applicant_perm.deposit
> 0:- call MOD-TD-MSG-1 to reduce
applicant_perm.grantee
trust deposit byapplicant_perm.deposit
. - set
applicant_perm.deposit
to 0.
- call MOD-TD-MSG-1 to reduce
If account executing the method is the validator:
- if
applicant_perm.validator_deposit
> 0:- load
Permission
validator_perm
fromapplicant_perm.validator_perm_id
. Call [MOD-TD-MSG-1] to reducevalidator_perm.grantee
trust deposit byapplicant_perm.validator_deposit
. - set
applicant_perm.validator_deposit
to 0.
- load
If account executing the method is the grantee (timeout), validator is punished and its trust deposit is not freed.
§ [MOD-PERM-MSG-6] Cancel Permission VP Last Request
At any time, applicant of a permission validation process may request cancellation of the process, provided state is PENDING. Upon method execution, the pending validation is cancelled and paid trust fees are refunded. If vp_exp
is not null, vp_state
is set back to VALIDATED, else vp_state
is set to TERMINATED.
§ [MOD-PERM-MSG-6-1] Cancel Permission VP Last Request parameters
An account that would like to set cancel a validation entry MUST execute this method by specifying:
id
(uint64) (mandatory): id of thePermission
entry;
§ [MOD-PERM-MSG-6-2] Cancel Permission VP Last Request precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-6-2-1] Cancel Permission VP Last Request basic checks
if a mandatory parameter is not present, transaction MUST abort.
id
MUST be a valid uint64.- Load
Permission
entryapplicant_perm
with this id. It MUST exist. - account running the transaction MUST be
applicant_perm.grantee
. applicant_perm.vp_state
MUST be PENDING.
§ [MOD-PERM-MSG-6-2-2] Cancel Permission VP Last Request fee checks
Account executing the method MUST have the required estimated transaction fees in its account, else transaction MUST abort.
§ [MOD-PERM-MSG-6-3] Cancel Permission VP Last Request execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
Load
Permission
entryapplicant_perm
withid
. It MUST exist. -
define
now
: current timestamp. -
set
applicant_perm.modified
tonow
. -
if
applicant_perm.vp_exp
is null (validation never completed), setapplicant_perm.vp_state
to TERMINATED, else setapplicant_perm.vp_state
to VALIDATED. -
set
applicant_perm.vp_last_state_change
tonow
. -
if
applicant_perm.vp_current_fees
> 0: -
if
applicant_perm.vp_current_deposit
> 0:- call [MOD-TD-MSG-1] to reduce trust deposit of
applicant_perm.grantee
byapplicant_perm.vp_current_deposit
- set
applicant_perm.vp_current_deposit
to 0.
- call [MOD-TD-MSG-1] to reduce trust deposit of
§ [MOD-PERM-MSG-7] Create Root Permission
This method is used by controllers of Trust Registries. When they create a Credential Schema, they need to create (a) permission(s) of type ECOSYSTEM so that other participants can run validation processes.
§ [MOD-PERM-MSG-7-1] Create Root Permission parameters
An account that would like to create a Permission
entry MUST call this method by specifying:
schema_id
(uint64) (mandatory)did
(string) (mandatory): DID of the VS grantee service.country
(optional).effective_from
(timestamp) (optional): timestamp from when (exclusive) this Perm is effective. MUST be in the future.effective_until
(timestamp) (optional): timestamp until when (exclusive) this Perm is effective, null if it doesn’t expire. If not null, MUST be greater thaneffective_from
.validation_fees
(number) (mandatory): price to pay by applicant to validator for running a validation process that uses this perm as validator, for a given validation period, in trust unit. Default to 0.issuance_fees
(number) (mandatory): price to pay by the issuer of a credential of this schema to the grantee of this perm when a credential is issued, in trust unit. Default to 0.verification_fees
(number) (mandatory): price to pay by the verifier of a credential of this schema to the grantee of this perm when a credential is verified, in trust unit. Default to 0.
§ [MOD-PERM-MSG-7-2] Create Root Permission precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-7-2-1] Create Root Permission basic checks
if a mandatory parameter is not present, transaction MUST abort.
schema_id
MUST be a valid uint64 and a credential schema entry with this id MUST exist.did
, if specified, MUST conform to the DID Syntax, as specified [DID-CORE].effective_from
must be in the future.effective_until
, if not null, must be greater thaneffective_from
country
if not null, MUST be a valid alpha-2 code (ISO 3166).validation_fees
(number) (mandatory): MUST be >= 0.issuance_fees
(number) (mandatory): MUST be >= 0.verification_fees
(number) (mandatory): MUST be >= 0.
§ [MOD-PERM-MSG-7-2-2] Create Root Permission permission checks
To execute this method, account MUST match at least one these rules, else transaction MUST abort.
- The related
CredentialSchema
entry is loaded withschema_id
, and will be namedcs
in this section. - The related
TrustRegistry
entrytr
is loaded fromcs.tr_id
. - account executing the method MUST be the controller of
tr
. - else MUST abort.
HOLDER permission are used so that it is possible to identify grantee account for paying rewards.
§ [MOD-PERM-MSG-7-2-3] Create Root Permission fee checks
Account MUST have the required estimated transaction fees available.
§ [MOD-PERM-MSG-7-3] Create Root Permission execution
If all precondition checks passed, method is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
- define
now
: current timestamp.
A new entry Permission
perm
MUST be created:
perm.id
: auto-incremented uint64.perm.schema_id
:schema_id
.perm.modified
tonow
.perm.type
: ECOSYSTEM.perm.did
:did
.perm.grantee
:account
executing the method.perm.created
:now
perm.created_by
:account
executing the method.perm.effective_from
:effective_from
perm.effective_until
:effective_until
perm.country
:country
perm.validation_fees
:validation_fees
perm.issuance_fees
:issuance_fees
perm.verification_fees
:verification_fees
perm.deposit
: 0
§ [MOD-PERM-MSG-8] Extend Permission
This method can only be called by a validator.
§ [MOD-PERM-MSG-8-1] Extend Permission parameters
An account that would like to extend the effective_until timestamp of a permission MUST call this method by specifying:
id
(uint64) (mandatory): id of the permission;effective_until
(timestamp) (optional): timestamp until when (exclusive) thisPermission
is effective.
§ [MOD-PERM-MSG-8-2] Extend Permission precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-8-2-1] Extend Permission basic checks
if a mandatory parameter is not present, transaction MUST abort.
id
MUST be a valid uint64.- Load
Permission
entryapplicant_perm
fromid
. If no entry found, abort. applicant_perm
MUST be a valid permissioneffective_until
MUST be greater thanapplicant_perm.effective_until
else MUST abort.effective_until
MUST be lower or equal toapplicant_perm.vp_exp
else MUST abort.
§ [MOD-PERM-MSG-8-2-2] Extend Permission validator perms
- if
applicant_perm.validator_perm_id
is null andapplicant_perm.type
is ECOSYSTEM, account running the method MUST be `applicant_perm.grantee’. - else load
validator_perm
fromapplicant_perm.validator_perm_id
.validator_perm
MUST be a valid permission. account running the method MUST bevalidator_perm.grantee
.
§ [MOD-PERM-MSG-8-2-3] Extend Permission fee checks
Validator MUST have the required estimated transaction fees in its account, else transaction MUST abort.
§ [MOD-PERM-MSG-8-3] Extend Permission execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
define
now
: current timestamp. -
Load
Permission
entryapplicant_perm
fromid
. -
Load
Permission
entryvalidator_perm
fromapplicant_perm.validator_perm_id
. -
set
applicant_perm.effective_until
toeffective_until
-
set
applicant_perm.extended
tonow
-
set
applicant_perm.modified
tonow
-
set
applicant_perm.extended_by
to account executing the method.
§ [MOD-PERM-MSG-9] Revoke Permission
This method can only be called by a validator.
§ [MOD-PERM-MSG-9-1] Revoke Permission parameters
An account that would like to extend the effective_until timestamp of a permission MUST call this method by specifying:
id
(uint64) (mandatory): id of the permission;
§ [MOD-PERM-MSG-9-2] Revoke Permission precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-9-2-1] Revoke Permission basic checks
if a mandatory parameter is not present, transaction MUST abort.
id
MUST be a valid uint64.- Load
Permission
entryapplicant_perm
fromid
. If no entry found, abort. applicant_perm
MUST be a valid permission
§ [MOD-PERM-MSG-9-2-2] Revoke Permission validator perms
- load
validator_perm
fromapplicant_perm.validator_perm_id
.validator_perm
MUST be a valid permission. - account running the method MUST be
validator_perm.grantee
.
§ [MOD-PERM-MSG-9-2-3] Revoke Permission fee checks
Validator MUST have the required estimated transaction fees in its account, else transaction MUST abort.
§ [MOD-PERM-MSG-9-3] Revoke Permission execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
define
now
: current timestamp. -
Load
Permission
entryapplicant_perm
fromid
. -
Load
Permission
entryvalidator_perm
fromapplicant_perm.validator_perm_id
. -
set
applicant_perm.revoked
tonow
-
set
applicant_perm.modified
tonow
-
set
applicant_perm.revoked_by
to account executing the method.
§ [MOD-PERM-MSG-10] Create or Update Permission Session
Any credential exchange that requires issuer or verifier to pay fees implies the creation of a PermissionSession
.
If the peer wants to issue a credential, the agent
, the Verifiable User Agent or Verifiable Service that receive the request MUST send to peer:
- a
uuid
for session identification; - the
wallet_agent_perm_id
permission id of the agent wallet that will store the credential.
If the peer wants to verify a credential, agent must send to peer:
- a
uuid
for session identification; - a map of compatible found credentials in available wallets for the requested schema_id: Map<uint64: wallet_agent_perm_id, string[] issuer_dids>
payer
MUST create a Permission Session using the above information, then, agent
MUST check session has been created and is valid before accepting the action (receive and store issued credential, or accept a presentation request).
See VT spec.
§ [MOD-PERM-MSG-10-1] Create or Update Permission Session parameters
An account that would like to create or update a PermissionSession
entry MUST send a Msg by specifying:
id
(uuid) (mandatory): id of thePermissionSession
.issuer_perm_id
(uint64) (optional): the id of the perm od the issuer, if we are dealing with the issuance of a credential.verifier_perm_id
(uint64) (optional): the id of the perm of the issuer, if we are dealing with the verification of a credential.agent_perm_id
(uint64) (mandatory): the agent that received the request (credential offer for issuance, presentation request for verification).wallet_agent_perm_id
(uint64) (mandatory): the wallet agent where the credential will be or is stored, if different than agent.
§ [MOD-PERM-MSG-10-2] Create or Update Permission Session precondition checks
If any of these precondition checks fail, transaction MUST abort.
if issuer_perm_id
is null AND verifier_perm_id
is null, MUST abort.
- define
issuer_perm
as null. - define
verifier_perm
as null.
if issuer_perm_id
is no null:
- Load
issuer_perm
fromissuer_perm_id
. - if
issuer_perm.type
is not ISSUER, abort. - if
issuer_perm
is not a valid permission, abort.
if verifier_perm_id
is no null:
- Load
verifier_perm
fromverifier_perm_id
. - if
verifier_perm.type
is not VERIFIER, abort. - if
verifier_perm
is not a valid permission, abort.
agent:
- Load
agent_perm
fromagent_perm_id
. - if
agent_perm.type
is not ISSUER, abort. - if
agent_perm
is not a valid permission, abort.
wallet_agent:
- Load
wallet_agent_perm
fromwallet_agent_perm_id
. - if
wallet_agent_perm.type
is not ISSUER, abort. - if
wallet_agent_perm
is not a valid permission, abort.
we might want to check that credential schema of agent and wallet_agent perms is an ECS of type UserAgent. At the moment there is no way of doing it. We consider User Agent will not report a permission that is not controlled by its owner.
§ [MOD-PERM-MSG-10-3] Create or Update Permission Session fee checks
Account MUST have sufficient available balance for:
- the required estimated transaction fees;
- the required beneficiary fees and its corresponding trust deposit
trust_fees
as explained below:
To calculate the required beneficiary fees, use “Find Beneficiaries” query method below to get the set of beneficiary permission found_perm_set
. Now that we have the set with all ancestors, we can calculate the required fees:
- define
beneficiary_fees
= 0 - if
verifier_perm
is null: iterate over permissionsperm
offound_perm_set
and setbeneficiary_fees
=beneficiary_fees
+perm.issuance_fees
. - if
verifier_perm
is NOT null: iterate over permissionsperm
offound_perm_set
and setbeneficiary_fees
=beneficiary_fees
+perm.verification_fees
.
Total required trust_fees
to be paid by account executing the method, including Trust Deposit: (beneficiary_fees
+ percent fees for agents) * trust deposit percent * trust unit price:
trust_fees
= beneficiary_fees
* (1 + (GlobalVariables.user_agent_reward_rate
+ GlobalVariables.wallet_user_agent_reward_rate
)) * (1 + GlobalVariables.trust_deposit_rate
) * GlobalVariables.trust_unit_price
See Pay per trust fees above.
§ [MOD-PERM-MSG-10-4] Create or Update Permission Session execution
If all precondition checks passed, method is executed.
-
Load all permissions as in basic checks.
-
define
now
: current timestamp. -
use “Find Beneficiaries” above to build
found_perm_set
. -
if
verifier_perm
is null:- for each
Permission
perm
fromfound_perm_set
, ifperm.issuance_fees
> 0:- transfer
perm.issuance_fees
*GlobalVariables.trust_unit_price
* (1 -GlobalVariables.trust_deposit_rate
) toperm.grantee
. - use [MOD-TD-MSG-1] to increase by
perm.issuance_fees
*GlobalVariables.trust_unit_price
*GlobalVariables.trust_deposit_rate
the trust deposit ofperm.grantee
. - use [MOD-TD-MSG-1] to increase by
perm.issuance_fees
*GlobalVariables.trust_unit_price
*GlobalVariables.trust_deposit_rate
the trust deposit ofaccount
executing the method.
- transfer
- for each
-
else :
- for each
Permission
perm
fromfound_perm_set
, ifperm.verification_fees
> 0:- transfer
perm.verification_fees
*GlobalVariables.trust_unit_price
* (1 -GlobalVariables.trust_deposit_rate
) toperm.grantee
. - use [MOD-TD-MSG-1] to increase by
perm.verification_fees
*GlobalVariables.trust_unit_price
*GlobalVariables.trust_deposit_rate
the trust deposit ofperm.grantee
. - use [MOD-TD-MSG-1] to increase by
perm.verification_fees
*GlobalVariables.trust_unit_price
*GlobalVariables.trust_deposit_rate
the trust deposit ofaccount
executing the method.
- transfer
- for each
If new, create entry PermissionSession
session
:
session.id
:id
session.controller
: account running the methodsession.agent_perm_id
:agent_perm_id
session.authz[]
: create and put (issuer_perm_id
,verifier_perm_id
,wallet_agent_perm_id
).session.modified:
:now
session.created:
:now
Else update:
- add (
issuer_perm_id
,verifier_perm_id
,wallet_agent_perm_id
) tosession.authz[]
session.modified:
:now
session.authz[]
can contain null issuer_perm_id
OR verifier_perm_id
§ [MOD-PERM-MSG-11] Update Permission Module Parameters
Update Permission Module Parameters.
Can only be executed through a governance proposal.
§ [MOD-PERM-MSG-11-1] Update Permission Module Parameters parameters
params
(KeySet<String, String>): the parameters to update and their values.
§ [MOD-PERM-MSG-11-2] Update Permission Module Parameters precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-11-2-1] Update Permission Module Parameters basic checks
params
: size ofparams
MUST be greater than 0. For eachparam
<key
,value
>key
MUST exist, else abort.
§ [MOD-PERM-MSG-11-2-2] Update Permission Module Parameters fee checks
provided transaction fees MUST be sufficient for execution
§ [MOD-PERM-MSG-11-3] Update Permission Module Parameters execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
for each parameter param
<key
, value
> in parameters
:
- update parameter set value =
value
where key =key
.
§ [MOD-PERM-MSG-12] Slash Permission Trust Deposit
This method can only be called by either:
- the
account
of the validator that created the Permission that they want to slash, - the
grantee
of theECOSYSTEM
Permission (the Trust Registry controller) of the corresponding credential schema that this Permission is linked to; - the network governance authority (using a proposal).
§ [MOD-PERM-MSG-12-1] Slash Permission Trust Deposit parameters
An account that would like to slash a permission trust deposit MUST call this method by specifying:
id
(uint64) (mandatory): id of the permission;amount
(number) (mandatory): the amount to slash
§ [MOD-PERM-MSG-12-2] Slash Permission Trust Deposit precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-12-2-1] Slash Permission Trust Deposit basic checks
if a mandatory parameter is not present, transaction MUST abort.
id
MUST be a valid uint64.- Load
Permission
entryapplicant_perm
fromid
. If no entry found, abort. applicant_perm
MUST be a valid permissionamount
MUST be lower or equal toapplicant_perm.deposit
else MUST abort.
§ [MOD-PERM-MSG-12-2-2] Slash Permission Trust Deposit validator perms
Either Option #1, #2 or #3 MUST be true else abort.
Option #1: executed by validator
if applicant_perm.validator_perm_id
is defined:
- load
validator_perm
fromapplicant_perm.validator_perm_id
.validator_perm
MUST be a valid permission. - account running the method MUST be
validator_perm.grantee
.
Option #2: executed by ecosystem controller
- find
ecosystem_perm
usingecosystem_perm.type
=ECOSYSTEM
andecosystem_perm.schema_id
=applicant_perm.schema_id
. - account running the method MUST be
ecosystem_perm.grantee
.
Option #3: network governance authority
Account executing the method MUST be the network governance authority (voted proposal).
§ [MOD-PERM-MSG-12-2-3] Slash Permission Trust Deposit fee checks
Account executing the method MUST have the required estimated transaction fees in its account, else transaction MUST abort.
§ [MOD-PERM-MSG-12-3] Slash Permission Trust Deposit execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
define
now
: current timestamp. -
Load
Permission
entryapplicant_perm
fromid
. -
Load
Permission
entryvalidator_perm
fromapplicant_perm.validator_perm_id
. -
set
applicant_perm.slashed
tonow
-
set
applicant_perm.modified
tonow
-
set
applicant_perm.slashed_deposit
toapplicant_perm.slashed_deposit
+amount
-
set
applicant_perm.slashed_by
to account executing the method.
use MOD-TD-MSG-7 to burn the slashed amount
from the trust deposit of applicant_perm.grantee
.
§ [MOD-PERM-MSG-13] Repay Permission Slashed Trust Deposit
This method can only be called by anyone that want to repay the deposit of a slashed perm. This won’t make the perm re-usable: it will be needed for the grantee to request a new permission, as slashed permissions cannot be revived (same happen for revoked, etc…).
Nevertheless, to get a new permission for a given ecosystem, it is needed, using this method, to repay the deposit of a slashed permission first.
§ [MOD-PERM-MSG-13-1] Repay Permission Slashed Trust Deposit parameters
An account that would like to repay a permission trust deposit MUST call this method by specifying:
id
(uint64) (mandatory): id of the permission
§ [MOD-PERM-MSG-13-2] Repay Permission Slashed Trust Deposit precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-13-2-1] Repay Permission Slashed Trust Deposit basic checks
if a mandatory parameter is not present, transaction MUST abort.
id
MUST be a valid uint64.- Load
Permission
entryapplicant_perm
fromid
. If no entry found, abort.
§ [MOD-PERM-MSG-13-2-2] Repay Permission Slashed Trust Deposit validator perms
Any account can execute this method.
§ [MOD-PERM-MSG-13-2-3] Repay Permission Slashed Trust Deposit fee checks
Account executing the method MUST have the required estimated transaction fees in its account, plus applicant_perm.slashed_deposit
, else transaction MUST abort.
§ [MOD-PERM-MSG-13-3] Repay Permission Slashed Trust Deposit execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
define
now
: current timestamp. -
Load
Permission
entryapplicant_perm
fromid
. -
set
applicant_perm.repaid
tonow
-
set
applicant_perm.modified
tonow
-
set
applicant_perm.repaid_deposit
toamount
. -
set
applicant_perm.repaid_by
to account executing the method.
use Adjust Trust Deposit to transfer amount
to trust deposit of applicant_perm.grantee
.
§ [MOD-PERM-MSG-14] Create Permission
This simple permission creation method can be used to self-create an ISSUER (resp. VERIFIER) permission if issuance mode (resp. verification mode) is set to OPEN
for a given schema. As permissions are the anchor of ecosystem trust deposit operations, it is required if Ecosystem decided to charge the issuance (or the verification) of the credentials.
§ [MOD-PERM-MSG-14-1] Create Permission parameters
An account that would like to create a Permission
entry MUST call this method by specifying:
schema_id
(uint64) (mandatory)type
(PermissionType) (mandatory): ISSUER or VERIFIER.did
(string) (mandatory): DID of the VS grantee service.country
(optional).effective_from
(timestamp) (optional): timestamp from when (exclusive) this Perm is effective. MUST be in the future.effective_until
(timestamp) (optional): timestamp until when (exclusive) this Perm is effective, null if it doesn’t expire. If not null, MUST be greater thaneffective_from
.verification_fees
(number) (optional): price to pay by the verifier of a credential of this schema to the grantee of this perm when a credential is verified, in trust unit. Default to 0.
§ [MOD-PERM-MSG-14-2] Create Permission precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-PERM-MSG-14-2-1] Create Permission basic checks
if a mandatory parameter is not present, transaction MUST abort.
schema_id
MUST be a valid uint64 and a credential schema entry with this id MUST exist.type
(PermissionType) (mandatory): MUST be ISSUER or VERIFIER, else abort.did
, if specified, MUST conform to the DID Syntax, as specified [DID-CORE].effective_from
must be in the future.effective_until
, if not null, must be greater thaneffective_from
country
if not null, MUST be a valid alpha-2 code (ISO 3166).verification_fees
(number) (optional): If specified, MUST be >= 0.
§ [MOD-PERM-MSG-14-2-2] Create Permission permission checks
To execute this method, account MUST match at least one these rules, else transaction MUST abort.
- The related
CredentialSchema
entry is loaded withschema_id
, and will be namedcs
in this section. - if
type
is equal to ISSUER: ifcs.issuer_perm_management_mode
is not equal to OPEN, MUST abort. - if
type
is equal to VERIFIER: ifcs.verifier_perm_management_mode
is not equal to OPEN, MUST abort.
§ [MOD-PERM-MSG-14-2-3] Create Permission fee checks
Account MUST have the required estimated transaction fees available.
§ [MOD-PERM-MSG-14-3] Create Permission execution
If all precondition checks passed, method is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
- define
now
: current timestamp.
A new entry Permission
perm
MUST be created:
perm.id
: auto-incremented uint64.perm.schema_id
:schema_id
.perm.modified
tonow
.perm.type
:type
.perm.did
:did
.perm.grantee
:account
executing the method.perm.created
:now
perm.created_by
:account
executing the method.perm.effective_from
:effective_from
perm.effective_until
:effective_until
perm.country
:country
perm.validation_fees
: 0perm.issuance_fees
: 0perm.verification_fees
:verification_fees
if specified, else 0.perm.deposit
: 0
§ [MOD-PERM-QRY-1] List Permissions
Anyone CAN execute this method.
§ [MOD-PERM-QRY-1-1] List Permissions parameters
modified_after
(timestamp) (optional): show permissions modified after this timestamp.response_max_size
(small number) (optional): default to 64. Min 1, max 1,024.
§ [MOD-PERM-QRY-1-2] List Permissions checks
modified_after
(timestamp) (mandatory): show permissions modified after this timestamp.response_max_size
(small number) (optional): Must be min 1, max 1,024.
§ [MOD-PERM-QRY-1-3] List Permissions execution
return a list of found entries, or an empty list if nothing found. Ordered by last modified asc.
§ [MOD-PERM-QRY-2] Get Permission
Anyone CAN execute this method.
§ [MOD-PERM-QRY-2-1] Get Permission parameters
id
of the credential schema permission (mandatory);
§ [MOD-PERM-QRY-2-2] Get Permission checks
id
must be a uint64.
§ [MOD-PERM-QRY-2-3] Get Permission execution
return found entry (if any).
§ [MOD-PERM-QRY-3] Find Permissions With DID
Usually, Verifiable Trust verification flow will work as in the example below. To simplify, we suppose VUAa is both a User Agent and a Verifiable Credential Wallet.
- a User of Verifiable User Agent A (VUAa) wants to connect to Verifiable Service S (VSs)
- VUAa verifies credentials of VSs, including presented Organization or Person credential. For this credential, VUAa calls the Find Permissions With DID to verify issuer was authorized and get the corresponding permission(s).
- If everything went well, VUAa connects to VSs and presents its VUA credential. For this credential, VSs calls the Find Permissions With DID to verify issuer was authorized to deliver this credential to VUAa and get the corresponding permission(s).
- Now, VSs wants to issue a credential to User of VUAa. VSs will request a session_id to VUAa, execute a transaction to create the session, and sends a driving license credential to VUAa.
- VUAa gets the PermissionSession and dereferences the linked permission Ids to verify issuer paid and is authorized for this session and this driving license schema.
§ [MOD-PERM-QRY-3-1] Find Permission With DID parameters
did
(string) (mandatory): did of the service that want to issue a credential.type
(PermissionType) (mandatory): type of the permission.schema_id
(uint64) (mandatory): the schema_id.country
(string) (optional): a country code, to select Permission with this country code or with a null country code.when
(timestamp) (optional): Find permission atwhen
. When set, means find only valid permission atwhen
, when unspecified, means find all permissions.
§ [MOD-PERM-QRY-3-2] Find Permission With DID checks
did
(string) (mandatory): MUST be a DID.type
(PermissionType) (mandatory): MUST be a PermissionType.schema_id
(uint64) (mandatory): an entry withid
equal toschema_id
must be present inCredentialSchema
.country
(string) (optional): if specified, MUST be a country code.when
(timestamp) (optional): MUST be a timestamp.
§ [MOD-PERM-QRY-3-3] Find Permission With DID execution
This method should use an index per cs.id
and insert any new entry hash(perm.did
;perm.type
) when perm.effective_from
and perm.did
are not null (updated when perm
is modified). Index example:
SchemaId => hash(did;type) => Perm id list => (load perms one by one and filter other query attributes such as country, effective_from, effective_until, revoked, terminated)
- load
CredentialSchema
cs
fromschema_id
. - define
Permission[]
found_perms
as empty list.
Using example index, calculate hash(did
;type
) to get the list of matching permissions perms[]
.
- then for each
perm
inperms[]
:- check if perm is matching
country
: (ifcountry
is unspecified (perm.country
IS NULL) elsecountry
is specified (perm.country
IS NULL orperm.country
is equal tocountry
)), else ignoreperm
. - if
perm
is valid for requestedcountry
:- if time is unset, add
perm
tofound_perms
. - else check perm validity: if
time
is greater or equal toperm.effective_from
ANDtime
is lower thanperm.effective_until
AND ((perm.revoked
is NULL) OR (perm.revoked
is greater thantime
)) AND ((perm.terminated
is NULL) OR (perm.terminated
is greater thantime
)), then the permission matches, add it tofound_perms
- if time is unset, add
- end
- check if perm is matching
- end
return found_perms
.
§ [MOD-PERM-QRY-4] Find Beneficiaries
Anyone can execute this method.
To calculate the fees required for paying the beneficiaries, it is needed to recurse all involved perms until the root of the permission tree (which is the trust registry perm), starting from the 2 branches issuer_perm
and verifier_perm
. As both branches may have common ancestors, we can create a Set (unordered collection with no duplicates), and recurse over the 2 branches, adding found perms. If verifier_perm
is null, issuer_perm
is never added to the set. If verifier_perm
is NOT null, issuer_perm
is added to the set if it exists but verifier_perm
is not added to the set.
If a Credential Schema is configured with permission management mode set to OPEN
for either issuance or verification, it is necessary to check whether the associated ECOSYSTEM permission requires issuance or verification fees. This check MUST be performed by calling this method and passing the id of the ECOSYSTEM permission. In this case, the only beneficiary of the fees is the ECOSYSTEM permission itself.
Example 1: verifier_perm
: is not set: it’s a credential offer, schema configured to have Issuer Grantors.
Example 2: verifier_perm
: is not set: it’s a credential offer. Schema configured to NOT have Issuer Grantors.
Example 3: verifier_perm
is set, it’s a presentation request. Schema configured to have Verifier and Issuer Grantors.
§ [MOD-PERM-QRY-4-1] Find Beneficiaries parameters
issuer_perm_id
(uint64) (optional): id of issuer permission.verifier_perm_id
(uint64) (optional): id of verifier permission.
§ [MOD-PERM-QRY-4-2] Find Beneficiaries checks
- if
issuer_perm_id
andverifier_perm_id
are unset then MUST abort. - if
issuer_perm_id
is specified, loadissuer_perm
fromissuer_perm_id
, Permission MUST exist and MUST be a valid permission. - if
verifier_perm_id
is specified, loadverifier_perm
fromverifier_perm_id
, Permission MUST exist and MUST be a valid permission.
§ [MOD-PERM-QRY-4-3] Find Beneficiaries execution
Let’s build the set. Revoked and terminated permissions will not be added to the set. Expired permissions, if not revoked/terminated, will be considered.
-
create Set
found_perm_set
. -
define permission
current_perm
as null. -
load perms
issuer_perm
and optionalverifier_perm
as specified in basic checks above.
if issuer_perm
is not null:
- set
current_perm
=issuer_perm
- while
current_perm.validator_perm_id
is not null:- set
current_perm
to loaded permission fromcurrent_perm.validator_perm_id
. - if
current_perm.revoked
ANDcurrent_perm.terminated
is NULL, Addcurrent_perm
tofound_perm_set
.
- set
Additionally, if verifier_perm
is not null:
- if
issuer_perm
is not null, addissuer_perm
tofound_perm_set
- set
current_perm
=verifier_perm
- while
verifier_perm.validator_perm_id
is not null:- set
current_perm
to loaded permission fromcurrent_perm.validator_perm_id
. - if
current_perm.revoked
ANDcurrent_perm.terminated
is NULL, Addcurrent_perm
tofound_perm_set
.
- set
return found_perms
.
This works even is schema is open to any issuer or open to any verifier.
§ [MOD-PERM-QRY-5] Get PermissionSession
§ [MOD-PERM-QRY-5-1] Get PermissionSession parameters
id
(uuid) (mandatory): the id of thePermissionSession
.
§ [MOD-PERM-QRY-5-2] Get PermissionSession checks
§ [MOD-PERM-QRY-5-3] Get PermissionSession execution
return PermissionSession
entry if found, else return not found.
§ [MOD-PERM-QRY-6] List Permission Module Parameters
§ [MOD-PERM-QRY-6-2] List Permission Module Parameters parameters
§ [MOD-PERM-QRY-6-2] List Permission Module Parameters query checks
§ [MOD-PERM-QRY-6-3] List Permission Module Parameters execution of the query
Return the list of the existing parameters and their values.
§ [MOD-PERM-QRY-6-4] List Permission Module Parameters API result example
{
"params": {
"key1": "value1",
"key2": "value2",
...
...
}
}
§ [MOD-PERM-QRY-7] List Permission Sessions
Anyone CAN execute this method.
§ [MOD-PERM-QRY-7-1] List Permission Sessions parameters
modified_after
(timestamp) (optional): show permissions modified after this timestamp.response_max_size
(small number) (optional): default to 64. Min 1, max 1,024.
§ [MOD-PERM-QRY-7-2] List Permission Sessions checks
modified_after
(timestamp) (mandatory): show permissions modified after this timestamp.response_max_size
(small number) (optional): Must be min 1, max 1,024.
§ [MOD-PERM-QRY-7-3] List Permission Sessions execution
return a list of found entries, or an empty list if nothing found, ordered by last modified asc.
§ Validation Examples
§ Getting a Credential from an Authorized Issuer
This section is non-normative.
Example of an Applicant that would like to get issued a credential (HOLDER):
§ Add a DID to the List of Granted Issuers of a Credential Schema
This section is non-normative.
§ DID Directory Module
The DID Directory is a keystore of DIDs.
§ DID Directory Module Overview
This section is non-normative.
Registering a DID in the DID Directory makes the DID, its associated credentials, and related services (such as VSs) publicly discoverable by crawlers and indexers.
⚠️ Registration is optional and not required for Trust Resolution.
However, it may be useful for certain use cases, for example, a Social Browser may rely on the DID Directory to crawl and index all DIDs that reference Social Channel VSs, enabling users to search and discover them directly through the app.
The DID Directory is open to anyone, meaning:
- There is no built-in verification at the VPR level to confirm that the registering account actually controls the DID.
- Since the VPR does not resolve DIDs, it cannot verify ownership or control.
This implies that a DID could be registered by someone who is not its legitimate controller, an inherent limitation of the model.
That said, the deterrent is economic: why would anyone pay registration fees for a DID they do not control?
To protect the intent of the actual DID controller, registration alone does not trigger indexing.
Indexers must respect optional crawler directives included in the DID Document (e.g., index
, noindex
), ensuring that control over indexation remains with the DID controller, regardless of who registered the DID in the directory.
It is not needed to register DIDs that are already present in Trust Registries, Permissions,… as services linked to these DIDs are indexed like if they were registered in the DID Directory.
§ [MOD-DD-MSG-1] Add a DID
Add a DID to the DID Directory, with expiration timestamp set to current timestamp + years years.
Any account CAN run this method.
§ [MOD-DD-MSG-1-1] Add a DID transaction parameters
did
(string) (mandatory): the DID.years
(tiny number) (optional): the number of years we want the entry to be valid for, 1-31 years. Default to 1 year.
§ [MOD-DD-MSG-1-2] Add a DID precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-DD-MSG-1-2-1] Add a DID basic checks
- if a mandatory parameter is not present, transaction MUST abort.
did
: the specified DID format MUST conform to the DID Syntax, as specified [DID-CORE], and MUST NOT already exist in DID directory.years
: can be null, but if specified, must be between 1 and 31 inclusive.
§ [MOD-DD-MSG-1-2-2] Add a DID fee checks
Applicant MUST have an available balance (not blocked by trust deposit nor staked) in its account, to cover the following fees:
- the required estimated transaction fees;
- the required
trust_deposit_in_denom
:GlobalVariables.trust_unit_price
*did_directory_trust_deposit
*years
.
§ [MOD-DD-MSG-1-3] Add a DID execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
Recalculate
trust_deposit_in_denom
, as specified above. -
use [MOD-TD-MSG-1] to increase by
trust_deposit_in_denom
the trust deposit of account running the method and transfer the corresponding amount toTrustDeposit
module. -
Create DidDirectory entry:
- set
entry.did
todid
; - set
entry.controller
toaccount
; - set
entry.created
to timestamp of day; - set
entry.modified
to timestamp of day; - set
entry.exp
to timestamp of day +years
years; - set
entry.deposit
totrust_deposit_in_denom
- set
§ [MOD-DD-MSG-2] Renew a DID
Renew a DID, by adding years years to current expiration timestamp.
This method MUST be run by controller of the DID entry.
§ [MOD-DD-MSG-2-1] Renew a DID transaction parameters
did
(string) (mandatory): the DID.years
(tiny number) (optional): the number of years we want to ad to the current expiration timestamp, 1-31 years. Default to 1 year.
§ [MOD-DD-MSG-2-2] Renew a DID precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-DD-MSG-2-2-1] Renew a DID basic checks
if any of the following conditions is not satisfied, transaction MUST abort.
did
: the specified DID format MUST conform to the DID Syntax, as specified [DID-CORE] and MUST exist in DID directory.years
: can be null, but if specified, must be between 1 and 31 inclusive.- account executing the transaction must be the
controller
of the DID.
§ [MOD-DD-MSG-2-2-2] Renew a DID fee checks
Applicant MUST have an available balance (not blocked by trust deposit nor staked) in its account, to cover the following fees:
- the required estimated transaction fees;
- the required
trust_deposit_in_denom
:GlobalVariables.trust_unit_price
*did_directory_trust_deposit
*years
.
§ [MOD-DD-MSG-2-3] Renew a DID execution of the transaction
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
Recalculate
trust_deposit_in_denom
, as specified above. -
Recalculate
removal_gas_fees
, as specified above. -
use [MOD-TD-MSG-1] to increase by
trust_deposit_in_denom
the trust deposit of account running the method and transfer the corresponding amount toTrustDeposit
module. -
Update DidDirectory entry:
- set
entry.modified
to timestamp of day; - set
entry.exp
to entry.exp+
years` years; - set
entry.deposit
toentry.deposit
+trust_deposit_in_denom
.
- set
§ [MOD-DD-MSG-3] Remove a DID
Remove a DID and unlock the corresponding trust deposit.
§ [MOD-DD-MSG-3-1] Remove a DID transaction parameters
did
(string) (mandatory): the DID.
§ [MOD-DD-MSG-3-2] Remove a DID precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-DD-MSG-3-2-1] Remove a DID basic checks
if any of the following conditions is not satisfied, transaction MUST abort.
did
: the specified DID format MUST conform to the DID Syntax, as specified [DID-CORE], and MUST exist in DID directory.- if now() < expireTs +
GlobalVariables.did_directory_grace_period_days
; then account running the transaction MUST be equals tocontroller
; else parameter account CAN be any account.
§ [MOD-DD-MSG-3-2-2] Remove a DID fee checks
Account running the transaction MUST have the required estimated transaction fees in its account, else transaction MUST abort.
§ [MOD-DD-MSG-3-3] Remove a DID execution of the transaction
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
load
DidDirectory
entrydd
. -
use [MOD-TD-MSG-1] to decrease by
dd.deposit
the trust deposit ofdd.controller
account. -
remove entry from
DidDirectory
.
§ [MOD-DD-MSG-4] Touch a DID
This method is used to update the modified
of a given entry so that crawlers will know DID should be immediately reindexed.
§ [MOD-DD-MSG-4-1] touch a DID transaction parameters
did
(string) (mandatory): the DID.
§ [MOD-DD-MSG-4-2] Touch a DID precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-DD-MSG-4-2-1] Touch a DID basic checks
- if a mandatory parameter is not present, transaction MUST abort.
did
: the specified DID format MUST conform to the DID Syntax, as specified [DID-CORE], and MUST exist in DID directory.
§ [MOD-DD-MSG-4-2-2] Touch a DID fee checks
Account running the transaction MUST have the required estimated transaction fees in its account, else transaction MUST abort.
§ [MOD-DD-MSG-4-3] Touch a DID execution of the transaction
If all precondition checks passed, transaction is executed.
Transaction execution MUST perform the following tasks, and rollback if any error occurs.
- update
modified
to timestamp of the day for the selected entry.
§ [MOD-DD-MSG-5] Update Module Parameters
Update Module Parameters.
Can only be executed through a governance proposal.
§ [MOD-DD-MSG-5-1] Update Module Parameters parameters
params
(KeySet<String, String>): the parameters to update and their values.
§ [MOD-DD-MSG-5-2] Update Module Parameters precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-DD-MSG-5-2-1] Update Module Parameters basic checks
params
: size ofparams
MUST be greater than 0. For eachparam
<key
,value
>key
MUST exist, else abort.
§ [MOD-DD-MSG-5-2-2] Update Module Parameters fee checks
provided transaction fees MUST be sufficient for execution
§ [MOD-DD-MSG-5-3] Update Module Parameters execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
for each parameter param
<key
, value
> in parameters
:
- update parameter set value =
value
where key =key
.
§ [MOD-DD-QRY-1] List DIDs
This method is used to query the DID Directory keeper. Returned data MUST be ordered by modified
asc.
§ [MOD-DD-QRY-1-1] List DIDs query parameters
The following parameters are optional:
account
(account): if specified, returns only DIDs controlled byaccount
.modified
(timestamp): if specified, returns only DIDs changed aftermodified
.expired
(boolean): if specified, show expired services, in and over grace period.over_grace
(boolean): if specified, show expired services, over grace period.response_max_size
(small number): default to 64. Max 1,024.
§ [MOD-DD-QRY-1-2] List DIDs query checks
If any of these checks fail, query MUST fail.
response_max_size
must be between 1 and 1,024.
§ [MOD-DD-QRY-1-3] List DIDs execution of the query
If all precondition checks passed, query is executed and result (may be empty) returned.
§ [MOD-DD-QRY-2] Get a DID
This method is used to read a DID from the DID Directory keeper. As this method does not modify data, it does not require a transaction.
§ [MOD-DD-QRY-2-1] Get a DID query parameters
did
(string) (mandatory): the DID.
§ [MOD-DD-QRY-2-2] Get a DID query checks
did
MUST conform to the DID Syntax, as specified [DID-CORE].
§ [MOD-DD-QRY-2-3] Get a DID execution of the query
If DID is found, return the corresponding entry, else empty result is returned.
§ [MOD-DD-QRY-3] List Module Parameters
Anyone CAN run this query.
§ [MOD-DD-QRY-3-2] List Module Parameters parameters
§ [MOD-DD-QRY-3-2] List Module Parameters query checks
§ [MOD-DD-QRY-3-3] List Module Parameters execution of the query
Return the list of the existing parameters and their values.
§ [MOD-DD-QRY-3-4] List Module Parameters API result example
{
"params": {
"key1": "value1",
"key2": "value2",
...
...
}
}
§ Trust deposit module
§ Trust deposit module overview
This section is non-normative.
Concept: the trust deposit is used to lock trust value as a stake. To process application messages that perform state changes, several modules methods are requiring a trust deposit to be sent, from the executing account, to the trust deposit module.
We will use a similar method than the one described here to manage trust deposit and yield calculation and easy way.
Example:
In our example, we suppose a VPR is just starting and no trust transaction have taken place yet. For this reason:
TrustDeposit
module has a balance of0
:TrustDeposit.deposit
:0
.GlobalVariables.trust_deposit_share_value
has a value of1
.
Operation #1:
an account account1
wants to create a transaction that requires:
- 10
denom
to be sent to theaccount1
trust deposit; - 5
denom
for network fees.
First, the Trust Deposit: execution of the method will perform the following (we consider this account had no TrustDeposit
entry yet):
-
10
denom
are sent to theTrustDeposit
module.TrustDeposit.deposit
=TrustDeposit.deposit
+10
-
a
TrustDeposit
entrytd1
is created foraccount1
running the service with:td1.deposit
=10
td1.shares
=10
/GlobalVariables.trust_deposit_share_value
=10
Second, fee distribution: let’s suppose 70% of transaction fees are distributed to validators, and 30% of transaction fees are distributed to trust deposit holders. For this specific transaction:
-
30% * 5 = 1.5
denom
will be sent toTrustDeposit
module, which will increase theGlobalVariables.trust_deposit_share_value
: -
TrustDeposit.deposit
=11.5
-
GlobalVariables.trust_deposit_share_value
=1.15
.
Now, account1
can (optionally) reclaim the difference between the GlobalVariables.trust_deposit_share_value
* tt.share
minus tt.denom
, which represents the trust (yield) gains.
Operation #2:
Another account account2
wants to create a transaction that requires:
- 20
denom
to be sent to theaccount2
trust deposit; - 10
denom
for network fees.
First, Trust Deposit:
-
20
denom
are sent to theTrustDeposit
module.TrustDeposit.deposit
=31.5
-
a
TrustDeposit
entrytd2
is created foraccount2
:td2.deposit
=20
td2.shares
=20
/GlobalVariables.trust_deposit_share_value
=20
/1.15
~=17.39...
Second, fee distribution: let’s suppose 70% of transaction fees are distributed to validators, and 30% of transaction fees are distributed to trust deposit holders. For this specific transaction:
-
30% * 10 = 3
denom
will be sent toTrustDeposit
module, which will increase theGlobalVariables.trust_deposit_share_value
: -
TrustDeposit.deposit
=34.5
-
GlobalVariables.trust_deposit_share_value
=1.15
*34.5
/31.5
~=1.2595...
After the 2 operations:
account1
real deposit (based on share) isaccount1.share
*GlobalVariables.trust_deposit_share_value
~=12.595...
, available withdrawable yield isaccount1.share
*GlobalVariables.trust_deposit_share_value
-account1.deposit
~=2.595...
account2
real deposit (based on share) isaccount2.share
*GlobalVariables.trust_deposit_share_value
~=21.90...
, available withdrawable yield isaccount2.share
*GlobalVariables.trust_deposit_share_value
-account2.deposit
~=1.90...
§ [MOD-TD-MSG-1] Adjust Trust Deposit
This method is used to increase or decrease the trust deposit of a specific account.
Only the modules that require trust deposit manipulation CAN call this method. If trust deposit has been slashed and not repaid, method execution MUST abort.
§ [MOD-TD-MSG-1-1] Adjust Trust Deposit method parameters
account
(account) (mandatory): account of the trust deposit we want to adjust.augend
(number) (mandatory): value to add to the deposit, in denom.
§ [MOD-TD-MSG-1-2] Adjust Trust Deposit precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-TD-MSG-1-2-1] Adjust Trust Deposit basic checks
- if a mandatory parameter is not present, transaction MUST abort.
Value checks:
-
augend
(number) (mandatory): MUST be strictly positive or strictly negative. -
load
TrustDeposit
entrytd
foraccount
running the method.- if
td
does not exist:- if
augend
is negative, transaction MUST abort.
- if
- else
- if
augend
is negative andtd.claimable
-augend
is greater thantd.deposit
transaction MUST abort.
- if
- if
§ [MOD-TD-MSG-1-2-2] Adjust Trust Deposit fee checks
- load
TrustDeposit
entrytd
foraccount
running the method. - if
td
exists:- if
augend
is positive, calculateneeded_deposit
=augend
-td.claimable
. - else
needed_deposit
= 0.
- if
- else
needed_deposit
=augend
.
Account running the transaction MUST have the required estimated transaction fees in its account plus needed_deposit
, else transaction MUST abort.
§ [MOD-TD-MSG-1-3] Adjust Trust Deposit execution of the method
If all precondition checks passed, method is executed in a transaction.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
-
if a
TrustDeposit
entrytd
does not exist for thisaccount
, create entrytd
:- transfer
augend
fromaccount
toTrustDeposit
account. - calculate
augend_share
=amount
/GlobalVariables.trust_deposit_share_value
. - set
td.account
toaccount
; - set
td.deposit
toaugend
; - set
td.share
toaugend_share
; - set
td.claimable
to 0. - set
td.slashed_deposit
to 0. - set
td.repaid_deposit
to 0. - set
td.slash_count
to 0.
- transfer
-
else if
slashed_deposit
> 0 andslashed_deposit
<repaid_deposit
=> deposit has been slashed and not repaid, so MUST abort. -
else if
augend
> 0:-
if
td.claimable
> 0:- if
td.claimable
>=augend
:- set
td.claimable
totd.claimable
-augend
- set
- else
- use bank? to transfer
augend
-td.claimable
fromaccount
toTrustDeposit
account. - set
td.deposit
totd.deposit
+augend
-td.claimable
- set
td.claimable
to 0 - calculate
missing_augend_share
from missing tokens :missing_augend_share
= (augend
-td.claimable
) /GlobalVariables.trust_deposit_share_value
. - set
td.share
totd.share
+missing_augend_share
- use bank? to transfer
- if
-
else
- use bank? to transfer
augend
fromaccount
toTrustDeposit
account. - calculate
augend_share
=augend
/GlobalVariables.trust_deposit_share_value
. - set
td.deposit
totd.deposit
+augend
- set
td.share
totd.share
+augend_share
- use bank? to transfer
-
-
else if
augend
< 0:- set
td.claimable
totd.claimable
-augend
- set
The last case, augend
< 0, is to free trust deposit (ej when terminating a permission).
§ [MOD-TD-MSG-2] Reclaim Trust Deposit Yield
This method is used to reclaim yield. If trust deposit has been slashed and not repaid, method execution MUST abort.
Any account MAY call this method.
For a given TrustDeposit
entry td
, claimable yield is calculated like this:
claimable_yield
= td.share
* GlobalVariables.trust_deposit_share_value
- td.deposit
.
If claimable_yield
is positive, they can be claimed.
§ [MOD-TD-MSG-2-1] Reclaim Trust Deposit Yield method parameters
N/A
§ [MOD-TD-MSG-2-2] Reclaim Trust Deposit Yield precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-TD-MSG-2-2-1] Reclaim Trust Deposit Yield basic checks
- Load
TrustDeposit
entrytd
fromaccount
running the method. - if
td.slashed_deposit
> 0 andtd.slashed_deposit
<td.repaid_deposit
=> deposit has been slashed and not repaid, so MUST abort. - calculate
claimable_yield
=td.share
*GlobalVariables.trust_deposit_share_value
-td.deposit
. - if
claimable_yield
<= 0, transaction MUST abort.
§ [MOD-TD-MSG-2-2-2] Reclaim Trust Deposit Yield fee checks
Account running the transaction MUST have the required estimated transaction fees in its account, else transaction MUST abort.
§ [MOD-TD-MSG-2-3] Reclaim Trust Deposit Yield Value execution of the method
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
For the TrustDeposit
entry td
linked to account
:
- Load
TrustDeposit
entrytd
fromaccount
running the method. - calculate
claimable_yield
=td.share
*GlobalVariables.trust_deposit_share_value
-td.deposit
. - update
td.share
=td.share
-claimable_yield
/GlobalVariables.trust_deposit_share_value
- transfer
claimable_yield
fromTrustDeposit
account toaccount
.
Maybe here the claimed yield should go to the deposit. TBD.
§ [MOD-TD-MSG-3] Reclaim Trust Deposit
This method is used to reclaim claimable trust deposit value, td.claimable
. If trust deposit has been slashed and not repaid, method execution MUST abort.
Any account MAY call this method.
In order to discourage user from using this method:
- execution of the method will reduce value of
td.deposit
by subtractingclaimed
and settd.claimable
totd.claimable
-claimed
; GlobalVariables.trust_deposit_reclaim_burn_rate
*claimed
will be burned fromaccount
.
§ [MOD-TD-MSG-3-1] Reclaim Trust Deposit method parameters
claimed
(number) (mandatory): value to reclaim, in denom.
§ [MOD-TD-MSG-3-2] Reclaim Trust Deposit precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-TD-MSG-3-2-1] Reclaim Trust Deposit basic checks
if any of these conditions is not satisfied, transaction MUST abort.
claimed
must be > 0.- if
td.slashed_deposit
> 0 andtd.slashed_deposit
<td.repaid_deposit
=> deposit has been slashed and not repaid, so MUST abort. TrustDeposit
entrytd
MUST exist for thisaccount
, andtd.claimable
MUST be greater or equal toclaimed
.- calculate
required_minimum_deposit
=td.share
*GlobalVariables.trust_deposit_share_value
.required_minimum_deposit
MUST be greater or equal totd.deposit
-claimed
, else method MUST abort.
§ [MOD-TD-MSG-3-2-2] Reclaim Trust Deposit fee checks
Account running the transaction MUST have the required estimated transaction fees in its account, else transaction MUST abort.
§ [MOD-TD-MSG-3-3] Reclaim Trust Deposit execution of the method
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
For the TrustDeposit
entry td
linked to account
:
- set
td.claimable
totd.claimable
-claimed
. - set
td.deposit
totd.deposit
-claimed
. - set
td.share
totd.share
-claimed
/GlobalVariables.trust_deposit_share_value
- calculate
to_burn
=GlobalVariables.trust_deposit_reclaim_burn_rate
*claimed
from account. - calculate
to_transfer
=claimed
-to_burn
- transfer
to_transfer
fromTrustDeposit
account toaccount
. - burn
to_burn
fromTrustDeposit
module.
§ [MOD-TD-MSG-4] Update Module Parameters
Update Module Parameters.
Can only be executed through a governance proposal.
§ [MOD-TD-MSG-4-1] Update Module Parameters parameters
params
(KeySet<String, String>): the parameters to update and their values.
§ [MOD-TD-MSG-4-2] Update Module Parameters precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-TD-MSG-4-2-1] Update Module Parameters basic checks
params
: size ofparams
MUST be greater than 0. For eachparam
<key
,value
>key
MUST exist, else abort.
§ [MOD-TD-MSG-4-2-2] Update Module Parameters fee checks
provided transaction fees MUST be sufficient for execution
§ [MOD-TD-MSG-4-3] Update Module Parameters execution
If all precondition checks passed, transaction is executed.
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
for each parameter param
<key
, value
> in parameters
:
- update parameter set value =
value
where key =key
.
§ [MOD-TD-MSG-5] Slash Trust Deposit
This method is used by the network governance authority to globally slash an account
trust deposit.
This method can only be called by a governance proposal. A globally slashed account MUST repay the slashed deposit in order to continue to use the services provided by the VPR. When and account is slashed, and while slashed deposit has not been repaid, all account linked permissions MUST be considered non trustable.
This method is for network governance authority slash. For ecosystem slash, see Slash Permission Trust Deposit.
§ [MOD-TD-MSG-5-1] Slash Trust Deposit method parameters
account
(account) (mandatory): account of the trust deposit we want to slash.amount
(number) (mandatory): value to slash, in denom.
§ [MOD-TD-MSG-5-2] Slash Trust Deposit precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-TD-MSG-5-2-1] Slash Trust Deposit basic checks
if any of these conditions is not satisfied, transaction MUST abort.
amount
must be > 0.TrustDeposit
entrytd
MUST exist for thisaccount
, andtd.deposit
MUST be greater or equal toamount
.
§ [MOD-TD-MSG-5-2-2] Slash Trust Deposit fee checks
Account running the transaction MUST have the required estimated transaction fees in its account, else transaction MUST abort.
§ [MOD-TD-MSG-5-3] Slash Trust Deposit execution of the method
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
- define
now
: current timestamp.
For the TrustDeposit
entry td
linked to account
:
- set
td.deposit
totd.deposit
-amount
. - set
td.share
totd.share
-amount
/GlobalVariables.trust_deposit_share_value
- burn
amount
fromTrustDeposit
account. - set
td.slashed_deposit
totd.slashed_deposit
+amount
- set
td.last_slashed
to now - set
td.repaid_by
to undefined. - if
td.slash_count
is undefined, set it to1
, else set it totd.slash_count
+ 1
§ [MOD-TD-MSG-6] Repay Slashed Trust Deposit
Repay a slashed trust deposit. Can be executed by any account.
§ [MOD-TD-MSG-6-1] Repay Slashed Trust Deposit method parameters
account
(account) (mandatory): account of the trust deposit we want to repay.amount
(number) (mandatory): value to repay, in denom.
§ [MOD-TD-MSG-6-2] Repay Slashed Trust Deposit precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-TD-MSG-6-2-1] Repay Slashed Trust Deposit basic checks
if any of these conditions is not satisfied, transaction MUST abort.
amount
must be > 0.TrustDeposit
entrytd
MUST exist for thisaccount
, andamount
MUST be exactly equal totd.slashed_deposit
-td.repaid_deposit
.
§ [MOD-TD-MSG-6-2-2] Repay Slashed Trust Deposit fee checks
Account running the transaction MUST have the required estimated transaction fees in its account plus amount
, else transaction MUST abort.
§ [MOD-TD-MSG-6-3] Repay Slashed Trust Deposit execution of the method
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
- define
now
: current timestamp.
For the TrustDeposit
entry td
linked to account
:
- set
td.deposit
totd.deposit
+amount
. - set
td.share
totd.share
+amount
/GlobalVariables.trust_deposit_share_value
- add
amount
toTrustDeposit
account. - set
td.repaid_deposit
totd.repaid_deposit
+amount
- set
td.last_repaid
to now - set
td.last_repaid_by
to account executing the transaction.
§ [MOD-TD-MSG-7] Burn Ecosystem Slashed Trust Deposit
Burn the portion of the trust deposit of a given account. This method can only be called by the permission module when performing an ecosystem-related slash.
Make sure to properly protect access to the execution of this method else it may lead to very destructive actions.
§ [MOD-TD-MSG-7-1] Burn Ecosystem Slashed Trust Deposit method parameters
account
(account) (mandatory): account of the trust deposit we want to burn.amount
(number) (mandatory): value to burn, in denom.
Alternative approach: For security and consistency, implementers MAY choose to reference the ID of the slashed permission, load it and use its defined slashed_deposit
value as the slashing amount.
The decision between this method and specifying the amount directly is left to implementers.
§ [MOD-TD-MSG-7-2] Burn Ecosystem Slashed Trust Deposit precondition checks
If any of these precondition checks fail, transaction MUST abort.
§ [MOD-TD-MSG-7-2-1] Burn Ecosystem Slashed Trust Deposit basic checks
if any of these conditions is not satisfied, transaction MUST abort.
amount
must be > 0.TrustDeposit
entrytd
MUST exist for thisaccount
, andamount
MUST be lower or equal thantd.deposit
.
§ [MOD-TD-MSG-7-2-2] Burn Ecosystem Slashed Trust Deposit fee checks
Account running the transaction MUST have the required estimated transaction fees in its account else transaction MUST abort.
§ [MOD-TD-MSG-7-3] Burn Ecosystem Slashed Trust Deposit execution of the method
Method execution MUST perform the following tasks in a transaction, and rollback if any error occurs.
- define
now
: current timestamp.
For the TrustDeposit
entry td
linked to account
:
- set
td.deposit
totd.deposit
-amount
. - set
td.share
totd.share
-amount
/GlobalVariables.trust_deposit_share_value
- burn
amount
fromTrustDeposit
account.
§ [MOD-TD-QRY-1] Get Trust Deposit
Any account CAN run this query. As this method does not modify data, it does not require a transaction.
§ [MOD-TD-QRY-1-1] Get Trust Deposit query parameters
account
(account) (mandatory): the account for which we want to get the trust deposit value.
§ [MOD-TD-QRY-1-2] Get Trust Deposit query checks
If any of these checks fail, query MUST fail.
account
must be a valid account.
§ [MOD-TD-QRY-1-3] Get Trust Deposit execution of the query
If found, returns trust deposit, else return not found.
§ [MOD-TD-QRY-2] List Module Parameters
Anyone CAN run this query.
§ [MOD-TD-QRY-2-2] List Module Parameters parameters
§ [MOD-TD-QRY-2-2] List Module Parameters query checks
§ [MOD-TD-QRY-2-3] List Module Parameters execution of the query
Return the list of the existing parameters and their values.
§ [MOD-TD-QRY-2-4] List Module Parameters API result example
{
"params": {
"key1": "value1",
"key2": "value2",
...
...
}
}
§ ToIP Trust Registry QueryProtocol version 2.0
This section is non-normative.
Implementations must provide support for ToIP Trust Registry QueryProtocol version 2.0. This will be developed when TRQP spec stabilizes.
§ Initial Data Requirements
§ [GLO] Global Variables
Global variables CAN only be changed by the governance authority through proposals.
Default values MUST be set at VPR initialization (genesis). Below you’ll find some possible values. These values will have to be defined in the governance framework.
Trust Unit:
trust_unit_price
(number) (mandatory): 1.0 denom.
Credential Schema:
credential_schema_trust_deposit
(number) (mandatory): 10 trust units.credential_schema_schema_max_size
(number) (mandatory): 8192.credential_schema_issuer_grantor_validation_validity_period_max_days
(number) (mandatory): 3650.credential_schema_verifier_grantor_validation_validity_period_max_days
(number) (mandatory): 3650.credential_schema_issuer_validation_validity_period_max_days
(number) (mandatory): 3650.credential_schema_verifier_validation_validity_period_max_days
(number) (mandatory): 3650.credential_schema_holder_validation_validity_period_max_days
(number) (mandatory): 3650.
Validation:
validation_term_requested_timeout_days
(number) (mandatory): 7.
Trust Registry:
trust_registry_trust_deposit
(number) (mandatory): 10 trust units.
DID Directory:
did_directory_trust_deposit
(number) (mandatory): 5 trust units.did_directory_grace_period_days
(number) (mandatory): 30.
Trust Deposit:
trust_deposit_reclaim_burn_rate
(number) (mandatory): 0.60.trust_deposit_share_value
(number) (mandatory): 1.trust_deposit_rate
(number) (mandatory): 0.20.wallet_user_agent_reward_rate
(number) (mandatory): 0.10.user_agent_reward_rate
(number) (mandatory): 0.10.
§ References
§ Normative References
- DID-CORE
- Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed; 2022-07-19. Status: REC.
- RFC3986
- Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter; 2005-01. Status: Internet Standard.
- VC-DATA-MODEL
- Verifiable Credentials Data Model v1.1. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel; Kyle Den Hartog; 2022-03-03. Status: REC.