Verax DID Method

Verax Improvement Proposal [VIP-1] - Verax DID Method

Author: @simon.brown

Title: Create a Verax DID method

Type: Verax Improvement Proposal


We propose establishing a DID method for Verax, which would allow attestation to be issued to a DID, instead of to a wallet address. This would give many benefits, including key rotation, mass revocation though revoking the DID instead of the attestation itself, chain agnostic attestation ids, and potential other benefits in the future.

Proposal Summary

Create a did:vrx DID method facilitated through a first-class schema, smart contract functions, and SDK helper functions.

Overview of Proposal

The key elements of this proposal are:

  • create documentation for the did:vrx method
  • create a did:vrx schema and a portal that can issue, revoke and replace them
  • create a smart contract function that can resolve a did internally
  • create a smart contract function that allows users to revoke an attestation issued to their DID.
  • create an SDK convenience methods for creating and resolving did:vrx identifiers
  • create a Universal Resolver driver to resolve did:vrx DIDs

While no clear timelines are proposed, the above scope should be achievable inside of one quarter between multiple contributors, each working on one part, though currently, who works on what is an open question.


As users collect more and more attestations, many of them will be issued to a single address. If this address is compromised, it will very difficult for the user to revoke the various attestations. Some issuers also don’t allow revocation of the attestation itself.

An improvement to the way things are done currently would be to issue the attestations to a DID, which itself is an attestation. If querying the registry via an attestation id, and the subject is a DID of the did:vrx method, the registry can look up the attestation specified as the DID, and can return the address specified in the DID document.

This means that if a user ever loses their private key or if their key is compromised, they can update the address that the attestations were issued to, or simply revoke all attestations issued to that DID, by revoking the DID itself, and also by revoking the attestations as well if they want to.

Note: that part of this proposal is also to allow subjects to revoke any attestation that was issued to them. Though this may be a separate concern, it is one of the motivations behind the proposal, and should be discussed. This would involve allowing the revocation of any attestation who subject is a wallet address, by the owner of the wallet address.

Technical considerations

Compressed Attestation IDs

Ideally we would be able to refer to an attestation like so:


