Flow of Data

Deprecated: New Architecture Coming Soon

The Holonym system consists of the following components.

• Client (website or mobile app).

• Issuer servers.

  • Government ID issuer.

  • Phone number issuer.

• Hub smart contracts (1 per chain).

• Relayer server.

The flow of data is outlined in the action sequence described in the Actions section. The following describes the flow of data in more detail. The diagram illustrates the issuance+storage (designated by 1.*) and proving (designated by 2.*) steps. An organization can grant access to users based on the results stored in the proof contract.

Holonym V2 architecture. NOTE: Holonym is transitioning to V3 architecture which is substantially different

1.1. User verifies themself. The verification process involves the use of a 3rd party identity provider, such as Veriff. To verify using government ID, the user must scan their ID documents to submit to the identity provider.

1.2. The issuer retrieves the credentials from the identity provider, signs a hash of the credentials with a secret generated by the issuer, deletes the credentials from the identity provider's servers, and sends the signed credentials to the user. We call the hash of the credentials a "leaf" because it becomes a leaf in the Merkle tree.

1.3. User generates a new secret, generates a proof that the hash with the new secret uses the same credentials that were in the hash from the issuer, and sends the proof and new hash to the relayer.

1.4. Relayer verifies the proof and, if the proof is valid, stores the leaf in a Merkle tree. It also updates the Merkle root in the Roots contract so that Merkle proofs can be publicly verified. The relayer is used so that (a) the user does not need to pay gas for the transaction and (b) the user does not associate their blockchain address with their leaf.

1.5. User encrypts their credentials client-side. The encryption key is generated from the user's signature. If the user loses access to the private key used to generate the signature, they could lose their ability to decrypt their credentials.

1.6. User stores their encrypted credentials in (a) browser storage and (b) in a Holonym database. At this point, the user can start generating proofs.

2.1. User submits a proof (e.g., a proof that they are a US resident) to the appropriate proof contract.

2.2. The proof contract verifies that the Merkle root used in the proof is a recent root.

2.3. The proof contract verifies the proof. After verification, the proof contract stores the proof result in a mapping of address to result, where result is an integer or boolean value.