upgrade Trusted Issuer List

[bluesteens]

Steering summary

Spherity has built an Ethereum-based smart contract-based trusted credential issuer registry. In principle, this registry is functional and ready for use by the intended ecosystem and managed by trusted entities. However, with knowledge gained since its release, we have realized that the existing MVP requires changes based on needs of the ecosystem. This is part of OCI's continuous improvement.

Updated assessment following architectural and development work

Aspect	TI List v1 (current)	TI List v2 (proposal)	Comment
Smart contract	Ethereum-based	Ethereum-based	no change in general tech approach
Upgradability	requires new contract, thus hassle for wallets	upgradeable w/o changes by wallet; hassle-free
Granularity	1 simple issuer list	possibility to distinguish which issuer can issue which VC type via parallel lists
Delegation	not possible	possible	enable other entities to work with (delegate) or for (meta transactions) OCI on a shared trusted issuer list
Voting	custom-code	3rd party provider	increases security, changes Statekeeper workflow
Owner Change	not possible	list can be handed over to new "managing entity"
List Freeze	not possible	can pause entire list to prevent unwanted changes like DID addition, e.g. in case of suspicious action
List Revocation	not possible	can revoke entire lists w/o impact on re-verifiability
Batching	not possible	possible to do bulk actions in one transactions	decrease transaction costs
UX	OK	slicker	direct integration of ledger w/out need of Metamask; Safe as complete managing solution
Longevity	would have needed improvements, thus migration	more future-proof than v1 due to upgradeability, community-involvement, 3rd party service for voting
Community	released to OCI community	released to OCI and Ethereum communities	the larger the community, the more likely it is to receive new ideas and optimizations

---

Envisaged improvements

Upgradability

• There is no upgrade mechanism for the trusted issuer registry contract. This means that an upgrade will result in a new contract, which represents an inconvenience for implementers regarding data migration and its implications.
• The difficult upgrade process of the smart contract also discourages changes to the trusted issuer registry and, thus, slows down its adaptability to future requirements.

  Granularity

• The registry does not cater for the distinction between different trusted issuers being able to issue different credential types. Such added granularity would help automate the issuer check by the verifier.
• Further universal metadata can be stored alongside the trusted issuer information

  Delegation

• Meta transactions are not possible, which reduces usage flexibility and user experience. This empowers inexperienced users to manage trusted issuers through web3-enabled platforms. Meta transactions enable an actor to carry out transactions on behalf of someone else's wallet as long as the signer of the transaction can prove they have access to the private key material of the current owner of the identity.
• New possibility of collaborating on a shared trusted issuer list by adding delegates to a list

  UX

• Trusted issuers are represented by their DID hash and can be found in lists identified by their hash of a credential type schema URL. These are not human readable and aren’t necessarily resolvable for a frontend laying out the trusted issuers. Additional clear text versions for those use cases can be stored as metadata alongside the trusted issuers.
• Improved user experience of MVP’s dApp user interface

Scope of work

• [x] - Define new requirements based on contract limitations and further needs
• [x] - Research alternative smart contract approaches and technological solutions for requirements
• [x] - Develop draft specification and proposal to OCI
• [ ] - Creation of new smart contract, libraries, and test suites
• [ ] - Finalize smart contract specification, implementation

Projected impact on ecosystem player & OCI Statekeepers:

Wallet

• Change API contract address, change ABI (app binary interface) - both copy-paste
• The following changes have to be done by digital wallets:

  const did = "did:example:example";
  const isTrustedIssuer = await contract.isTrustedIssuer(did);

to something like this

const ociAddress = "0x.....";
const schemaUrl = "https://open-credentialing-initiative.github.io/schemas/credentials/IdentityCredential-v1.0.0.jsonld";
const did = "did:example:example";
const isTrustedIssuer = await contract.isTrustedIssuer(ociAddress, schemaUrl, did);

VRS

• no impact

  Issuer

• no impact

  Trading Partner

• no impact

  Statekeeper