Which would resolve to an attestation with an id of 0x0001000000000000000000000000000000000000000000000000000000045699... on a Verax instance on the correct chain, and would return an attestation, which when decoded against the DID schema would look like:

  "@context": [
  "id": "did:vrx:0x010a5fe9",
  "verificationMethod": [{
      "id": "did:vrx:0x010a5fe9#key-0",
      "type": "EcdsaSecp256k1RecoverySignature2020",
      "blockchainAccountId": "eip155:1:0x89a932207c485f85226d86f7cd486a89a24fcc12"
  "assertionMethod": [{
      "id": "did:vrx:0x01073ab2#key-0",
      "type": "EcdsaSecp256k1RecoverySignature2020",
      "blockchainAccountId": "eip155:1:0x20974C8722622d523438AA265F7188a96309A4bB"

Attestation ID compressed format:

The attestation id 0x010a5fe9 is actually a compressed format of the actual attestation id, which is: 0x00010000000000000000000000000000000000000000000000000000000a5fe9

The compression simply truncates any contiguous leading zeros after the chain id prefix, (in this case 1, i.e. : 0x0001...). Furthermore, the leading zeros before the chain id can be reduced to one, as are the trailing zeros after the chain prefix. When reading the attestation id, the last zero in the id indicates that everything afterwards is the attestation id, which should be cast to bytes32 and the first zero in the attestation id indicate the digits following it, and up to the attestation id, is the chain id.

DID schema

This DID would require an on-chain schema string that looks like:

(string[] context, string id, (string id, string type, string blockchainAccountId)[] verificationMethod), (string id, string type, string blockchainAccountId)[] assertionMethod)

Note: this doesn’t allow for things like different key types, service endpoints etc. so there is scope for considering a slightly more flexible schema.

Expected Timeline

This is an open ended discussion for now, with no definitive voting date or deployment date set.

Design Considerations

When the getAttestation method of the attestation id is called, the specified attestation id should be tested to see if it starts with the substring did:vrx:0 - if it does, then the chain id should be matched against the network the registry is deployed on, and if there is a match, then the did suffix should be decompressed into an attestation id, and this should be retrieved.

It will be expected that the resulting attestation will have a schema id that is the DID schema. The registry should then checked if this attestation has been revoked or replaced. If it has been replaced, then the replacedBy attestation should be looked up, and then this should be checked to see if it has been replaced, and these steps should be repeated recursively until we have a current attestation or a revoked attestation.

When returning the attestation that was given initially, the revoked bit should be set according the status of the final DID attestation that was retrieved.

Deployment Considerations

  • the documentation for the did:vrx method can be created as a markdown document, and then added to GitBook
  • the did:vrx schema and a portal should be created on a testnet first
  • the smart contract function that can resolve a did internally can be created as a standalone contract for testing, and then later ported into the attestation registry
  • to create a smart contract function that allows users to revoke an attestation issued to their DID, will require an upgrade to the core Attestation Registry contract, and this should be carried out on a testnet
  • creating an SDK convenience methods for creating and resolving did:vrx identifiers can simply be developed and tested on a feature branch
  • a Universal Resolver driver to resolve did:vrx DIDs is created as a docker image, and once completed is submitted to the universal resolver website for inclusion

Next Steps

Next steps are for stakeholders to review and comment on this proposal, and suggest any changes or amendments as necessary. Following a period of discussion, then we will need to create user stories for of the deliverables described above. Critically, we will need to agree on when to vote on this proposal in order to proceed with the implementation, especially on the core contracts.

References and Links

Description of EcdsaSecp256k1RecoverySignature2020 Verification Key method


In general it makes sense for the reasons stated in the proposal related to the safety of revoking attestations tied to specific addresses.

I would additionally suggest considering a mechanism to aggregate attestations across different networks via DIDs. So that attestations are not dependent on a particular network.

This way, we can combine all our attestations in different networks (e.g., in our case, scores in different networks) through a single DID. And this data will be available from everywhere.
And then this DID with generalized data within it can be attested in any network, so that this data will also be available and verified by the onchain in concrete blockchain.

This proposal makes sense because it’s very common for users to get their wallets compromised.

However, if revoking the attestation requires the user to pay gas, it could be an issue because often when the wallet is compromised, the drainer is configured on the wallet.

So, the compromised user won’t be able to revoke because the funds would be stolen before he would be able to access the revoke dashboard.

This is quite an interesting idea. So if I understand correctly, what you’re suggesting is that we can issue an attention on say Arbitrum to a DID is registered on say Linea? Is that what you’re suggesting, or something else?

The benefits of doing this are clear, and would greatly improve things from the user’s perspective. There is a technical challenge involved in resolving the attestations. With the proposal as outlined above, an external contract can query the registry with DID, and the registry would look up the DID attestation to see if it has been revoked or replaced, but it won’t be able to do this if the DID attestation is on another chain. We are looking at a mechanism that would actually make this possible, and this could be an interesting use case for it.

This is a really good point, I hadn’t thought of that. In fact, it’s an obvious oversight now that I think about it. The DID should really have two keys, one that is used as the main wallet address that the DID points to, and the other that is used to revoke the DID. The W3C DID spec provisions two types of “verification relationship”: assertionMethod, and verificationMethod. The verificationMethod could be used to revoke the DID, or update the assertionMethod wallet address. Only the assertionMethod address can be updated though, because if the verificationMethod is compromised, the user should be able to use it to revoke the DID.

Do you think this would solve the issue you described?

FYI: I’ve updated the original specification to include the assertionMethod and verificationMethod as described in the last post

Proposal passed:

Position No. Votes
For 11
Against 0
Abstain 0