Skip to main content

States

The module keeps its state in the following collections (see x/vcv/keys.go and x/vcv/keeper/keeper.go):

Authority​

The address that is allowed to update the module Params via MsgUpdateParams. In Dchain this is the gov module address. Note that the authority only governs the module parameters; individual routes are managed by each route's own admin (see messages).

Params​

Params (d.vcv.v1.Params) holds the module-wide parameters:

  • suspicious_threshold: the number of blocks for which a validator may submit a wrong (or intentionally empty) vote-extension VP before it is treated as suspicious and jailed.
  • max_presentation_len: the maximum verifiable presentation length accepted by the verifier. This value is fixed in this Dchain version and cannot be changed via MsgUpdateParams.

Routes​

Routes is a map[routeId]Route that defines, per gated message, the trusted issuers and the requirements a presentation must satisfy.

  • routeId convention: the routeId is the proto message name of the gated message, optionally suffixed with an id using the : divider. Examples: cosmos.staking.v1beta1.MsgCreateValidator, cosmos.gov.v1.MsgVote, /d.notary.v1.MsgNotarise:1.

The Route type (d.vcv.v1.Route) is:

message Route {
  string admin = 1;            // address allowed to manage this route's issuers/requirements
  RouteType typ = 2;           // ROUTE_TYPE_SD_JWT
  map<string, Issuer> issuers = 3; // keyed by issuer identifier
}

message Issuer {
  repeated Requirement content_requirements = 1;   // requirements on the Msg content
  repeated Requirement extension_requirements = 2; // requirements on the attached extension options
  repeated VerificationMaterial verification_materials = 3; // issuer public keys
}

message VerificationMaterial {
  oneof pubkey { Jwk jwk = 1; }
}

message Jwk {
  string kty = 1;
  string crv = 2;
  string x = 3;
  string y = 4;
}

message Requirement {
  string attribute = 1;   // the disclosed claim name
  Criterion criterion = 2;
}

message Criterion {
  oneof criterion {
    StringCriterion string_criterion = 1;
    NumberCriterion number_criterion = 2;
    FloatCriterion float_criterion = 3;
    BooleanCriterion boolean_criterion = 4;
    ExpiresCriterion expires_criterion = 5;
    NotContainedInCriterion not_contained_in_criterion = 6;
  }
}

enum RouteType {
  ROUTE_TYPE_UNSPECIFIED = 0;
  ROUTE_TYPE_SD_JWT = 1;
}

Each Criterion carries an operator that defines how the disclosed claim is compared against the expected value:

  • StringCriterion: STRING_OPERATOR_EQUALS, STRING_OPERATOR_CONTAINS.
  • NumberCriterion: NUMBER_OPERATOR_EQUALS, NUMBER_OPERATOR_GREATER_THAN, NUMBER_OPERATOR_LESS_THAN.
  • FloatCriterion: FLOAT_OPERATOR_EQUALS, FLOAT_OPERATOR_GREATER_THAN, FLOAT_OPERATOR_LESS_THAN.
  • BooleanCriterion: BOOLEAN_OPERATOR_IS_TRUE, BOOLEAN_OPERATOR_IS_FALSE.
  • ExpiresCriterion: EXPIRES_OPERATOR_EXPIRES_IN, EXPIRES_OPERATOR_EXPIRES_AT.
  • NotContainedInCriterion: asserts the disclosed value is not contained in the configured set.

Suspicious Validators​

SuspiciousValidators is a map[consAddress]SuspiciousValidator tracking validators that have repeatedly submitted an incorrect or empty vote-extension VP. Once a validator's counter reaches the suspicious_threshold, the module jails it (see the BeginBlocker / jail.go path). Each entry holds the validator consensus address, a counter, and the validator power.