• voting behaviour changes - existing frontend will be adapted to be more user-friendly (but wanted to make it more user-friendly anyway) -> See Gnosis Safe

[bluesteens]

• [x] Is Issue appropriate for OCI Architecture
• [x] Create Steering-level Summary of request
• [x] Assign Size
• [x] Assign Priority
• [x] Assign Label (if needed)
• [x] OCI affected Artifacts Identified
• [ ] Assign Triage - Artifact Version Target (v x.x.x Milestone)
• [ ] Assign Triage - Interop Profile Version Target (v x.x.x Milestone)
• [ ] Create sub-project (if needed)

Affected Parties (help determine Sunrise/Sunset):

• [ ] Trading Partners
• [ ] Issuers
• [x] Wallet Solutions
• [ ] PI Verification Solutions

Affected OCI Artifact

• [ ] Schema Document
• [ ] Identity Schema
• [ ] ATP Schema
• [ ] Issuer Conformance Criteria
• [x] Wallet Conformance Criteria
• [ ] VRS Solution Conformance Criteria
• [ ] Wallet API Specification
• [x] Governance Document
• [ ] Conformance Program
• [ ] OCI Website
• [x] Internal Process
• [x] trusted issuer list

Change Category (Guides Steering Review)

• Steering/Industry Review

• [ ] Business-Level (May affect business operations)

• [x] OCI Governance, Policy or website feature

• Steering/Industry Notification

• [ ] Technical-Level (Does not affect business operations)

• [ ] OCI Internal Process or Infrastructure

Communication

• [ ] Website
• [ ] Newsletter
• [ ] email:
• [ ] Other:

[strumswell]

General

Spherity is proposing to enhance the currently implemented MVP. To summarise possible improvements and requirements:

• Upgradability: New features and bug fixes can't be made without changing the smart contract address.
• Security: The current implementation of the voting procedure for adding statekeepers is custom-written and not audited by a security firm.
• Granularity: There is a need to define trusted issuers on a credential type level.
• Platform features: Support delegation and meta transactions that allow statekeepers to let another entity take writing actions in their name.

Spherity has been given a grant by the Ethereum Foundation to create a general specification and library for the Ethereum community for this specific problem. A first draft can be found here. We propose to use this as the basis for an upgraded trusted issuer solution.

Proposed Solution

About the Trusted Hint Registry

The new specification mentioned above describes a trusted hint registry.

A hint is a metadata snippet that describes key attributes related to verifiable data or identities. These hints provide insights, aiding in the interpretation, reliability, and verifiability of decentralized ecosystem data. Hints can be used for multiple purposes, like revocation data, timestamping offline data, or trusted issuer information.

In this registry, an Ethereum address (namespace) owns a space of bytes32 hint lists. In those hint lists, any given bytes32 hint key can point to a bytes32 hint value. The structure is visualised below.

hint registry
├─ namespace
│  ├─ hint list 0
│  │  ├─  hint key 0
│  │  │   ├─  hint value
│  │  ├─ hint key x
│  │  │   ├─  hint value
│  ├─ hint list 1
│  │  ├─  hint key 0
│  │  │   ├─  hint value
... ... ... ...

The specification also describes a set of management features:

• An Ethereum address can invite other addresses (delegates) to one or more of their hint lists in their namespace.
• An Ethereum address can change the ownership of one or more of their hint lists to a new Ethereum address.
• A hint list owner/ delegate can use meta transactions to enable a third party to carry out transactions for them.

Apply the Trusted Hint Registry to OCI

To apply this to the OCI needs, we propose to do the following:

1. Swap voting feature for user-friendly multi-signature wallet (user-facing)

