§ Verifiable Public Registry v4 Specification

Latest draft: spec v4-draft11

Latest stable: spec v3

Editors:

Fabrice Rochette (The Verana Foundation)

Contributors:

Ariel Gentile

Mathieu Gauthron

Pratik Kumar

Participate:

GitHub repo

File a bug

Commit history

§ Abstract

Decentralized trust ecosystems need shared infrastructure to answer a fundamental question: who is authorized to issue, verify, or govern credentials in a given context? Without a common registry layer, each ecosystem operates in isolation, trust decisions depend on ad hoc configurations, and there is no interoperable way for Verifiable Services and Verifiable User Agents to resolve the legitimacy of a credential or its issuer.

The Verifiable Public Registry (VPR) is a decentralized “registry of registries” that provides this foundational infrastructure. It allows ecosystems to create and manage their own trust registries, define credential schemas with fine-grained permission policies, and assign roles — issuers, verifiers, grantors — through a transparent, on-chain governance model.

The VPR exposes a standardized query API that Verifiable Services and Verifiable User Agents use during trust resolution to confirm, in real time, whether a given participant is authorized to perform a specific action under a specific credential schema. This is what makes the trust in Verifiable Trust actually verifiable.

The VPR is DID-method-agnostic — it stores registrations, not validations — leaving trust decisions and cryptographic verification where they belong: with the relying parties. It supports flexible permission management modes (open, ecosystem-controlled, or grantor-delegated), enabling ecosystems to tailor governance to their specific requirements.

This specification defines the data model, API, and normative requirements for implementing and interacting with a Verifiable Public Registry.

§ 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.

§ 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 of ecosystem E1?
• can participant #2 request credential presentation of credential issued by issuer DEF from schema GHI of ecosystem E2, for jurisdiction France in context 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.

Permission 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.

authority:

An group which is the owner 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.

denom:

Token that has been configured and is recognized in a VPR, example: uvna, USDC.

native denom:

Native token of a VPR, example: uvna.

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].

ecosystem governance authority:

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.

governance authority:

The governance authority (GA) of a VPR.

grantor:

A role an entity is granted by an ecosystem for operating its trust registry.

group:

A verifiable public registry group.

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 authority, its trust deposit is increased when running validation process (either as an applicant or as a validator).

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:

A fake denom that is not usable as a token (cannot be transferred, or used for paying in transactions). Trust unit is used to define fees in Permissions. Fees defined in trust units are automatically converted to native denom when a transaction is executed, using an exchange rate TU/[[ref: native denom]]. Trust unit is used to compensate native denom fluctuation.

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.

active permission:

A credential schema permission of a given type, which effective_from timestamp is lower than current timestamp, and (effective_until timestamp is null or greater than current timestamp), and revoked is null and slashed is null.

future permission:

A credential schema permission of a given type, which effective_from timestamp is higher than current timestamp, and (effective_until timestamp is null or greater than effective_from timestamp), and revoked 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 authority can create 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 authority (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: ISSUER permissions can be created by anyone.
  • ECOSYSTEM: ISSUER permissions are granted directly by the ecosystem, the trust registry authority
  • GRANTOR_VALIDATION: 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: VERIFIER permissions can be created by anyone.
  • ECOSYSTEM: VERIFIER permissions are granted directly by the ecosystem, the Trust Registry authority
  • GRANTOR_VALIDATION: 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:

Example of a Json Schema credential schema:

{
  "$id": "vpr:verana:mainnet/cs/v1/js/VPR_CREDENTIAL_SCHEMA_ID", // ignored, will be generated
  "$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:

• if schema is OPEN for issuance and/or verification: an entity must have an account in the VPR and self-create its permission.

• if schema is not OPEN for issuance and/or verification: 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:

§ DID Indexing

This section is non-normative.

The Permission registry is a can be used by crawlers to index the metadata associated with verifiable services.

Search engines can iterate over the permissions, 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 index 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.

§ 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:

• 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.

The following operations only require payment of network fees (no trust deposit is involved):

• Trust Registries: requires paying only network fees

• Credential Schemas: requires paying only network fees

• Updating the governance framework documents of an ecosystem trust registry

• Updating a Credential Schema

• Updating a Trust Registry

• …

§ 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:

• (1): if issuer mode is set to GRANTOR_VALIDATION.
• (2): if verifier mode is set to GRANTOR_VALIDATION.
• (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.

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.

§ 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.
• authority (group) (mandatory): group 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.
• aka (string) (optional): optional additional URI of this trust registry.
• language (string) (mandatory): primary language tag (BCP 47) 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 this GovernanceFrameworkVersion 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 the GovernanceFrameworkVersion entry.
• created (timestamp) (mandatory): timestamp this GovernanceFrameworkDocument has been created.
• language (string) (mandatory): primary language tag (BCP 47) 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 this CredentialSchema 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.
• 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 this CredentialSchema. OPEN means anyone can issue credential of this schema; GRANTOR_VALIDATION 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 the CredentialSchema entry in order to create an ISSUER permission;
• verifier_perm_management_mode (PermissionManagementMode) (mandatory): defines how permissions are managed for verifiers of this CredentialSchema. OPEN means anyone can verify credentials of this schema (does not implies that a payment is not necessary); GRANTOR_VALIDATION 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 the CredentialSchema entry in order to create a VERIFIER permission;
• pricing_asset_type (PricingAssetType) (mandatory): used asset for paying business fees. Can be TU (trust unit), COIN (a token available on the VPR chain), FIAT (means chain is used for settlement only and payment is done off-chain). Not that in all cases, trust deposits are always handled in denom.
• pricing_asset (string) (mandatory): "tu" if pricing_asset_type is set to TU, else examples: COIN: denom "uvna", "ufoo", "ibc/3A0F9C2E4E2A9B7D6F...", "factory/verana1.../ueurv", FIAT: "USD", "GBP",…
• digest_algorithm (string) (mandatory): algorithm used to compute the digestSRI for credentials issued under this schema. Valid values are defined in the Verifiable Trust spec.

§ SchemaAuthorizationPolicy

SchemaAuthorizationPolicy:

• id (uint64) (mandatory): unique identifier of this authorization policy.
• schema_id (uint64) (mandatory): id of the CredentialSchema this policy applies to.
• created (timestamp) (mandatory): timestamp when this policy entry was created.
• version (integer) (mandatory): version number of this policy for the given (schema_id, role).
• role (SchemaAuthorizationPolicyRole) (mandatory): role this policy applies to (ISSUER or VERIFIER).
• url (string) (mandatory): URL where the policy document is published.
• digest_sri (string) (mandatory): SRI hash of the policy document, used to guarantee integrity and immutability.
• effective_from (timestamp) (mandatory): timestamp from which this policy version is in force.
• effective_until (timestamp) (optional): timestamp until which this policy version is in force, if time-limited.
• revoked (boolean) (mandatory): indicates whether this policy version has been revoked and must no longer be used.

§ Permission

Permission:

• id (uint64) (mandatory): the id of the perm.
• schema_id (uint64) (mandatory): the id of the related CredentialSchema entry.
• type (PermissionType): ISSUER, VERIFIER, ISSUER_GRANTOR, VERIFIER_GRANTOR, ECOSYSTEM, HOLDER
• did (string) (optional): DID this permission refers to. MUST conform to [RFC3986].
• authority (group) (mandatory): group that owns this permission.
• vs_operator (account) (mandatory): verifiable service agent account. This is the account that will have the right to create or update permission sessions.
• created (timestamp) (mandatory): timestamp this Permission has been created.
• adjusted (timestamp) (mandatory): timestamp this Permission has been adjusted.
• slashed (timestamp) (mandatory): timestamp this Permission has been slashed.
• repaid (timestamp) (mandatory): timestamp this Permission has been repaid.
• effective_from (timestamp) (optional): timestamp from which (inclusive) this Permission is effective.
• effective_until (timestamp) (optional): timestamp until when (exclusive) this Permission 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 (authority grantee of this perm) for running a validation process for a given validation period. Must be an integer. Default to 0. Considered unit depends on pricing_asset_type and pricing_asset configuration of related schema.
• issuance_fees (number) (mandatory): fees requested by grantee authority of this perm when a credential is issued. Must be an integer. Default to 0. Considered unit depends on pricing_asset_type and pricing_asset configuration of related schema.
• verification_fees (number) (mandatory): fees requested by grantee authority of this perm when a credential is verified. Must be an integer. Default to 0. Considered unit depends on pricing_asset_type and pricing_asset configuration of related schema.
• deposit (number) (mandatory): accumulated grantee deposit in the context of the use of this permission (including the validation process), in native denom. Usually, it is incremented when for example, for a ISSUER type Permission 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 this perm.deposit value as well. If perm is, let’s say revoked, then corresponding perm.deposit value is freed from perm.grantee Trust Deposit.
• slashed_deposit (number) (mandatory): part of the deposit in native denom that has been slashed.
• repaid_deposit (number) (mandatory): part of the slashed deposit in native denom that has been repaid.
• revoked (timestamp) (optional): manual revocation timestamp of this Perm.
• validator_perm_id (uint64) (optional): permission of the validator assigned to the validation process of this permission, ie parent node in the Permission tree.
• vp_state (enum) (mandatory): one of PENDING, VALIDATED, TERMINATED.
• vp_exp (timestamp) (optional): validation expiration timestamp. This expiration timestamp is for the validation process itself, not for the issued credential or Permission 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 (string) (optional): an optional digest SRI, set by validator, of a summary of the information, proofs… provided by the applicant.
• issuance_fee_discount: (number) (mandatory): default to 0 (no discount). Maximum 1 (100% discount). Can be set to an ISSUER_GRANTOR, ISSUER permission (if GRANTOR_VALIDATION mode) or an ISSUER permission (ECOSYSTEM mode) to reduce (or void) calculated issuance fees for subtree of permissions. Note: this should generally not be used because it reduces or void commission of all related ecosystem participants.
• verification_fee_discount: (number) (mandatory): default to 0 (no discount). Maximum 1 (100% discount). Can be set to a VERIFIER_GRANTOR, VERIFIER permission (if GRANTOR_VALIDATION mode) and/or a VERIFIER permission (ECOSYSTEM mode) to reduce (or void) calculated fees for subtree of permissions. Note: this should generally not be used because it reduces or void commission of all related ecosystem participants.
• vs_operator_authz_enabled: boolean (mandatory): if set to true, authorize this vs_operator to execute CreateOrUpdatePermissionSession on behalf of authority account (trust fees will be paid by authority account)
• vs_operator_authz_spend_limit (DenomAmount[]) (optional): maximum amount of funds that the vs_operator is allowed to spend in the context of this permission as a direct consequence of executing authorized messages.
• vs_operator_authz_with_feegrant: boolean (mandatory): if set to true, enable feegrant for this permission so vs_operator can pay the fees for CreateOrUpdatePermissionSession with authority account.
• vs_operator_authz_fee_spend_limit (DenomAmount[]) (optional): maximum total amount of fees that can be spent by vs_operator in the context of this permission.
• vs_operator_authz_spend_period: (period) (optional): reset period for vs_operator_authz_spend_limit and vs_operator_authz_fee_spend_limit in the context of this permission.

§ PermissionSession

PermissionSession:

• id (uuid) (mandatory): session uuid.
• authority (group) (mandatory): authority that controls the entry.
• vs_operator (account) (mandatory): verifiable service agent account that controls the entry (agent crypto account).
• agent_perm_id (uint64) (mandatory): permission id of the agent.
• created (timestamp) (mandatory): timestamp this PermissionSession has been created.
• modified (timestamp) (mandatory): timestamp this PermissionSession has been modified.
• session_records (PermissionSessionRecord[]) (mandatory): session records, for this session.

§ PermissionSessionRecord

PermissionSessionRecord:

• created (timestamp) (mandatory): timestamp this record has been created.
• issuer_perm_id (uint64) (optional): related issuer Permission id (if applicable).
• verifier_perm_id (uint64) (optional): related verifier Permission id (if applicable).
• wallet_agent_perm_id (uint64) (optional): related wallet agent Permission id (if applicable).

§ TrustDeposit

TrustDeposit:

• share (number) (mandatory): share of the module total deposit.
• authority (group) (mandatory) (key): the group
• deposit (number) (mandatory): amount of deposit in denom.
• claimable (number) (mandatory): amount of claimable deposit in denom.
• slashed_deposit (number) (optional): amount of slashed deposit in denom.
• repaid_deposit (number) (optional): amount of slashed deposit in denom.
• 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.

§ DenomAmount

• denom (string) (mandatory): token denomination, as explain in denom.
• amount (number) (mandatory): amount expressed in the given denomination.

§ Digest

• digest (string) (mandatory): digest to store.
• created (timestamp) (mandatory): block execution date of when it was persisted.

§ OperatorAuthorization

• authority (group) (mandatory): the authority group granting the authorization.
• operator (account) (mandatory): the operator account receiving the authorization.
• msg_types (msg_type[]) (mandatory): list of module message types this authorization applies to.
• spend_limit (DenomAmount[]) (optional): maximum amount of funds that the grantee is allowed to spend as a direct consequence of executing authorized messages.
• fee_spend_limit (DenomAmount[]) (optional): maximum total amount of fees that can be paid using this authorization.
• expiration (timestamp) (optional): timestamp after which the authorization is no longer valid.
• period (duration) (optional): reset period for spend_limit and fee_spend_limit.

§ FeeGrant

FeeGrant:

• grantor (group) (mandatory): the authority group granting the fee allowance.
• grantee (account) (mandatory): the account that receives the fee grant from grantor.
• msg_types (msg_type[]) (mandatory): list of VPR delegable message types for which the fee allowance applies.
• spend_limit (DenomAmount[]) (optional): maximum amount of fees that can be spent using this grant.
• expiration (timestamp) (optional): timestamp after which the fee grant is no longer valid.
• period (duration) (optional): reset period for spend_limit.

§ VSOperatorAuthorization

• authority (group) (mandatory): the authority group granting the authorization.
• vs_operator (account) (mandatory): the operator account receiving the authorization.
• permissions[] (uint64[]) (mandatory): permission ids for which we grant this authorization.

§ ExchangeRate

Represents an on-chain exchange rate between two assets.

ExchangeRate:

• base_asset_type (PricingAssetType, mandatory): Type of the base asset.
• base_asset (string, mandatory if base_asset_type is COIN or FIAT, null if base_asset_type is TU): Identifier of the base asset.
• quote_asset_type (PricingAssetType, mandatory): Type of the quote asset.
• quote_asset (string, mandatory): Identifier of the quote asset.
• rate (string, mandatory): Fixed-point integer representing the exchange rate from base asset to quote asset.
• rate_scale (uint32, mandatory): Number of decimal digits used to scale rate.
• validity_duration (duration, mandatory): when updated, set expires to block time plus validity_duration.
• updated (timestamp, mandatory): Timestamp of the last exchange rate update.
• expires (timestamp, mandatory): Timestamp after which the exchange rate is considered invalid.
• state (boolean, mandatory): true means enabled, false means disabled.

§ GlobalVariables

GlobalVariables:

Credential Schema:

• credential_schema_schema_max_size (number) (mandatory): maximum size of the schema string attribute for a CredentialSchema.
• 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.

Trust Deposit:

• trust_deposit_share_value(number) (mandatory): Value of one share of trust deposit, in native denom. 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)
• trust_deposit_max_yield_rate(number) (mandatory): Maximum yearly yield, in percent, that a trust deposit holder can obtain by receiving block rewards.
• trust_deposit_block_reward_share(number) (mandatory): Percentage of block reward that must be distributed to trust deposit holders. 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 of TrustRegistry entries.

Examples:

Get a TrustRegistry

"trust_registry": {
  {
    "active_version": 0,
    "aka": "string",
    "authority": "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",
    "authority": "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",
    "authority": "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"
          }
        ],
      }
    ]  
  }
]

