Credentials

Credentials are signed attestations by an issuer. While it supports legacy credential types, Holonym has a standard format for such credentials designed for simplicity and efficiency in a ZKP.

Holonym Standard Credential FOrmat

A leaf is an element of a Merkle tree. Merkle trees allow for efficient and anonymous proofs of set membership in zero-knowledge. Leaves are Poseidon hashes of 6 254-bit field elements:

Index	Name	Description
0	Issuer Address	The Ethereum address of the credential issuer, i.e. who provided this attestation
1	Nullifier Secret	A secret used to create nullifiers
2	Issuer-defined field	Can be used for anything the issuer wants
3	Issuer-defined field	Can be used for anything the issuer wants
4	iat	Unix timestamp in seconds when the credential was issued at
5	Scope	Default to 0 (wildcard) indicating it can be used anywhere. This field is mostly deprecated and is not used anywhere.

Note that while credentials can only have 2 issuer- fields, nothing prevents these fields from representing more: they can be set to the hash of unlimited custom fields

Nullifier Secret

The nullifier secret is a value that only the user knows. Because it is pseudorandom, the preimage of the leaf cannot be guessed without at least brute-forcing the secret, which is infeasible at 16 bytes. Thus, even if the other fields are predictable, the credential will still be anonymous without knowing the secret. In this way, it acts as a pepper, obscuring the preimage from the publicly known digest.

It also has a particular property allowing for sybil resistance: credentials can be spent for a specific use case by publishing a salted hash of the secret pepper. We refer to this as a hashbrown because it is a mixture of salt & pepper. Accurate computation of the hashbrown can be verified in a ZKP without revealing the pepper. Some use cases of involve anonymous reputation, anonymous voting, bot prevention, and fair airdrops. For example

Whenever a user votes in an election with actionID abc123, they must publish hash(abc123, secret) . And they generate a proof that the result came from abc123 and secret . This hash then gets added on-chain, so the user can never vote again without people seeing they're trying to "double-spend" their secret.

Leaf Formats of Holonym Foundation Issuers

Holonym Foundation provides two issuers, though others are encouraged to create more issuers.

Government ID Issuer

Index	Name	Description
0	Issuer Address	The Ethereum address of the credential issuer, i.e. who provided this attestation
1	Nullifier Secret	A secret used to create nullifiers
2	Country	This is a number corresponding to the user's country. Countries are numbered based on a custom accumulator scheme. This allows them to be used in efficient ZK arguments of presence in allowlists of countries.
3	Additional Info	Poseidon hash of: Name, city, state/province, street, zipcode
4	Time of credential issuance	Represented as seconds since 1900 (unix timestamp with -70yr offset)
5	Scope	0

Phone Issuer

Index	Name	Description
0	Issuer Address	The Ethereum address of the credential issuer, i.e. who provided this attestation
1	Nullifier Secret	A secret used to create nullifiers
2	Phone Number	Phone number in E.164 but without the leading + so it can be converted to a field element. E.g., [phone] becomes 15555555555
3	Empty	0
4	iat	Day the credential was issued at, in days since 1900/01/01
5	Scope	0