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 a marker using the : divider. Examples: cosmos.gov.v1.MsgVote:extop, /d.notary.v1.MsgNotarise:content: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 committed a block with an empty or invalid 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.

How suspicious counters are derived​

Counters are derived from the ExtendedCommitInfo that the block proposer injects as tx[0] (MsgExtendedProposalTxn.extended_commit_info). The key security property is that every validator's vote-extension bytes in that structure are accompanied by a consensus-key signature over a CanonicalVoteExtension, which ProcessProposal authenticates via baseapp.ValidateVoteExtensions (per-vote signature check, >2/3 total commit power, and an exact pin against the node's own ProposedLastCommit) before accepting the block. The PreBlocker then re-authenticates the same bytes and recomputes the suspicious set independently. A validator can therefore never be accused of vote-extension bytes it did not sign with its consensus key.

The counter-update flow is:

  1. ProcessProposal authenticates the injected ExtendedCommitInfo. Blocks whose commit fails validation are rejected before they reach the PreBlocker.
  2. In the PreBlocker, the authenticated commit is unmarshaled and re-validated. For each BlockIDFlagCommit vote, the validator is checked: an empty extension, or one whose VP fails verification, marks it as suspicious. The stored entry's counter is incremented by 1 and its power is overwritten with the value from the verified commit — not kept from the first offense. Because each validator appears at most once per commit, the counter moves at most +1 per block regardless of what the proposer put on the wire. Any data-shaped failure in the PreBlocker is logged and skipped; the PreBlocker must never halt the chain on block content.
  3. In the module BeginBlocker (same block as the increment that crosses the threshold), the validator is slashed with the stored power and an infraction height of height - ValidatorUpdateDelay - 1, then jailed. This matches the x/slashing downtime convention: the infraction is treated as continuous and priced at its latest occurrence.

Power snapshot semantics​

The power field exists because the staking slash call (SlashWithInfractionReason) requires the validator's voting power at the infraction, not at jail time — the slash amount is power × PowerReduction × SlashFractionDowntime, and the SDK uses the infraction-height power to also reach stake that has since been unbonded or redelegated.

Consequence: if a validator's power changes while the counter accumulates (e.g. suspicious_threshold = 5 and stake is unbonded between the first and fifth flagged block), the slash is computed from the power at the last flagged block. Stake that began unbonding before that block escapes the slash entirely, since it predates the recorded infraction height. This is the same trade-off upstream downtime slashing accepts: the downtime slash fraction is small, unbonding still takes the full unbonding period, and the jail itself is the primary deterrent.