A VPR implementation MUST implement all the following requirements.

§ Authorization and Fee Grants

§ Delegable Module Messages

Most VPR module messages (Msg) support delegation and follow the pattern described below.

Delegable messages are defined as messages that can be executed by an operator account on behalf of an authority group, provided that the appropriate authorization has been granted.

Such messages conceptually involve two roles:

• authority (group):
  The group that owns the created or manipulated resource.
  The authority is represented in the Msg through an authorization granted to an operator account.

• operator (account):
  The account that executes the Msg on behalf of the authority.
  The operator MUST be explicitly authorized for the given message type.

When a delegable message is executed directly by an operator account, both roles are authenticated and enforced by the authorization system.

Using this model makes it possible to:

• identify, within the Msg, both the authenticated authority and the executing operator,
• allow network fees to be paid either by the operator account or by the authority account via a fee grant.

For the execution of delegable messages:

• the operator account MUST have a valid authorization from the authority group for the specific message type being executed.

An authority group is not required to delegate all message types to the same operator.
It is entirely up to the authority group to decide which accounts may execute which messages.

• Authorizations MUST be granted to individual accounts through group proposals.
• Authorizations MAY include an optional spend_limit and an optional expiration date.

§ Not Delegable Module Messages

Some module messages specify only an authority:

• authority (group):
  The group that owns the manipulated resource.

Such messages cannot be delegated and MUST be executed exclusively through a group proposal.

§ Governance-Signed Module Messages

Some module messages can be executed only through a governance proposal.

These messages do not support delegation and are not executable by accounts, whether directly or via group authorization.

§ Fee Grants

An authority group MAY allow its operators to pay network transaction fees using the authority’s funds.

Fee grants are not created directly.
They are created, updated, and revoked exclusively by Authorization module messages.
When an authorization is created or updated, it MAY optionally include an associated fee grant.

§ [AUTHZ-CHECK] Common Authorization and Fee Grant Precondition Checks

For any delegable message executed by an operator on behalf of an authority, the following precondition checks MUST be performed before any method-specific checks. If any check fails, the transaction MUST abort.

§ [AUTHZ-CHECK-1] Operator Authorization checks

1. An OperatorAuthorization oauthz MUST exist where oauthz.authority = authority, oauthz.operator = operator, and oauthz.msg_types includes the current message type.
2. If oauthz.expiration is set, it MUST be in the future.
3. If oauthz.spend_limit is set, the remaining balance MUST be sufficient for the operation. After successful execution, the consumed amount MUST be deducted from the remaining balance.
4. If oauthz.period is set and the current period has elapsed since the last reset, the remaining balance MUST be reset to oauthz.spend_limit before evaluating the check above.

§ [AUTHZ-CHECK-2] Fee Grant checks

If the transaction fees are paid by the authority account (via fee grant) instead of the operator account:

1. A FeeGrant fg MUST exist where fg.grantor = authority, fg.grantee = operator, and fg.msg_types includes the current message type.
2. If fg.expiration is set, it MUST be in the future.
3. If fg.spend_limit is set, the remaining balance MUST be sufficient for the estimated transaction fees. After successful execution, the consumed fee amount MUST be deducted from the remaining balance.
4. If fg.period is set and the current period has elapsed since the last reset, the remaining balance MUST be reset to fg.spend_limit before evaluating the check above.

§ [AUTHZ-CHECK-3] VS Operator Authorization checks

For CreateOrUpdatePermissionSession, the authorization model differs from other delegable messages: it relies on VSOperatorAuthorization and per-permission settings instead of OperatorAuthorization.

Given an authority, an operator (the vs_operator), and a primary permission perm (determined by the calling method):

1. A VSOperatorAuthorization vso MUST exist where vso.authority = authority and vso.vs_operator = operator.
2. vso.permissions MUST include perm.id.
3. perm.vs_operator_authz_enabled MUST be true.
4. If perm.vs_operator_authz_spend_period is set and the current period has elapsed since the last reset, the remaining balances for perm.vs_operator_authz_spend_limit and perm.vs_operator_authz_fee_spend_limit MUST be reset to their original values before evaluating the checks below.
5. If perm.vs_operator_authz_spend_limit is set, the remaining balance MUST be sufficient for the operation. After successful execution, the consumed amount MUST be deducted from the remaining balance.

§ [AUTHZ-CHECK-4] VS Operator Fee Grant checks

If the transaction fees are paid by the authority account (via fee grant) instead of the operator account, using the same primary permission perm:

1. perm.vs_operator_authz_with_feegrant MUST be true, else abort.
2. If perm.vs_operator_authz_spend_period is set and the current period has elapsed since the last reset, the remaining balance for perm.vs_operator_authz_fee_spend_limit MUST be reset to its original value before evaluating the check below.
3. If perm.vs_operator_authz_fee_spend_limit is set, the remaining balance MUST be sufficient for the estimated transaction fees. After successful execution, the consumed fee amount MUST be deducted from the remaining balance.

§ Example

An authority group authorityABC wants to authorize an operator account accountABC to execute the
mod-perm-msg-10-create-or-update-permission-session message.

Additionally, the authority wants accountABC to pay the transaction fees for this message using the authority’s funds.

To achieve this, authorityABC MUST:

• create an authorization from authorityABC to accountABC for the
  mod-perm-msg-10-create-or-update-permission-session message type,
  optionally enabling an associated fee grant.

As a result, accountABC is authorized to:

• execute the specified message type on behalf of authorityABC, including any state changes and fund movements that are a direct consequence of that message, and
• pay the network transaction fees for that message using the funds of authorityABC, via the associated fee grant.

§ Method List

§ Trust Registry Module

§ [MOD-TR-MSG-1] Create New Trust Registry

Any authorized operator CAN execute this method on behalf of an authority.

§ [MOD-TR-MSG-1-1] Create New Trust Registry parameters

An authorized operator that would like to create a trust registry MUST call this method by specifying:

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• did (string) (mandatory): the did of the ecosystem that is creating the trust registry.
• aka (string) (optional): optional additional URI of this trust registry.
• language (string) (mandatory): primary language tag (BCP 47) 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.

• authority (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.

• 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 (BCP 47).

• 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-1-2-2] Create New Trust Registry fee checks

Fee payer MUST have an available balance to cover the estimated transaction fees.