Instead of implementing a custom audited voting process, we can resort to user-friendly multi-sig wallets. These wallets allow multiple existing wallets to be part of an organisational wallet. In there, every action, e.g., adding a trusted issuer, needs to reach a certain quorum by the participating wallets (statekeepers) before the multi-sig wallet carries out an action for them. So multiple signatures are needed before an action can be taken, which is comparable to typical internal processes in enterprises. We propose to use the usage of Gnosis Safe as they provide a user-friendly multi-sig wallet reachable via the web with all the invitation and voting features needed for OCI. OCI statekeepers will still need hardware wallets to use Safe.

2. Usage of registry data structure (developer-facing)

As described earlier, the data structure is hierarchically organised into namespaces, hint lists, hint keys, and their hint values.

• namespace: The namespace should be the address of the multi-sig wallet, as all writing actions shall be carried out by it after voting has happened by the participating statekeeper wallets.
• hint list: This can be any arbitrary bytes32 value. We suggest the Keccak-256 hash of the credential schema URL for now. For https://open-credentialing-initiative.github.io/schemas/credentials/IdentityCredential-v1.0.0.jsonld this would be 0x1825a61b3b384c564efb355d7aee9ef08d663bb59b5d308146fcaeaa4a1de1ff.
• hint key: This can be any arbitrary bytes32 value. We suggest the Keccak-256 hash of the issuer's DID. We are still actively discussing, if we want to store a bytes representation of the DID instead of its hash to make decoding of the written value possible.
• hint value: This can be the bytes32 representation of a boolean indicating if the hint key is trusted or not.

The structure can be visualised like so:

hint registry
├─ 0x..... (OCI address)
│  ├─ 0x1825a61b3b384c564efb355d7aee9ef08d663bb59b5d308146fcaeaa4a1de1ff (https://open-credentialing-initiative.github.io/schemas/credentials/IdentityCredential-v1.0.0.jsonld)
│  │  ├─  68bc8ca5d3b25b356cac4918838a92e284e06653081c2b8fd296250aab79a26f (did:example:example)
│  │  │   ├─  0x0000000000000000000000000000000000000000000000000000000000000001 (true)
... ... ... ...

3. Trusted issuer checks in digital wallets (developer-facing)

We propose to offer two methods that a digital wallet can call:

1. low-level: getHint(address _namespace, bytes32 _list, bytes32 _key) external view returns (bytes32); With this one, the digital wallet needs to do the hashing operations outlined above itself to get the trust status of an issuer DID in a specific credential schema URL.

2. high-level: isTrustedIssuer(address _namespace, string _contextUrl, string _issuerDid) external view returns (bool); With this one, the digital wallet only needs to provide the OCI multi-sig address, credential schema URL string, and issuer DID string.

With the high-level method, wallets need to change their contract calls from this

const did = "did:example:example";
const isTrustedIssuer = await contract.isTrustedIssuer(did);

to this

const ociAddress = "0x.....";
const schemaUrl = "https://open-credentialing-initiative.github.io/schemas/credentials/IdentityCredential-v1.0.0.jsonld";
const did = "did:example:example";
const isTrustedIssuer = await contract.isTrustedIssuer(ociAddress, schemaUrl, did);

4. Subscribing to registry changes (developer-facing)

The new contract emit events on the blockchain for various actions happening in the registry. One of them is the HintValueChanged event that is being emitted whenever a hint value in the registry changes somewhere.

With an open web socket connection, the digital wallet can subscribe to HintValueChanged events happening in the OCI address namespace and create a local cache of the values inside of it. It can persist the credential type context URL hash (hint list), the DID hash (hint key), and the bytes32 representation of the bool defining if that DID is now trusted or not from now on.

With every incoming verification or generation call, the digital wallet can then generate Keccak256 hashes of the credential type context URL and issuer DID and check against cached values. This way, wallets can spare on further external calls to an Ethereum wallet with every verification or generation, reducing further latency from calls to the wallet APIs.

[strumswell]

[bluesteens]

P&A call 12/7/23 - Next steps:

• wallets adjust code
• Statekeepers training
• list deployment on ETH Sepolia testnet
• list deployment on ETH mainnet
• add issuer DID

[rceleste125]

Approved by Steering 2024-01-29