§ [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.

• create and persist a new TrustRegistry entry tr:

• tr.id : auto-incremented uint64

• tr.did: did

• tr.authority: authority

• tr.created: current timestamp

• tr.modified: tr.created

• tr.aka: aka

• tr.language: language

• tr.active_version: 1

• create and persist a new GovernanceFrameworkVersion entry gfv:

• 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 entry gfd:

• 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 authorized operator CAN execute this method on behalf of an authority.

§ [MOD-TR-MSG-2-1] Add Governance Framework Document parameters

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• id (uint64) (mandatory): the id of the trust registry.
• doc_language (string) (mandatory): language tag (BCP 47) 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 will replace the corresponding entry. Else, a new entry is created. It is only possible to edit future versions. Active version cannot be modified.

§ [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.

• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• id (uint64) (mandatory): a TrustRegistry entry with this id MUST exist and authority executing the method MUST be the authority of the TrustRegistry entry.
• version: there MUST exist a GovernanceFrameworkVersion entry gfv where gfv.tr_id is equal to id and gfv.version = version, or version MUST be exactly equal to the biggest found gfv.version + 1 of all GovernanceFrameworkVersion entries found for this gfv.tr_id equal to id. version MUST be greater than the tr.active_version.
• doc_language (string) (mandatory): MUST be a language tag (BCP 47).
• 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

Fee payer 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: version

• gfv.active_since: null

• create and persist or (replace if already exist) a GovernanceFrameworkDocument entry gfd:

• 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 authorized operator CAN execute this method on behalf of an authority.

§ [MOD-TR-MSG-3-1] Increase Active Governance Framework Version parameters

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• 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.

• authority (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.

• id (uint64) (mandatory): a TrustRegistry entry with this id MUST exist and authority executing the method MUST be the authority of the TrustRegistry entry.

• load TrustRegistry entry tr from its id. Find a GovernanceFrameworkVersion entry gfv where version is equal to tr.active_version + 1. If none is found, transaction MUST abort.

• find GovernanceFrameworkDocument gfd for gfd.gfv_id = gfv.id and gfd.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

Fee payer 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 entry tr from its id. Find a GovernanceFrameworkVersion entry gfv where version is equal to tr.active_version + 1. If none is found, transaction MUST abort. Else, update tr.active_version to tr.active_version + 1. Set tr.modified to current timestamp, and set gfv.active_since to current timestamp and persist changes.

§ [MOD-TR-MSG-4] Update Trust Registry

Any authorized operator CAN execute this method on behalf of an authority.

§ [MOD-TR-MSG-4-1] Update Trust Registry parameters

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• 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.

• authority (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.

• id (uint64) (mandatory): a TrustRegistry entry tr with id id MUST exist and authority executing the method MUST be the authority of the TrustRegistry entry tr.

• 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

Fee payer must have 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 entry tr from id and set:

• tr.did: did

• tr.aka: aka

• tr.modified: current timestamp

§ [MOD-TR-MSG-5] Archive Trust Registry

Any authorized operator CAN execute this method on behalf of an authority.

§ [MOD-TR-MSG-5-1] Archive Trust Registry parameters

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• 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.

• authority (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.

• load TrustRegistry tr from id. tr.authority MUST be the authority executing the method, else MUST abort.

• archive (boolean) (mandatory) MUST be a boolean.

  • If archive is true and tr.archived is not null, MUST abort as TrustRegistry is already archived.
  • If archive is false and tr.archived is null, MUST abort as TrustRegistry is already not archived.

§ [MOD-TR-MSG-5-2-2] Archive Trust Registry fee checks

Fee payer 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 entry tr with tr.id equal to id:
• if archived is true: set tr.archived to current timestamp.
• if archived is false: set tr.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 of params MUST be greater than 0. For each param <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 active_gf_only is true, return only nested GovernanceFrameworkVersion and GovernanceFrameworkDocument entries for the active version.

§ [MOD-TR-QRY-2] List Trust Registries

§ [MOD-TR-QRY-2-1] List Trust Registries query parameters

The following parameters are optional:

• authority (group) (optional): if specified, filter by authority.
• modified_after (timestamp) (optional): if specified, returns only TrustRegistry entries with TrustRegistry.modified greater than modified.
• 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 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 authorized operator CAN execute this method on behalf of an authority.

§ [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:

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• 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).
• pricing_asset_type (PricingAssetType) (mandatory).
• pricing_asset (string) (mandatory).
• digest_algorithm (string) (mandatory): valid values are defined in the Verifiable Trust spec.

§ [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.

• authority (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.

• tr_id MUST represent an existing TrustRegistry entry tr and tr.authority MUST be the authority executing the method.

• json_schema MUST be a valid Json Schema, and size must not be greater than GlobalVariables.credential_schema_schema_max_size. $id of the Json Schema is ignored and will be replaced during execution by the auto-generated id of this CredentialSchema.

• issuer_grantor_validation_validity_period must be between 0 (never expire) and GlobalVariables.credential_schema_issuer_grantor_validation_validity_period_max_days days.

• verifier_grantor_validation_validity_period must be between 0 (never expire) and GlobalVariables.credential_schema_verifier_grantor_validation_validity_period_max_days days.

• issuer_validation_validity_period must be between 0 (never expire) and GlobalVariables.credential_schema_issuer_validation_validity_period_max_days days.

• verifier_validation_validity_period must be between 0 (never expire) and GlobalVariables.credential_schema_verifier_validation_validity_period_max_days days.

• holder_validation_validity_period must be between 0 (never expire) and GlobalVariables.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.

• digest_algorithm (string) (mandatory) MUST be a valid digest algorithm as defined in the Verifiable Trust spec.

• pricing_asset_type (PricingAssetType) (mandatory): used asset for paying business fees. Can be TU (Trust Unit), COIN (a token available on the VPR chain), FIAT (means chain is used for settlement only and payment is done off-chain). Not that in all cases, trust deposits are always handled in denom.

• pricing_asset (string) (mandatory): "tu" if pricing_asset_type is set to TU, else examples: COIN: denom "uvna", "ufoo", "ibc/3A0F9C2E4E2A9B7D6F...", "factory/verana1.../ueurv", FIAT: "EUR", "GBP",…

§ [MOD-CS-MSG-1-2-2] Create New Credential Schema fee checks

Fee payer MUST have an available balance in its account, to cover the required estimated transaction fees.

§ [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.

• create and persist a new CredentialSchema entry cs:

  • cs.id: auto-incremented uint64.
  • cs.tr_id: id of the TrustRegistry entry that will be the owner of cs.
  • cs.json_schema: json_schema, with VPR_CREDENTIAL_SCHEMA_ID string replaced by generated cs.id, and then canonicalize it using the JSON Canonicalization Scheme (JCS) as defined in RFC 8785. Schema MUST be saved canonized.
  • 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 timestamp
  • cs.modified: cs.created.
  • cs.pricing_asset_type: pricing_asset_type
  • cs.pricing_asset: pricing_asset
  • cs.digest_algorithm: digest_algorithm

§ [MOD-CS-MSG-2] Update Credential Schema

Any authorized operator CAN execute this method on behalf of an authority.

§ [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:

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• 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.

• authority (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.

• id MUST represent an existing CredentialSchema entry cs.

• load TrustRegistry tr from cs.tr_id. tr.authority MUST be the authority executing the method, else MUST abort.

• issuer_grantor_validation_validity_period MUST be between 0 (never expire) and GlobalVariables.credential_schema_issuer_grantor_validation_validity_period_max_days days.

• verifier_grantor_validation_validity_period MUST be between 0 (never expire) and GlobalVariables.credential_schema_verifier_grantor_validation_validity_period_max_days days.

• issuer_validation_validity_period MUST be between 0 (never expire) and GlobalVariables.credential_schema_issuer_validation_validity_period_max_days days.

• verifier_validation_validity_period MUST be between 0 (never expire) and GlobalVariables.credential_schema_verifier_validation_validity_period_max_days days.

• holder_validation_validity_period MUST be between 0 (never expire) and GlobalVariables.credential_schema_holder_validation_validity_period_max_days days.

§ [MOD-CS-MSG-2-2-2] Update Credential Schema fee checks

Fee payer 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 entry cs with cs.id equal to 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.modified: current timestamp.

§ [MOD-CS-MSG-3] Archive Credential Schema

Any authorized operator CAN execute this method on behalf of an authority.

§ [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:

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• 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.

• authority (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.

• id MUST represent an existing CredentialSchema entry cs.

• load TrustRegistry tr from cs.tr_id. tr.authority MUST be the authority executing the method, else MUST abort.

• archive (boolean) (mandatory) MUST be a boolean.

  • If archive is true and cs.archived is not null, MUST abort as Credential Schema is already archived.
  • If archive is false and cs.archived is null, MUST abort as Credential Schema is already not archived.

§ [MOD-CS-MSG-3-2-2] Archive Credential Schema fee checks

Fee payer 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 entry cs with cs.id equal to id:

• if archived is true: set cs.archived to current timestamp.

• if archived is false: set cs.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 of params MUST be greater than 0. For each param <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-MSG-5] Create Schema Authorization Policy

Any authorized operator CAN execute this method on behalf of an authority.

This message creates a draft SchemaAuthorizationPolicy for a given (schema_id, role), or overwrites the existing draft policy if one already exists.
A draft policy is defined as a policy with effective_from == null and MUST NOT be revoked.

Accordingly, if a credential schema defines one or more active policies for the ISSUER or VERIFIER role, the corresponding authority that grants the ISSUER or VERIFIER role for this schema (ISSUER_GRANTOR, VERIFIER_GRANTOR, or ECOSYSTEM, depending on how schema issuer and verifier modes have been configured) MUST issue an IAC or VAC credential to the candidate upon successful completion of the validation process. Refer to the Verifiable Trust spec for more information.

§ [MOD-CS-MSG-5-1] Create Schema Authorization Policy parameters

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• schema_id (uint64): id of the related CredentialSchema (mandatory).
• role (SchemaAuthorizationPolicyRole): ISSUER or VERIFIER (mandatory).
• url (string): URL where the policy document is published (mandatory).
• digest_sri (string): SRI digest of the policy document (mandatory).

§ [MOD-CS-MSG-5-2] Create Schema Authorization Policy precondition checks

If any of these precondition checks fail, method MUST abort.

§ [MOD-CS-MSG-5-2-1] Create Schema Authorization Policy basic checks

• if a mandatory parameter is not present, method MUST abort.
• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• schema_id MUST reference an existing CredentialSchema entry controlled by authority.
• role MUST be a valid SchemaAuthorizationPolicyRole.
• url MUST be a non-empty valid URI.
• digest_sri MUST be non-empty.
• there MUST NOT exist more than one policy for (schema_id, role) with effective_from == null and revoked == false.

§ [MOD-CS-MSG-5-2-2] Create Schema Authorization Policy fee checks

Fee payer MUST have an available balance in its account to cover the required estimated transaction fees.

§ [MOD-CS-MSG-5-3] Create Schema Authorization Policy 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:

• if a draft policy exists for (schema_id, role):
  • update the existing policy by setting:
    • url = url
    • digest_sri = digest_sri
• otherwise, create and persist a new SchemaAuthorizationPolicy entry sap:
  • sap.id: auto-incremented uint64
  • sap.schema_id: schema_id
  • sap.role: role
  • sap.version: max existing version for (schema_id, role) + 1, or 1 if none exist
  • sap.url: url
  • sap.digest_sri: digest_sri
  • sap.created: current timestamp
  • sap.effective_from: null
  • sap.effective_until: null
  • sap.revoked: false

§ [MOD-CS-MSG-6] Increase Active Schema Authorization Policy Version

Any authorized operator CAN execute this method on behalf of an authority.

This message activates the current draft SchemaAuthorizationPolicy for the given (schema_id, role) and deactivates any previously active version. Deactivation does not constitute revocation; credentials issued under earlier policies MAY continue to be considered valid.

§ [MOD-CS-MSG-6-1] Increase Active Schema Authorization Policy Version parameters

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• schema_id (uint64): id of the related CredentialSchema (mandatory).
• role (SchemaAuthorizationPolicyRole): ISSUER or VERIFIER (mandatory).

§ [MOD-CS-MSG-6-2] Increase Active Schema Authorization Policy Version precondition checks

If any of these precondition checks fail, method MUST abort.

§ [MOD-CS-MSG-6-2-1] Basic checks

• if a mandatory parameter is not present, method MUST abort.
• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• schema_id MUST reference an existing CredentialSchema entry controlled by authority.
• exactly one draft policy MUST exist for (schema_id, role) with effective_from == null and revoked == false.
• the draft policy MUST have non-empty url and digest_sri.

§ [MOD-CS-MSG-6-2-2] Fee checks

Fee payer MUST have an available balance in its account to cover the required estimated transaction fees.

§ [MOD-CS-MSG-6-3] Increase Active Schema Authorization Policy Version execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following tasks atomically in a transaction:

• let draft be the unique policy with effective_from == null and revoked == false.
• let prev_active be the active policy for (schema_id, role), if any.
• set draft.effective_from = now.
• if prev_active exists:
  • set prev_active.effective_until = now.

§ [MOD-CS-MSG-7] Revoke Schema Authorization Policy

Any authorized operator CAN execute this method on behalf of an authority.

This message revokes a previously enabled SchemaAuthorizationPolicy version. Revoked means previously issued credential that refer to this policy are automatically considered revoked.

§ [MOD-CS-MSG-7-1] Revoke Schema Authorization Policy parameters

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• schema_id (uint64): id of the related CredentialSchema (mandatory).
• role (SchemaAuthorizationPolicyRole): ISSUER or VERIFIER (mandatory).
• version (integer): policy version to revoke (mandatory).

§ [MOD-CS-MSG-7-2] Revoke Schema Authorization Policy precondition checks

If any of these precondition checks fail, method MUST abort.

§ [MOD-CS-MSG-7-2-1] Basic checks

• if a mandatory parameter is not present, method MUST abort.
• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• a policy MUST exist for (schema_id, role, version).
• the targeted policy MUST have effective_from != null (a policy that has never been enabled MUST NOT be revoked).
• the targeted policy MUST NOT already be revoked.

§ [MOD-CS-MSG-7-2-2] Fee checks

Fee payer MUST have an available balance in its account to cover the required estimated transaction fees.

§ [MOD-CS-MSG-7-3] Revoke Schema Authorization Policy execution

If all precondition checks passed, method is executed.

Method execution MUST perform the following task in a transaction:

• set revoked = true on the targeted SchemaAuthorizationPolicy entry.

§ [MOD-CS-QRY-1] List Credential Schemas

§ [MOD-CS-QRY-1-1] List Credential Schemas parameters

• tr_id (uint64) (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.
• only_active (boolean): if set to true, returns only not archived entries.
• issuer_perm_management_mode (PermissionManagementMode): if set, filter by issuer_perm_management_mode.
• verifier_perm_management_mode (PermissionManagementMode): if set, filter by verifier_perm_management_mode.

§ [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 DESC.

§ [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”.

Schema MUST be rendered cononized, even if it was not created canonized using the JSON Canonicalization Scheme (JCS) as defined in RFC 8785.

§ [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",
    ...
    ...
  }
}

§ [MOD-CS-QRY-5] Get Schema Authorization Policy

This query returns a single SchemaAuthorizationPolicy identified by its unique id.

§ [MOD-CS-QRY-5-1] Get Schema Authorization Policy parameters

• id (uint64): unique identifier of the SchemaAuthorizationPolicy (mandatory).

§ [MOD-CS-QRY-5-2] Get Schema Authorization Policy precondition checks

If any of these precondition checks fail, query MUST abort.

• id MUST be provided.
• a SchemaAuthorizationPolicy entry with the given id MUST exist.

§ [MOD-CS-QRY-5-3] Get Schema Authorization Policy execution

If all precondition checks pass, the query MUST return the corresponding SchemaAuthorizationPolicy entry:

• id
• schema_id
• role
• version
• url
• digest_sri
• created
• effective_from
• effective_until
• revoked

§ [MOD-CS-QRY-6] List Schema Authorization Policies

This query returns the list of SchemaAuthorizationPolicy entries associated with a given (schema_id, role) pair.

§ [MOD-CS-QRY-6-1] List Schema Authorization Policies parameters

• schema_id (uint64): id of the related CredentialSchema (mandatory).
• role (SchemaAuthorizationPolicyRole): ISSUER or VERIFIER (mandatory).

§ [MOD-CS-QRY-6-2] List Schema Authorization Policies precondition checks

If any of these precondition checks fail, query MUST abort.

• schema_id MUST be provided.
• role MUST be a valid SchemaAuthorizationPolicyRole.
• schema_id MUST reference an existing CredentialSchema entry.

§ [MOD-CS-QRY-6-3] List Schema Authorization Policies execution

If all precondition checks pass, the query MUST return the list of SchemaAuthorizationPolicy entries matching (schema_id, role).

Returned entries MUST include at least the following fields:

• id
• schema_id
• role
• version
• url
• digest_sri
• created
• effective_from
• effective_until
• revoked

Entries MUST be ordered by ascending version.

§ 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 (or by any account: - for ISSUER permissions if issuer_perm_management_mode is equal to OPEN, - for VERIFIER permissions if verifier_perm_management_mode is equal to OPEN).

A Validation Process (VP) is a process which involves an applicant (which is the authority of validation entry stored in a validation keeper), a validator permission, and optional validation 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:

1. 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.
2. 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.
3. 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.

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].

§ [MOD-PERM-MSG-1] Start Permission VP

Any authorized operator CAN execute this method on behalf of an authority.

§ [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:

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• vs_operator (account) (optional): the account of the Veriable Service we want to authorize to create permission sessions linked to this permission. If not specified, Verifiable Service will not be able to use the payment delegation feature. Required to use the payment delegation feature.
• type (PermissionType) (mandatory): (ISSUER_GRANTOR, VERIFIER_GRANTOR, ISSUER, VERIFIER, HOLDER): the permission that the applicant would like to get;
• validator_perm_id (uint64) (mandatory): the validator permission (parent permission in the tree), chosen by the applicant.
• validation_fees (number) (optional): Requested validation_fees for this permission (can be modified by validator).
• issuance_fees (number) (optional): Requested issuance_fees for this permission (can be modified by validator).
• verification_fees (number) (optional): Requested verification_fees for this permission (can be modified by validator).
• did (string) (required): MUST conform to the DID Syntax, as specified [DID-CORE].
• vs_operator_authz_enabled: boolean (mandatory): if set to true authorize this vs_operator to execute CreateOrUpdatePermissionSession on behalf of authority account (trust fees will be paid by authority account)
• vs_operator_authz_spend_limit (DenomAmount[]) (optional): maximum amount of funds that the vs_operator is allowed to spend in the context of this permission. as a direct consequence of executing authorized messages.
• vs_operator_authz_with_feegrant: boolean (mandatory): if set to true, enable feegrant for this permission so vs_operator can pay the fees for CreateOrUpdatePermissionSession with authority account.
• vs_operator_authz_fee_spend_limit (DenomAmount[]) (optional): maximum total amount of fees that can be spent by vs_operator in the context of this permission.
• vs_operator_authz_spend_period: (period) (optional): reset period for vs_operator_authz_spend_limit and vs_operator_authz_fee_spend_limit in the context of this permission.

Available compatible perms can be found by using an indexer 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.

• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• 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.
• validation_fees (number) (optional): Requested validation_fees for this permission (can be modified by validator).
• issuance_fees (number) (optional): Requested issuance_fees for this permission (can be modified by validator).
• verification_fees (number) (optional): Requested verification_fees for this permission (can be modified by validator).
• did, if specified, MUST conform to the DID Syntax, as specified [DID-CORE].
• vs_operator_authz_enabled: boolean (mandatory): if set to true, vs_operator MUST NOT be null, else abort.
• vs_operator_authz_spend_limit (DenomAmount[]) (optional): maximum amount of funds that the vs_operator is allowed to spend in the context of this permission. as a direct consequence of executing authorized messages.
• vs_operator_authz_with_feegrant: boolean (mandatory): if set to true, vs_operator MUST NOT be null, else abort.
• vs_operator_authz_fee_spend_limit (DenomAmount[]) (optional): maximum total amount of fees that can be spent by vs_operator in the context of this permission.
• vs_operator_authz_spend_period: (period) (optional): if not null, vs_operator MUST NOT be null, else abort. Reset period for vs_operator_authz_spend_limit and vs_operator_authz_fee_spend_limit in the context of this permission.

§ [MOD-PERM-MSG-1-2-2] Start Permission VP permission checks

• Load Permission entry validator_perm from validator_perm_id. It MUST be a active permission else transaction MUST abort.

• Load CredentialSchema entry cs from validator_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 active 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 from validator_perm_id.

• Load CredentialSchema entry cs from validator_perm.schema_id.

• Fee payer MUST have an available balance in its account, to cover the estimated transaction fees;

If a conversion is needed below, use Get Price to convert amounts to native denom:

• For trust fees:

if (cs.pricing_asset_type, cs.pricing_asset) is set to (COIN, [[ref: native denom]]):

• authority MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = validator_perm.validation_fees in native denom.
  • the required validation_trust_deposit_in_native_denom: validation_fees_in_denom * GlobalVariables.trust_deposit_rate in native denom.

else if (cs.pricing_asset_type, cs.pricing_asset) is set to (TU, "tu"):

• authority MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = getPrice(cs.pricing_asset_type, cs.pricing_asset, COIN, [[ref: native denom]], validator_perm.validation_fees) in native denom;
  • the required validation_trust_deposit_in_native_denom: validation_fees_in_denom * GlobalVariables.trust_deposit_rate in native denom.

else if (cs.pricing_asset_type, cs.pricing_asset) is set to an arbitrary coin (COIN, [[ref: denom]]):

• authority MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = validator_perm.validation_fees in specified (cs.pricing_asset_type, cs.pricing_asset)
  • the required validation_trust_deposit_in_native_denom: getPrice(cs.pricing_asset_type, cs.pricing_asset, COIN, [[ref: native denom]], validation_fees_in_denom) * GlobalVariables.trust_deposit_rate in native denom.

else if (cs.pricing_asset_type, cs.pricing_asset) is set to an arbitrary coin (FIAT, [[ref: denom]]):

• authority MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = 0 in native denom.
  • the required validation_trust_deposit_in_native_denom: getPrice(cs.pricing_asset_type, cs.pricing_asset, COIN, [[ref: native denom]], validator_perm.validation_fees) * GlobalVariables.trust_deposit_rate in native denom.

§ [MOD-PERM-MSG-1-2-4] Start Permission VP overlap checks

We want to make sure that 2 validation processes cannot be active at the same time in the same context. This does not prevent an authority from running different VP with differents validators for the same schema_id, type.

Find all permission perms[] for schema_id, type, validator_perm_id, authority with vp_state = VALIDATED or PENDING.

if size of perms[] > 0, it means there is already an existing validation process in this context, so MUST abort.

note: this check was not present in v3.

§ [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 entry validator_perm of the selected validator.

• calculate validation_fees_in_denom and validation_trust_deposit_in_native_denom as explained above in fee checks.

• use [MOD-TD-MSG-1] to increase by validation_trust_deposit_in_native_denom the trust deposit of authority running the method and transfer the corresponding amount to TrustDeposit 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.schema_id = validator_perm.schema_id
  • applicant_perm.authority: authority.
  • applicant_perm.vs_operator: vs_operator.
  • applicant_perm.type: type.
  • applicant_perm.created: now
  • applicant_perm.modified: now
  • applicant_perm.deposit: validation_trust_deposit_in_native_denom.
  • applicant_perm.validation_fees: validation_fees.
  • applicant_perm.issuance_fees: issuance_fees.
  • applicant_perm.verification_fees: verification_fees.
  • 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_native_denom.
  • applicant_perm.vp_summary_digest: null.
  • applicant_perm.vp_validator_deposit: 0.
  • applicant_perm.vs_operator_authz_enabled: vs_operator_authz_enabled
  • applicant_perm.vs_operator_authz_spend_limit: vs_operator_authz_spend_limit
  • applicant_perm.vs_operator_authz_with_feegrant: vs_operator_authz_with_feegrant
  • applicant_perm.vs_operator_authz_fee_spend_limit: vs_operator_authz_fee_spend_limit
  • applicant_perm.vs_operator_authz_spend_period: vs_operator_authz_spend_period

§ 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.

Upon connecting to the VS, the applicant should be required by the validator to complete one or more of the following tasks:

1. Prove control over the vs_operator account specifid in the permission (e.g., via blind signature or cryptographic challenge).
2. Provide requested information, such as filling out forms, submitting documents, or other forms of disclosure as required by the validation VS.
3. 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
• 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.

§ [MOD-PERM-MSG-2] Renew Permission VP

Any authorized operator CAN execute this method on behalf of an authority.

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.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

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• 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.

• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• 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 entry applicant_perm. authority running the operation MUST be applicant_perm.authority, else MUST abort. applicant_perm MUST be a active permission.
• Load Permission entry validator_perm from applicant_perm.validator_perm_id. It MUST exist, and be a active permission, else MUST abort.

§ [MOD-PERM-MSG-2-2-3] Renew Permission VP fee checks

• Load Permission entry validator_perm from applicant_perm.validator_perm_id.

• Load CredentialSchema entry cs from validator_perm.schema_id.

• Fee payer MUST have an available balance in its account, to cover the estimated transaction fees;

If a conversion is needed below, use Get Price to convert amounts to native denom:

• For trust fees:

if (cs.pricing_asset_type, cs.pricing_asset) is set to (COIN, [[ref: native denom]]):

• authority MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = validator_perm.validation_fees in native denom.
  • the required validation_trust_deposit_in_native_denom: validation_fees_in_denom * GlobalVariables.trust_deposit_rate in native denom.

else if (cs.pricing_asset_type, cs.pricing_asset) is set to (TU, "tu"):

• authority MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = getPrice(cs.pricing_asset_type, cs.pricing_asset, COIN, [[ref: native denom]], validator_perm.validation_fees) in native denom;
  • the required validation_trust_deposit_in_native_denom: validation_fees_in_denom * GlobalVariables.trust_deposit_rate in native denom.

else if (cs.pricing_asset_type, cs.pricing_asset) is set to an arbitrary coin (COIN, [[ref: denom]]):

• authority MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = validator_perm.validation_fees in specified (cs.pricing_asset_type, cs.pricing_asset)
  • the required validation_trust_deposit_in_native_denom: getPrice(cs.pricing_asset_type, cs.pricing_asset, COIN, [[ref: native denom]], validation_fees_in_denom) * GlobalVariables.trust_deposit_rate in native denom.

else if (cs.pricing_asset_type, cs.pricing_asset) is set to an arbitrary coin (FIAT, [[ref: denom]]):

• authority MUST have an available balance in its account, to cover the following trust fees.
  • the required validation_fees_in_denom = 0 in native denom.
  • the required validation_trust_deposit_in_native_denom: getPrice(cs.pricing_asset_type, cs.pricing_asset, COIN, [[ref: native denom]], validator_perm.validation_fees) * GlobalVariables.trust_deposit_rate in native denom.

§ [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 entry applicant_perm.

• Load Permission entry validator_perm from applicant_perm.validator_perm_id.

• calculate validation_fees_in_denom and validation_trust_deposit_in_native_denom as explained above in fee checks.

• use [MOD-TD-MSG-1] to increase by validation_trust_deposit_in_native_denom the trust deposit of authority running the method and transfer the corresponding amount to TrustDeposit 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.deposit + validation_trust_deposit_in_native_denom.
  • applicant_perm.vp_current_fees (number): validation_fees_in_denom.
  • applicant_perm.vp_current_deposit (number): validation_trust_deposit_in_native_denom.
  • applicant_perm.modified: now

§ [MOD-PERM-MSG-3] Set Permission VP to Validated

Any authorized operator CAN execute this method on behalf of an authority.

§ [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:

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• id (uint64) (mandatory): id of the validation process;
• effective_until (timestamp) (optional): timestamp until when (exclusive) this Permission 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) (mandatory): Agreed validation_fees for this permission. Can be set only the first time this method is called (cannot be set for renewals). Use 0 for no fees.
• issuance_fees (number) (mandatory): Agreed issuance_fees for this permission. Can be set only the first time this method is called (cannot be set for renewals). Use 0 for no fees.
• verification_fees (number) (mandatory): Agreed verification_fees for this permission. Can be set only the first time this method is called (cannot be set for renewals). Use 0 for no fees.
• vp_summary_digest (string) (optional): an optional digest, set by validator, of a summary of the information, proofs… provided by the applicant.
• issuance_fee_discount: (number) (mandatory): use 0 for no discount. Maximum 1 (100% discount). Can be set to an ISSUER_GRANTOR, ISSUER permission (if GRANTOR_VALIDATION mode) or an ISSUER permission (ECOSYSTEM mode) to reduce (or void) calculated issuance fees for subtree of permissions. Note: this should generally not be used because it reduces or void commission of all related ecosystem participants.
• verification_fee_discount: (number) (mandatory): use 0 for no discount. Maximum 1 (100% discount). Can be set to a VERIFIER_GRANTOR, VERIFIER permission (if GRANTOR_VALIDATION mode) and/or a VERIFIER permission (ECOSYSTEM mode) to reduce (or void) calculated fees for subtree of permissions. Note: this should generally not be used because it reduces or void commission of all related ecosystem participants.

§ [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.

• authority (group): (Signer) signature must be verified.

• operator (account): (Signer) signature must be verified.

• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.

• id MUST be a valid uint64.

• Load Permission entry applicant_perm from id. If no entry found, abort.

• applicant_perm.vp_state MUST be equal to PENDING, else abort.

• validation_fees (number) (mandatory): MUST be zero or a positive integer. If applicant_perm.effective_from is not null (we are in renewal) validation_fees MUST be equal to applicant_perm.validation_fees, else abort.

• issuance_fees (number) (mandatory): MUST be zero or a positive integer. If applicant_perm.effective_from is not null (we are in renewal) issuance_fees MUST be equal to applicant_perm.issuance_fees or, else abort.

• verification_fees (number) (mandatory): MUST be zero or a positive integer. If applicant_perm.effective_from is not null (we are in renewal) verification_fees MUST be equal to applicant_perm.verification_fees, else abort.

• vp_summary_digest (string) (optional): MUST be null if validation.type is set to HOLDER (for HOLDER, proofs can be stored in credentials). Else, MUST be a valid digest. Example: sha384-MzNNbQTWCSUSi0bbz7dbua+RcENv7C6FvlmYJ1Y+I727HsPOHdzwELMYO9Mz68M26.

• Load CredentialSchema cs from applicant_perm.schema_id.

• Load Permission validator_perm from applicant_perm.validator_perm_id.

• issuance_fee_discount : (number) (mandatory):

  • if applicant_perm.effective_from is not null (renewal), then issuance_fee_discount must be equal to applicant_perm.issuance_fee_discount else MUST abort.
  • if cs.issuer_perm_management_mode is set to GRANTOR_VALIDATION:
    • if applicant_perm.type == ISSUER_GRANTOR: issuance_fee_discount can be set between 0 (no discount) and 1 (100% discount) inclusive.
    • if applicant_perm.type == ISSUER: if validator_perm.issuance_fee_discount is defined, issuance_fee_discount can be set between 0 (no discount) and validator_perm.issuance_fee_discount (100% discount) inclusive.
  • if cs.issuer_perm_management_mode is set to ECOSYSTEM:
    • if applicant_perm.type == ISSUER: issuance_fee_discount can be set between 0 (no discount) and 1 (100% discount) inclusive.
  • else MUST abort.

• verification_fee_discount : (number) (mandatory):

  • if applicant_perm.effective_from is not null (renewal), then verification_fee_discount must be equal to applicant_perm.verification_fee_discount else MUST abort.
  • if cs.verifier_perm_management_mode is set to GRANTOR_VALIDATION:
    • if applicant_perm.type == VERIFIER_GRANTOR: verification_fee_discount can be set between 0 (no discount) and 1 (100% discount) inclusive.
    • if applicant_perm.type == VERIFIER: if validator_perm.verification_fee_discount is defined, verification_fee_discount can be set between 0 (no discount) and validator_perm.verification_fee_discount (100% discount) inclusive.
  • if cs.verifier_perm_management_mode is set to ECOSYSTEM:
    • if applicant_perm.type == VERIFIER: verification_fee_discount can be set between 0 (no discount) and 1 (100% discount) inclusive.
  • else MUST abort.

Calculation of vp_exp, the validation process expiration timestamp, required to verify provided effective_until:

• let’s define validity_period = cs.issuer_grantor_validation_validity_period (if applicant_perm.type is ISSUER_GRANTOR), cs.verifier_grantor_validation_validity_period (if applicant_perm.type is VERIFIER_GRANTOR), cs.issuer_validation_validity_period (if applicant_perm.type is ISSUER), cs.verifier_validation_validity_period (if applicant_perm.type is VERIFIER), or cs.holder_validation_validity_period (if applicant_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() plus validity_period.

• else vp_exp = applicant_perm.vp_exp plus validity_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, if vp_exp is not null, lower or equal to vp_exp.
• else effective_until MUST be greater than applicant_perm.effective_until AND, if vp_exp is not null, lower or equal to vp_exp.

§ [MOD-PERM-MSG-3-2-2] Set Permission VP to Validated validator perms

• load validator_perm from applicant_perm.validator_perm_id. validator_perm MUST be a active permission.
• authority running the method MUST be validator_perm.authority.

If validator_perm is not a active permission (expired, revoked, slashed…) then applicant MUST start a new validation process.

§ [MOD-PERM-MSG-3-2-3] Set Permission VP to Validated fee checks

• Fee payer MUST have the required estimated transaction fees in its account, else transaction MUST abort.
• if applicant_perm.vp_current_fees is not in native denom, authority account MUST have applicant_perm.vp_current_deposit available in native denom on its account for paying the trust deposit.

§ [MOD-PERM-MSG-3-2-4] Set Permission VP to Validated overlap checks

We want to make sure that 2 permissions cannot be active at the same time for the same validator_perm_id. That should not occur in this method, but better do the check anyway.

Find all active permissions perms[] (not revoked, not slashed, not repaid) for schema_id, type, validator_perm_id, authority.

for each Permission entry p from perms[]:

• if p.effective_until is greater than effective_from, method execution MUST abort.
• if p.effective_from is lower than effective_until, method execution MUST abort.
• if p.effective_until is NULL (never expire), creation of a new permission doesn’t make any sense and method execution MUST abort.

note: this check was not present in v3.

§ [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 entry applicant_perm from id.
• Load Permission entry validator_perm from applicant_perm.validator_perm_id.
• define now timestamp of now().

Calculate vp_exp:

• Load CredentialSchema cs from applicant_perm.schema_id.

• let’s define validity_period = cs.issuer_grantor_validation_validity_period (if applicant_perm.type is ISSUER_GRANTOR), cs.verifier_grantor_validation_validity_period (if applicant_perm.type is VERIFIER_GRANTOR), cs.issuer_validation_validity_period (if applicant_perm.type is ISSUER), cs.verifier_validation_validity_period (if applicant_perm.type is VERIFIER), or cs.holder_validation_validity_period (if applicant_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() plus validity_period.

• else vp_exp = applicant_perm.vp_exp plus validity_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 to vp_exp.

• else if applicant_perm.effective_until is NULL:

  • verify that provided effective_until is greater than now else MUST abort
  • if vp_exp is not null, verify that provided effective_until is lower or equal to vp_exp else MUST abort

• else:

  • effective_until MUST be greater than applicant_perm.effective_until else MUST abort
  • if vp_exp is not null, verify that provided effective_until is lower or equal to vp_exp else MUST abort.

Fees and Trust Deposits:

• transfer the full amount applicant_perm.vp_current_fees in the proper denom from escrow account to validator authority account validator_perm.authority;
• Increase validator perm trust deposit: use [MOD-TD-MSG-1] to increase by applicant_perm.vp_current_deposit the trust deposit of authority running the method and transfer the corresponding amount to TrustDeposit module. Set applicant_perm.vp_validator_deposit to applicant_perm.vp_validator_deposit + applicant_perm.vp_current_deposit.

Important: if applicant_perm.vp_current_fees is not in native denom, authority account MUST have applicant_perm.vp_current_deposit available for paying the trust deposit.

Update Permission applicant_perm:

• set applicant_perm.modified to now.
• set applicant_perm.vp_state to VALIDATED.
• set applicant_perm.vp_last_state_change to now.
• set applicant_perm.vp_current_fees to 0;
• set applicant_perm.vp_current_deposit to 0;
• set applicant_perm.vp_summary_digest to vp_summary_digest.
• set applicant_perm.vp_exp to vp_exp.
• set applicant_perm.effective_until to effective_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 to validation_fees;
  • set applicant_perm.issuance_fees to issuance_fees;
  • set applicant_perm.verification_fees to verification_fees;
  • set applicant_perm.effective_from to now.
  • set applicant_perm.issuance_fee_discount to issuance_fee_discount.
  • set applicant_perm.verification_fee_discount to verification_fee_discount.

If applicant_perm.type is ISSUER or VERIFIER: Create authorization for applicant_perm.vs_operator so that the Verifiable Service will be able to call CreateOrUpdatePermissionSession when issuing or verifying credentials:

• if applicant_perm.vs_operator_authz_enabled == true: call Grant VS Operator Authorization(applicant_perm.id).

§ [MOD-PERM-MSG-4] Void

§ [MOD-PERM-MSG-5] Void

§ [MOD-PERM-MSG-6] Cancel Permission VP Last Request

Any authorized operator CAN execute this method on behalf of an authority.

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 escrewed 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

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• id (uint64) (mandatory): id of the Permission 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.

• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• id MUST be a valid uint64.
• Load Permission entry applicant_perm with this id. It MUST exist.
• authority running the transaction MUST be applicant_perm.authority.
• applicant_perm.vp_state MUST be PENDING.
• if applicant_perm.deposit has been slashed and not repaid, MUST abort

§ [MOD-PERM-MSG-6-2-2] Cancel Permission VP Last Request fee checks

Fee payer 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 entry applicant_perm with id. It MUST exist.

• define now: current timestamp.

• set applicant_perm.modified to now.

• if applicant_perm.vp_exp is null (validation never completed), set applicant_perm.vp_state to TERMINATED, else set applicant_perm.vp_state to VALIDATED.

• set applicant_perm.vp_last_state_change to now.

• if applicant_perm.vp_current_fees > 0:

  • transfer applicant_perm.vp_current_fees in proper denom back from escrow account to applicant account, applicant_perm.authority.
  • set applicant_perm.vp_current_fees to 0;

• if applicant_perm.vp_current_deposit > 0:

  • call [MOD-TD-MSG-1] to reduce trust deposit of applicant_perm.authority by applicant_perm.vp_current_deposit
  • set applicant_perm.vp_current_deposit to 0.

§ [MOD-PERM-MSG-7] Create Root Permission

Any authorized operator CAN execute this method on behalf of an authority.

This method is used by controller authorities 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 (if schema mode is ECOSYSTEM) or self create their permissions (schema mode set to OPEN).

§ [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:

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• schema_id (uint64) (mandatory)
• did (string) (mandatory): DID of the VS.
• effective_from (timestamp) (mandatory): 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 than effective_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 the denom specified in the credential schema. Default to 0. Note that setting validation fees for OPEN schemas has no effect and does not mean a validation process must take place. For enabling validation processes, at least one of the two issuer, verifier mode must be different than OPEN.
• 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 the denom specified in the credential schema. 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 the denom specified in the credential schema. 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.

• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• 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 than effective_from
• 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 with schema_id, and will be named cs in this section.
• The related TrustRegistry entry tr is loaded from cs.tr_id.
• authority executing the method MUST be tr.authority.
• else MUST abort.

§ [MOD-PERM-MSG-7-2-3] Create Root Permission fee checks

Fee payer MUST have the required estimated transaction fees available.

§ [MOD-PERM-MSG-7-2-4] Create Root Permission overlap checks

We want to make sure that 2 permissions cannot be active at the same time. If authority wishes to create a new permission but existing active one never expires (or expire too far from now), authority MUST use first the Extend Perm Msg to set or adjust the effective_until value.

Find all active permissions perms[] (not revoked, not slashed, not repaid) for schema_id, ECOSYSTEM, authority.

Note: unlike overlap checks from other methods, here we do not need to check for validator_perm_id, as for ECOSYSTEM type permissions it is NULL.

for each Permission entry p from perms[]:

• if p.effective_until is greater than effective_from, method execution MUST abort.
• if p.effective_from is lower than effective_until, method execution MUST abort.
• if p.effective_until is NULL (never expire), creation of a new permission doesn’t make any sense and method execution MUST abort.

note: this check was not present in v3.

§ [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 to now.
• perm.type: ECOSYSTEM.
• perm.did: did.
• perm.authority: authority.
• perm.created: now
• perm.effective_from: effective_from
• perm.effective_until: effective_until
• perm.validation_fees: validation_fees
• perm.issuance_fees: issuance_fees
• perm.verification_fees: verification_fees
• perm.deposit: 0

§ [MOD-PERM-MSG-8] Adjust Permission

Any authorized operator CAN execute this method on behalf of an authority.

This method can be called:

• by perm.authority, if permission is of type ECOSYSTEM.
• by perm.authority, if it is a self-created permission (schema configuration is open)
• by an authority of a validator permission (if permission is managed by a VP).

§ [MOD-PERM-MSG-8-1] Adjust Permission parameters

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• id (uint64) (mandatory): id of the permission;
• effective_until (timestamp) (mandatory): timestamp until when (exclusive) this Permission will be effective.

§ [MOD-PERM-MSG-8-2] Adjust Permission precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-8-2-1] Adjust Permission basic checks

if a mandatory parameter is not present, transaction MUST abort.

• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• id MUST be a valid uint64.
• Load Permission entry applicant_perm from id. If no entry found, abort.
• applicant_perm MUST be a active permission
• applicant_perm.effective_until MUST be greater than now().
• else MUST abort.

Note: This method can be used to both Extend or Reduce the effective_until, or set an effective_until if it was null, which was not the case in spec v3.

§ [MOD-PERM-MSG-8-2-2] Adjust Permission advanced checks

1. ECOSYSTEM permissions

• if applicant_perm.validator_perm_id is null and applicant_perm.type is ECOSYSTEM, authority running the method MUST be applicant_perm.authority.

2. Self-created permissions

• load validator_perm from applicant_perm.validator_perm_id. validator_perm MUST be a active permission of type ECOSYSTEM. authority running the method MUST be applicant_perm.authority.

3. VP managed permissions

• effective_until MUST be lower or equal to applicant_perm.vp_exp else MUST abort.
• load validator_perm from applicant_perm.validator_perm_id. validator_perm MUST be a active permission. authority running the method MUST be validator_perm.authority.

§ [MOD-PERM-MSG-8-2-3] Adjust Permission fee checks

Fee payer MUST have the required estimated transaction fees in its account, else transaction MUST abort.

§ [MOD-PERM-MSG-8-2-4] Adjust Permission overlap checks

We want to make sure that 2 permissions cannot be active at the same time for the same validator_perm_id. If authority wishes to create a new permission but existing active one never expires (or expire too far from now), authority MUST use first the Extend Perm Msg to set or adjust the effective_until value.

Find all active permissions perms[] (not revoked, not slashed, not repaid) for schema_id, type, validator_perm_id, authority.

for each Permission entry p from perms[]:

• if p.effective_until is greater than effective_from, method execution MUST abort.
• if p.effective_from is lower than effective_until, method execution MUST abort.
• if p.effective_until is NULL (never expire), creation of a new permission doesn’t make any sense and method execution MUST abort.

note: this check was not present in v3.

§ [MOD-PERM-MSG-8-3] Adjust 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 entry applicant_perm from id.

• set applicant_perm.effective_until to effective_until

• set applicant_perm.adjusted to now

• set applicant_perm.modified to now

If applicant_perm.type is ISSUER or VERIFIER: Update authorization for applicant_perm.vs_operator so that the Verifiable Service will be able to call CreateOrUpdatePermissionSession when issuing or verifying credentials:

• if applicant_perm.vs_operator_authz_enabled == true: call Grant VS Operator Authorization(applicant_perm.id).

§ [MOD-PERM-MSG-9] Revoke Permission

Any authorized operator CAN execute this method on behalf of an authority.

This method can only be called:

• by an ancestor (authority of a validator in the permission branch until the root permission (GRANTOR, ECOSYSTEM, OPEN schema mode)).
• by the grantee authority (OPEN, GRANTOR, ECOSYSTEM schema mode).
• by the TrustRegistry authority (owner of the credential schema).

§ [MOD-PERM-MSG-9-1] Revoke Permission parameters

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• 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.

• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• id MUST be a valid uint64.
• Load Permission entry applicant_perm from id. If no entry found, abort.
• applicant_perm MUST be a active permission

§ [MOD-PERM-MSG-9-2-2] Revoke Permission advanced checks

Either Option #1, #2 or #3 MUST return true, else abort.

Option #1: executed by a validator ancestor

if applicant_perm.validator_perm_id is defined:

• set validator_perm = applicant_perm
• while validator_perm.validator_perm_id is defined,
  • load validator_perm from validator_perm.validator_perm_id.
  • if validator_perm is a active permission and validator_perm.authority is who is running the method, => return true.
• end
• return false.

Option #2: executed by TrustRegistry controller

• load CredentialSchema cs from applicant_perm.schema_id
• load TrustRegistry tr from cs.tr_id
• if authority running the method is tr.authority, return true.
• else return false.

Option #3: executed by applicant_perm.authority: return true.

Example:

In the following permission tree, “Verifier E” permission can be revoked:

• by “Verifier E”, if the corresponding permission is a active permission;
• by “Verifier Grantor D”, if the corresponding permission is a active permission;
• by “Ecosystem A”, if the corresponding root permission is a active permission;
• by the TrustRegistry object controller, obtained by resolving perm => credential schema => trust registry.

§ [MOD-PERM-MSG-9-2-3] Revoke Permission fee checks

Fee payer 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 entry applicant_perm from id.

• set applicant_perm.revoked to now

• set applicant_perm.modified to now

If applicant_perm.type is ISSUER or VERIFIER: Delete authorization for applicant_perm.vs_operator:

• call Revoke VS Operator Authorization(applicant_perm.id).

§ [MOD-PERM-MSG-10] Create or Update Permission Session

Any authorized operator CAN execute this method on behalf of an authority.

Any credential exchange that requires issuer or verifier to pay fees, register a digest_sri, or produce a proof 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, uint64[] issuer_perm_ids>

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:

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• id (uuid) (mandatory): id of the PermissionSession.
• issuer_perm_id (uint64) (optional): the id of the perm of the issuer, if we are dealing with the issuance of a credential.
• verifier_perm_id (uint64) (optional): the id of the perm of the verifier, if we are dealing with the verification of a credential.
• agent_perm_id (uint64) (mandatory): the agent credential issuer permission id (extracted from the agent credential that agent has in its wallet) of the agent that received the request (credential offer for issuance, presentation request for verification).
• wallet_agent_perm_id (uint64) (mandatory): the wallet credential issuer permission id of the agent where the credential will be or is stored. Can be the same perm than agent_perm_id if agent and wallet_agent are the same agent.
• digest (string) (optional): digest derived from an issued or verified credential.

§ [MOD-PERM-MSG-10-2] Create or Update Permission Session precondition checks

If any of these precondition checks fail, transaction MUST abort.

• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• id MUST be a valid uuid. If an entry existing_entry with id already exist, then existing_entry.authority MUST be equal to authority AND existing_entry.vs_operator MUST be equal to operator, else 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 not null:

• Load issuer_perm from issuer_perm_id.
• if issuer_perm.type is not ISSUER, abort.
• if issuer_perm is not a active permission, abort.
• if issuer_perm.vs_operator is not equal to operator, abort.
• if issuer_perm.authority is not equal to authority, abort.
• if digest_sri is present but not a valid digest SRI, abort.

if verifier_perm_id is not null:

• Load verifier_perm from verifier_perm_id.
• if verifier_perm.type is not VERIFIER, abort.
• if verifier_perm is not a active permission, abort.
• if verifier_perm.vs_operator is not equal to operator, abort.
• if verifier_perm.authority is not equal to authority, abort.
• if digest_sri is present but not a valid digest SRI, abort.

Define the primary permission perm: if verifier_perm is not null, perm = verifier_perm (the caller is the vs_operator of the verifier). Else, perm = issuer_perm (the caller is the vs_operator of the issuer).

[AUTHZ-CHECK-3] MUST pass for this (authority, operator, perm) tuple. [AUTHZ-CHECK-4] MUST pass for this (authority, operator, perm) tuple.

agent:

• Load agent_perm from agent_perm_id.
• if agent_perm.type is not ISSUER, abort.
• if agent_perm is not a active permission, abort.

wallet_agent:

• Load wallet_agent_perm from wallet_agent_perm_id.
• if wallet_agent_perm.type is not ISSUER, abort.
• if wallet_agent_perm is not a active permission, abort.

§ [MOD-PERM-MSG-10-3] Create or Update Permission Session fee checks

• Load CredentialSchema entry cs from issuer_perm.schema_id if issuer_perm is not null, else from verifier_perm.schema_id.
• Fee payer MUST have sufficient available balance for the required estimated transaction fees.

For trust fees, authority account MUST have sufficient available balance as explained below.

Step 1: Calculate total beneficiary fees in credential schema pricing asset

Use “Find Beneficiaries” query method to get the set of beneficiary permissions found_perm_set (all ancestors in the permission tree).

• define total_beneficiary_fees = 0

If Credential Issuance (issuer_perm is NOT null):

• for each perm in found_perm_set:
  • total_beneficiary_fees = total_beneficiary_fees + perm.issuance_fees × (1 - issuer_perm.issuance_fee_discount)

If Credential Verification (verifier_perm is NOT null):

• for each perm in found_perm_set:
  • total_beneficiary_fees = total_beneficiary_fees + perm.verification_fees × (1 - verifier_perm.verification_fee_discount)

Note: total_beneficiary_fees is expressed in the credential schema pricing asset (cs.pricing_asset_type, cs.pricing_asset).

Step 2: Calculate amounts payer must have available

Based on the credential schema pricing configuration, calculate the total amounts the payer (authority) must have available.

Define the following variables:

Initialize:

• total_fees_in_pricing_asset = total_beneficiary_fees
• total_fees_in_native_denom = 0
• total_payer_trust_deposit = 0
• total_payees_trust_deposit = 0
• total_payees_fees_to_account = 0
• total_user_agent_reward = 0
• total_wallet_agent_reward = 0

If a conversion is needed below, use Get Price to convert amounts.

Case A: (cs.pricing_asset_type, cs.pricing_asset) = (COIN, [[ref: native denom]])

Pricing is in native token. No conversion needed.

Calculate:

• total_fees_in_native_denom = total_fees_in_pricing_asset
• total_payer_trust_deposit = total_fees_in_native_denom × GlobalVariables.trust_deposit_rate
• total_payees_trust_deposit = total_payer_trust_deposit
• total_payees_fees_to_account = total_fees_in_native_denom × (1 - GlobalVariables.trust_deposit_rate)
• total_user_agent_reward = total_fees_in_native_denom × GlobalVariables.user_agent_reward_rate
• total_wallet_agent_reward = total_fees_in_native_denom × GlobalVariables.wallet_user_agent_reward_rate

Required balance check:

• authority MUST have available balance ≥ total_fees_in_native_denom + total_payer_trust_deposit + total_user_agent_reward + total_wallet_agent_reward in native denom.

Case B: (cs.pricing_asset_type, cs.pricing_asset) = (TU, "tu")

Pricing is in Trust Units. Convert to native denom for all on-chain payments.

Calculate:

• total_fees_in_native_denom = getPrice(TU, "tu", COIN, [[ref: native denom]], total_fees_in_pricing_asset)
• total_payer_trust_deposit = total_fees_in_native_denom × GlobalVariables.trust_deposit_rate
• total_payees_trust_deposit = total_payer_trust_deposit
• total_payees_fees_to_account = total_fees_in_native_denom × (1 - GlobalVariables.trust_deposit_rate)
• total_user_agent_reward = total_fees_in_native_denom × GlobalVariables.user_agent_reward_rate
• total_wallet_agent_reward = total_fees_in_native_denom × GlobalVariables.wallet_user_agent_reward_rate

Required balance check:

• authority MUST have available balance ≥ total_fees_in_native_denom + total_payer_trust_deposit + total_user_agent_reward + total_wallet_agent_reward in native denom.

Case C: (cs.pricing_asset_type, cs.pricing_asset) = (COIN, <arbitrary_denom>)

Pricing is in an arbitrary on-chain coin (e.g., USDC). Fees to payees are paid in that coin; deposits and agent rewards are converted to native denom.

Calculate:

• total_fees_in_native_denom = getPrice(COIN, <arbitrary_denom>, COIN, [[ref: native denom]], total_fees_in_pricing_asset)
• total_payer_trust_deposit = total_fees_in_native_denom × GlobalVariables.trust_deposit_rate
• total_payees_trust_deposit = total_payer_trust_deposit
• total_payees_fees_to_account = total_fees_in_pricing_asset × (1 - GlobalVariables.trust_deposit_rate)
• total_user_agent_reward = total_fees_in_native_denom × GlobalVariables.user_agent_reward_rate
• total_wallet_agent_reward = total_fees_in_native_denom × GlobalVariables.wallet_user_agent_reward_rate

Required balance check:

• authority MUST have available balance ≥ total_payer_trust_deposit + total_payees_trust_deposit + total_user_agent_reward + total_wallet_agent_reward in native denom.
• AND authority MUST have available balance ≥ total_payees_fees_to_account in <arbitrary_denom>.

Case D: (cs.pricing_asset_type, cs.pricing_asset) = (FIAT, <fiat_denom>)

Pricing is in fiat currency (e.g., USD). Fiat fees are settled off-chain; only deposits and agent rewards are paid on-chain in native denom.

Calculate:

• total_fees_in_native_denom = getPrice(FIAT, <fiat_denom>, COIN, [[ref: native denom]], total_fees_in_pricing_asset)
• total_payer_trust_deposit = total_fees_in_native_denom × GlobalVariables.trust_deposit_rate
• total_payees_trust_deposit = total_payer_trust_deposit
• total_payees_fees_to_account = 0 (FIAT payments are managed off-chain)
• total_user_agent_reward = total_fees_in_native_denom × GlobalVariables.user_agent_reward_rate
• total_wallet_agent_reward = total_fees_in_native_denom × GlobalVariables.wallet_user_agent_reward_rate

Required balance check:

• authority MUST have available balance ≥ total_payer_trust_deposit + total_payees_trust_deposit + total_user_agent_reward + total_wallet_agent_reward in native denom.

§ [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.
• Load CredentialSchema entry cs from issuer_perm.schema_id if issuer_perm is not null, else from verifier_perm.schema_id.
• define now: current timestamp.
• use “Find Beneficiaries” to build found_perm_set.

Note: All funds are transferred from the authority account executing the method. The steps below describe what each recipient must receive. Implementation details (batching, order of transfers) are left to the implementer.

Step 1: Process fee distribution to each beneficiary

Initialize accumulators for agent rewards:

• accumulated_user_agent_reward = 0
• accumulated_wallet_agent_reward = 0

Determine the operation type and applicable discount:

• If Credential Issuance (issuer_perm is NOT null):

  • fee_field = issuance_fees
  • discount = issuer_perm.issuance_fee_discount
  • payer_perm = issuer_perm

• Else if Credential Verification (verifier_perm is NOT null):

  • fee_field = verification_fees
  • discount = verifier_perm.verification_fee_discount
  • payer_perm = verifier_perm

For each beneficiary permission perm in found_perm_set:

If perm.[fee_field] > 0:

1. Calculate the discounted fee for this beneficiary:

   • beneficiary_fee_in_pricing_asset = perm.[fee_field] × (1 - discount)

2. Calculate amounts based on pricing configuration (same logic as fee checks):

   Case A: (cs.pricing_asset_type, cs.pricing_asset) = (COIN, [[ref: native denom]])

   • fee_in_native_denom = beneficiary_fee_in_pricing_asset
   • payer_trust_deposit = fee_in_native_denom × GlobalVariables.trust_deposit_rate
   • payee_trust_deposit = payer_trust_deposit
   • payee_fees_to_account = fee_in_native_denom × (1 - GlobalVariables.trust_deposit_rate)
   • user_agent_reward_portion = fee_in_native_denom × GlobalVariables.user_agent_reward_rate
   • wallet_agent_reward_portion = fee_in_native_denom × GlobalVariables.wallet_user_agent_reward_rate

   Case B: (cs.pricing_asset_type, cs.pricing_asset) = (TU, "tu")

   • fee_in_native_denom = getPrice(TU, "tu", COIN, [[ref: native denom]], beneficiary_fee_in_pricing_asset)
   • payer_trust_deposit = fee_in_native_denom × GlobalVariables.trust_deposit_rate
   • payee_trust_deposit = payer_trust_deposit
   • payee_fees_to_account = fee_in_native_denom × (1 - GlobalVariables.trust_deposit_rate)
   • user_agent_reward_portion = fee_in_native_denom × GlobalVariables.user_agent_reward_rate
   • wallet_agent_reward_portion = fee_in_native_denom × GlobalVariables.wallet_user_agent_reward_rate

   Case C: (cs.pricing_asset_type, cs.pricing_asset) = (COIN, <arbitrary_denom>)

   • fee_in_native_denom = getPrice(COIN, <arbitrary_denom>, COIN, [[ref: native denom]], beneficiary_fee_in_pricing_asset)
   • payer_trust_deposit = fee_in_native_denom × GlobalVariables.trust_deposit_rate
   • payee_trust_deposit = payer_trust_deposit
   • payee_fees_to_account = beneficiary_fee_in_pricing_asset × (1 - GlobalVariables.trust_deposit_rate) (in <arbitrary_denom>)
   • user_agent_reward_portion = fee_in_native_denom × GlobalVariables.user_agent_reward_rate
   • wallet_agent_reward_portion = fee_in_native_denom × GlobalVariables.wallet_user_agent_reward_rate

   Case D: (cs.pricing_asset_type, cs.pricing_asset) = (FIAT, <fiat_denom>)

   • fee_in_native_denom = getPrice(FIAT, <fiat_denom>, COIN, [[ref: native denom]], beneficiary_fee_in_pricing_asset)
   • payer_trust_deposit = fee_in_native_denom × GlobalVariables.trust_deposit_rate
   • payee_trust_deposit = payer_trust_deposit
   • payee_fees_to_account = 0 (FIAT payments are managed off-chain)
   • user_agent_reward_portion = fee_in_native_denom × GlobalVariables.user_agent_reward_rate
   • wallet_agent_reward_portion = fee_in_native_denom × GlobalVariables.wallet_user_agent_reward_rate

3. Execute transfers and deposits for this beneficiary:

   • If payee_fees_to_account > 0: transfer payee_fees_to_account to perm.authority (in the appropriate denom).
   • Use [MOD-TD-MSG-1] to increase the trust deposit of perm.authority by payee_trust_deposit. Increase perm.deposit by the same value.
   • Use [MOD-TD-MSG-1] to increase the trust deposit of authority (payer) by payer_trust_deposit. Increase payer_perm.deposit by the same value.

4. Accumulate agent rewards:

   • accumulated_user_agent_reward = accumulated_user_agent_reward + user_agent_reward_portion
   • accumulated_wallet_agent_reward = accumulated_wallet_agent_reward + wallet_agent_reward_portion

Step 2: Process agent rewards

After processing all beneficiaries, distribute accumulated rewards to agents.

User Agent Reward:

If accumulated_user_agent_reward > 0:

• agent_trust_deposit = accumulated_user_agent_reward × GlobalVariables.trust_deposit_rate
• agent_fees_to_account = accumulated_user_agent_reward - agent_trust_deposit
• Transfer agent_fees_to_account to agent_perm.authority in native denom.
• Use [MOD-TD-MSG-1] to increase the trust deposit of agent_perm.authority by agent_trust_deposit. Increase agent_perm.deposit by the same value.

Wallet Agent Reward:

If accumulated_wallet_agent_reward > 0:

• wallet_agent_trust_deposit = accumulated_wallet_agent_reward × GlobalVariables.trust_deposit_rate
• wallet_agent_fees_to_account = accumulated_wallet_agent_reward - wallet_agent_trust_deposit
• Transfer wallet_agent_fees_to_account to wallet_agent_perm.authority in native denom.
• Use [MOD-TD-MSG-1] to increase the trust deposit of wallet_agent_perm.authority by wallet_agent_trust_deposit. Increase wallet_agent_perm.deposit by the same value.

Step 3: Create or update session records

Now that all transfers have been done, we can create the entries

Create a PermissionSessionRecord cspsr:

• cspsr.created: now
• cspsr.issuer_perm_id: issuer_perm_id
• cspsr.verifier_perm_id: verifier_perm_id
• cspsr.wallet_agent_perm_id: wallet_agent_perm_id

If new, create entry PermissionSession session:

• session.id: id
• session.authority: authority
• session.vs_operator: operator
• session.agent_perm_id: agent_perm_id
• session.modified: : now
• session.created: : now

Else update:

• session.modified: : now

then, add the cspsr to session.session_records

if current transaction if for issuance of a credential, persist the digest SRI by calling [MOD-DI-MSG-1].

§ [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 of params MUST be greater than 0. For each param <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:

• an authority ancestor validator of this permission;
• the authority controller of the TrustRegistry object, owner of the corresponding credential schema.

§ [MOD-PERM-MSG-12-1] Slash Permission Trust Deposit parameters

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• 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.

• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• id MUST be a valid uint64.
• Load Permission entry applicant_perm from id. If no entry found, abort.
• amount MUST be lower or equal to applicant_perm.deposit else MUST abort.

§ [MOD-PERM-MSG-12-2-2] Slash Permission Trust Deposit validator perms

Either Option #1, or #2 MUST return true, else abort.

Option #1: executed by a validator ancestor

if applicant_perm.validator_perm_id is defined:

• set validator_perm = applicant_perm
• while validator_perm.validator_perm_id is defined,
  • load validator_perm from validator_perm.validator_perm_id.
  • if validator_perm is a active permission and validator_perm.authority is who is running the method, => return true.
• end
• return false.

Option #2: executed by TrustRegistry controller

• load CredentialSchema cs from applicant_perm.schema_id
• load TrustRegistry tr from cs.tr_id
• if authority running the method is tr.authority, return true.
• else return false.

§ [MOD-PERM-MSG-12-2-3] Slash Permission Trust Deposit fee checks

Fee payer 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 entry applicant_perm from id.

• Load Permission entry validator_perm from applicant_perm.validator_perm_id.

• set applicant_perm.slashed to now

• set applicant_perm.modified to now

• set applicant_perm.slashed_deposit to applicant_perm.slashed_deposit + amount

use MOD-TD-MSG-7 to burn the slashed amount from the trust deposit of applicant_perm.authority.

If applicant_perm.type is ISSUER or VERIFIER: Delete authorization for applicant_perm.vs_operator:

• call Revoke VS Operator Authorization(applicant_perm.id) with the following parameters:

§ [MOD-PERM-MSG-13] Repay Permission Slashed Trust Deposit

This method can only be called by the authority that want to repay the deposit of a slashed perm they own. This won’t make the perm re-usable: it will be needed for the authority associated to this permission 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

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• 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.

• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• id MUST be a valid uint64.
• Load Permission entry applicant_perm from id. If no entry found, abort.
• if applicant_perm.authority is not equal to authority, abort.

§ [MOD-PERM-MSG-13-2-2] Repay Permission Slashed Trust Deposit fee checks

• Fee payer MUST have the required estimated transaction fees in its account;
• authority MUST have at least applicant_perm.slashed_deposit in its account balance, 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.

use Adjust Trust Deposit to transfer applicant_perm.slashed_deposit to trust deposit of applicant_perm.authority.

• Load Permission entry applicant_perm from id.
• set applicant_perm.repaid to now
• set applicant_perm.modified to now
• set applicant_perm.repaid_deposit to applicant_perm.slashed_deposit.

§ [MOD-PERM-MSG-14] Self Create Permission

Any authorized operator CAN execute this method on behalf of an authority.

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 for an issuer/verifier candidate to self-create a permission for being issuer or verifier of a given schema.

§ [MOD-PERM-MSG-14-1] Self Create Permission parameters

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.
• type (PermissionType) (mandatory): ISSUER or VERIFIER.
• validator_perm_id (uint64) (mandatory): MUST be an ECOSYSTEM active permission or future permission.
• vs_operator (account) (optional): the account we want to authorize to create permission sessions linked to this permission. Required for payment delegation.
• did (string) (mandatory): DID of the VS grantee service.
• 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 than effective_from.
• verification_fees (number) (optional): price to pay by the verifier of a credential of this schema to the grantee of this ISSUER perm when a credential is verified, in the denom specified in the credential schema. Default to 0.
• validation_fees (number) (optional): price to pay by the holder of a credential of this schema to the issuer when executing a validation process to obtain a credential, in the denom specified in the credential schema. Default to 0.
• vs_operator_authz_enabled: boolean (mandatory): if set to true authorize this vs_operator to execute CreateOrUpdatePermissionSession on behalf of authority account (trust fees will be paid by authority account)
• vs_operator_authz_spend_limit (DenomAmount[]) (optional): maximum amount of funds that the vs_operator is allowed to spend in the context of this permission. as a direct consequence of executing authorized messages.
• vs_operator_authz_with_feegrant: boolean (mandatory): if set to true, enable feegrant for this permission so vs_operator can pay the fees for CreateOrUpdatePermissionSession with authority account.
• vs_operator_authz_fee_spend_limit (DenomAmount[]) (optional): maximum total amount of fees that can be spent by vs_operator in the context of this permission.
• vs_operator_authz_spend_period: (period) (optional): reset period for vs_operator_authz_spend_limit and vs_operator_authz_fee_spend_limit in the context of this permission.

§ [MOD-PERM-MSG-14-2] Self Create Permission precondition checks

If any of these precondition checks fail, transaction MUST abort.

§ [MOD-PERM-MSG-14-2-1] Self Create Permission basic checks

if a mandatory parameter is not present, transaction MUST abort.

Load Permission validator_perm from validator_perm_id.

• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.
• type (PermissionType) (mandatory): MUST be ISSUER or VERIFIER, else abort.
• validator_perm_id (uint64) (mandatory): validator_perm MUST be an ECOSYSTEM active permission or future permission.
• vs_operator (account) (optional): no check required.
• did, MUST conform to the DID Syntax, as specified [DID-CORE].
• effective_from MUST be in the future AND
  • MUST be greater or equal to validator_perm.effective_from AND
  • if validator_perm.effective_until is not null, MUST be lower than validator_perm.effective_until
• effective_until:
  • if null, validator_perm.effective_until MUST be NULL
  • else if not null, must be greater than effective_from AND if validator_perm.effective_until is not null, MUST be lower or equal to validator_perm.effective_until
• verification_fees (number) (optional): If specified, MUST be >= 0 and MUST be a ISSUER permission.
• validation_fees (number) (optional): If specified, MUST be >= 0 and MUST be a ISSUER permission.
• vs_operator_authz_enabled: boolean (mandatory): if set to true, vs_operator MUST NOT be null, else abort.
• vs_operator_authz_spend_limit (DenomAmount[]) (optional): maximum amount of funds that the vs_operator is allowed to spend in the context of this permission. as a direct consequence of executing authorized messages.
• vs_operator_authz_with_feegrant: boolean (mandatory): if set to true, vs_operator MUST NOT be null, else abort.
• vs_operator_authz_fee_spend_limit (DenomAmount[]) (optional): maximum total amount of fees that can be spent by vs_operator in the context of this permission.
• vs_operator_authz_spend_period: (period) (optional): if not null, vs_operator MUST NOT be null, else abort. Reset period for vs_operator_authz_spend_limit and vs_operator_authz_fee_spend_limit in the context of this permission.

§ [MOD-PERM-MSG-14-2-2] Self 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 with validator_perm.schema_id, and will be named cs in this section.
• if type is equal to ISSUER: if cs.issuer_perm_management_mode is not equal to OPEN, MUST abort.
• if type is equal to VERIFIER: if cs.verifier_perm_management_mode is not equal to OPEN, MUST abort.
• if type is equal to VERIFIER and validation_fees is specified and different than 0, MUST abort.
• if type is equal to VERIFIER and verification_fees is specified and different than 0, MUST abort.

§ [MOD-PERM-MSG-14-2-3] Self Create Permission fee checks

Fee payer MUST have the required estimated transaction fees available.

§ [MOD-PERM-MSG-14-2-4] Self Create Permission overlap checks

We want to make sure that 2 permissions cannot be active at the same time for the same validator_perm_id. If authority wishes to create a new permission but existing active one never expires (or expire too far from now), authority MUST use first the Extend Perm Msg to set or adjust the effective_until value.

Find all active permissions perms[] (not revoked, not slashed, not repaid) for cs.id, type, validator_perm_id, authority.

for each Permission entry p from perms[]:

• if p.effective_until is greater than effective_from, method execution MUST abort.
• if p.effective_from is lower than effective_until, method execution MUST abort.
• if p.effective_until is NULL (never expire), creation of a new permission doesn’t make any sense and method execution MUST abort.

note: this check was not present in v3.

§ [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.
• Load Permission validator_perm from validator_perm_id.

A new entry Permission perm MUST be created:

• perm.id: auto-incremented uint64.
• perm.validator_perm_id: validator_perm_id
• perm.schema_id: validator_perm.schema_id
• perm.modified to now.
• perm.type: type.
• perm.did: did.
• perm.authority: authority.
• perm.vs_operator: vs_operator.
• perm.created: now
• perm.effective_from: effective_from
• perm.effective_until: effective_until
• perm.validation_fees: validation_fees if specified and type is ISSUER, else 0.
• perm.issuance_fees: 0
• perm.verification_fees: verification_fees if specified and type is ISSUER, else 0.
• perm.deposit: 0
• perm.vs_operator_authz_enabled: vs_operator_authz_enabled
• perm.vs_operator_authz_spend_limit: vs_operator_authz_spend_limit
• perm.vs_operator_authz_with_feegrant: vs_operator_authz_with_feegrant
• perm.vs_operator_authz_fee_spend_limit: vs_operator_authz_fee_spend_limit
• perm.vs_operator_authz_spend_period: vs_operator_authz_spend_period

Create authorization for vs_operator so that the Verifiable Service will be able to call CreateOrUpdatePermissionSession when issuing or verifying credentials:

• if perm.vs_operator_authz_enabled == true: call Grant VS Operator Authorization(perm.id).

§ [MOD-PERM-QRY-1] List Permissions

Anyone CAN execute this method.

Generic query used for (at least):

• find all permissions (all or limit to active) of a given schema;
• for a given validator, get PENDING validation processes;
• find all permissions of a given grantee;
• find all permissions of a given did;
• find all ISSUER_GRANTOR active permission, so that I can apply to an ISSUER permission; …

§ [MOD-PERM-QRY-1-1] List Permissions parameters

• schema_id (number) (optional): the schema id.
• grantee (account) (optional): the grantee account.
• did (string) (optional): the did the permission refers to.
• perm_id (number) (optional): limit to permissions where the validator_perm_id is perm_id.
• type (PermissionType) (optional): if we want to limit to a specific permission type.
• only_valid (boolean) (optional): if set to true, only return active permissions.
• only_slashed (boolean) (optional): if set to true, only return slashed permissions.
• only_repaid (boolean) (optional): if set to true, only return repaid slashed permissions.
• modified_after (timestamp) (optional): limit to permissions modified after (or equal to) modified_after.
• vp_state (ValidationState) (optional): limit to permissions with a vp_state not null and equal to vp_state.
• response_max_size (small number) (optional): limit to response_max_size results. Must be min 1, max 1,024. Default to 64.
• when (timestamp) (optional): if set, query at when, else query at now(). Used to query the VPR state at a previous datetime.

§ [MOD-PERM-QRY-1-2] List Permissions checks

Basic type check arg SHOULD be applied.

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-PERM-QRY-1-3] List Permissions execution

return a list of found entries, or an empty list if nothing found. Ordered by 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] Void

Obsoleted by [MOD-PERM-QRY-1].

§ [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.

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 and verifier_perm_id are unset then MUST abort.
• if issuer_perm_id is specified, load issuer_perm from issuer_perm_id, Permission MUST exist and MUST be a active permission.
• if verifier_perm_id is specified, load verifier_perm from verifier_perm_id, Permission MUST exist and MUST be a active permission.

§ [MOD-PERM-QRY-4-3] Find Beneficiaries execution

Example: Let’s build the set. Revoked and slashed permissions will not be added to the set. Expired permissions, if not revoked/slashed, will be considered.

• create Set found_perm_set.

• define permission current_perm as null.

• load perms issuer_perm and optional verifier_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:
  • current_perm = load(current_perm.validator_perm_id)
  • if current_perm.revoked is NULL AND current_perm.slashed is NULL, Add current_perm to found_perm_set.

Additionally, if verifier_perm is not null:

• if issuer_perm is not null, add issuer_perm to found_perm_set
• set current_perm = verifier_perm
• while current_perm.validator_perm_id != null:
  • current_perm = load(current_perm.validator_perm_id)
  • if current_perm.revoked is NULL AND current_perm.slashed is NULL, Add current_perm to found_perm_set.

return found_perms.

§ [MOD-PERM-QRY-5] Get PermissionSession

§ [MOD-PERM-QRY-5-1] Get PermissionSession parameters

• id (uuid) (mandatory): the id of the PermissionSession.

§ [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",
    ...
    ...
  }
}

§ 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.

§ 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 of 0: TrustDeposit.deposit : 0.
• GlobalVariables.trust_deposit_share_value has a value of 1.

Operation #1:

an account account1 wants to create a transaction that requires:

• 10 denom to be sent to the account1 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 the TrustDeposit module.

  • TrustDeposit.deposit = TrustDeposit.deposit + 10

• a TrustDeposit entry td1 is created for account1 running the service with:

  • td1.deposit = 10
  • td1.shares = 10 / GlobalVariables.trust_deposit_share_value = 10

Second, fee distribution: let’s suppose that trust_deposit_block_reward_share is set to 0.30 so that 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 to TrustDeposit module, which will increase the GlobalVariables.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 the account2 trust deposit;
• 10 denom for network fees.

First, Trust Deposit:

• 20 denom are sent to the TrustDeposit module.

  • TrustDeposit.deposit = 31.5

• a TrustDeposit entry td2 is created for account2:

  • td2.deposit = 20
  • td2.shares = 20 / GlobalVariables.trust_deposit_share_value = 20 / 1.15 ~= 17.39...

Second, fee distribution: let’s suppose trust_deposit_block_reward_share is set to 0.30 so that 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 to TrustDeposit module, which will increase the GlobalVariables.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) is account1.share * GlobalVariables.trust_deposit_share_value ~= 12.595..., available withdrawable yield is account1.share * GlobalVariables.trust_deposit_share_value - account1.deposit ~= 2.595...
• account2 real deposit (based on share) is account2.share * GlobalVariables.trust_deposit_share_value ~= 21.90..., available withdrawable yield is account2.share * GlobalVariables.trust_deposit_share_value - account2.deposit ~= 1.90...

§ Trust Deposit Yield

The following global parameters are used to tune the Trust Deposit yield generation, in case the VPR is implemented as a ledger:

• trust_deposit_max_yield_rate(number) (mandatory): Maximum yearly yield, in percent, that a trust deposit holder can obtain by receiving block rewards.
• trust_deposit_block_reward_share(number) (mandatory): Percentage of block reward that must be distributed to trust deposit holders. Default value: 20% (0.20)

Each time there is a block reward to be distributed, trust_deposit_block_reward_share percent MUST be directed to trust deposit holders, based on their trust deposit share.

Implementers MUST make sure, for each processed block reward, that the yearly effective yield is lower or equal than trust_deposit_max_yield_rate.

§ [MOD-TD-MSG-1] Adjust Trust Deposit

This method is used to increase or decrease the trust deposit of a specific authority 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

• authority (group) (mandatory): authority owner 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 entry td for authority.

  • if td does not exist:
    • if augend is negative, transaction MUST abort.
  • else
    • if augend is negative and td.claimable - augend is greater than td.deposit transaction MUST abort. (td.claimable trust deposit cannot be greater than td.deposit).

§ [MOD-TD-MSG-1-2-2] Adjust Trust Deposit fee checks

• Fee payer the transaction MUST have the required estimated transaction fees in its account

Additionally:

• load TrustDeposit entry td for authority.

• if td exists:

  • if augend is positive:
    • calculate needed_deposit = augend - td.claimable.
    • if needed_deposit < 0: needed_deposit = 0.
  • else needed_deposit = 0.

• else needed_deposit = augend.

• authority MUST have needed_deposit in its account, 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 entry td does not exist for this authority, create entry td:

  • transfer augend from authority account to TrustDeposit account.
  • calculate augend_share = augend / GlobalVariables.trust_deposit_share_value.
  • set td.authority to authority;
  • set td.deposit to augend;
  • set td.share to augend_share;
  • set td.claimable to 0.
  • set td.slashed_deposit to 0.
  • set td.repaid_deposit to 0.
  • set td.slash_count to 0.

• else if td.slashed_deposit > 0 and td.repaid_deposit < td.slashed_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 to td.claimable - augend
    • else
      • use bank? to transfer augend - td.claimable from authority account to authority TrustDeposit account.
      • set td.deposit to td.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 to td.share + missing_augend_share

  • else

    • use bank? to transfer augend from account to TrustDeposit account.
    • calculate augend_share = augend / GlobalVariables.trust_deposit_share_value.
    • set td.deposit to td.deposit + augend
    • set td.share to td.share + augend_share

• else if augend < 0:

  • set td.claimable to td.claimable - augend

The last case, augend < 0, is to free trust deposit (ej when canceling a validation process).

§ [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.

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, it can be claimed.

§ [MOD-TD-MSG-2-1] Reclaim Trust Deposit Yield method parameters

• authority (group): (Signer) the signing authority on whose behalf this message is executed.
• operator (account): (Signer) the account authorized by the authority to run this Msg.

§ [MOD-TD-MSG-2-2] Reclaim Trust Deposit Yield precondition checks

• authority (group): (Signer) signature must be verified.
• operator (account): (Signer) signature must be verified.
• [AUTHZ-CHECK] MUST pass for this (authority, operator) pair and this message type.

§ [MOD-TD-MSG-2-2-1] Reclaim Trust Deposit Yield basic checks

• Load TrustDeposit entry td from authority.
• if td.slashed_deposit > 0 and td.repaid_deposit < td.slashed_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.