Ctrlk
Visit Zipwire
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Signer Identity Cross-Referencing

Technical reference for the signerIdentityAttestations Merkle leaf and refUID selection, used across Zipwire's attesting flows (e-sign, timesheet approval, invoicing).

Overview

When a respondent signs a document, a timesheet is approved, or an invoice/settlement/payment is attested, Zipwire looks up whichever prior identity-interesting attestations that account already holds — an ID check, IsAHuman, HasClearAML, or an age tier — and cross-references them against the new attestation. This lets a reviewer see, and independently verify on-chain, what identity evidence stood behind a given action, without Zipwire re-asserting or re-verifying those facts itself. The same "find candidates, choose one for refUID, record all of them in a leaf" logic is shared across every flow that uses it.

Two mechanisms carry this information:

  • EAS refUID — the new attestation's own on-chain refUID field points at exactly one prior attestation (EAS only has one refUID slot per attestation). Only available where that slot isn't already claimed for something else (see Availability by Flow below).

  • signerIdentityAttestations Merkle leaf — a leaf on the attestation's tree (see Understanding Merkle Trees and Proofs) listing every identity-interesting attestation found for the account, not just the one chosen for refUID.

In e-sign, this only applies to the respondent's signing tree — the requestor's file-integrity signing tree does not carry this leaf, since that tree concerns the requestor's own file, not the respondent's identity.

Availability by Flow

Flow
Leaf
refUID

E-sign (respondent signing)

Yes

Yes

Timesheet approval

Yes

Yes

Invoice creation

Yes

Yes

Settlement / payment

Yes

No — refUID is already claimed for lifecycle chaining (settlement → invoice, payment → settlement/invoice)

For invoice creation specifically, the leaf is embedded when the invoice's Merkle tree is first built; the same lookup's refUID is carried alongside the invoice record and claimed later, when the on-chain attestation actually happens, so the leaf's IsReferencedByThisAttestation flag can never disagree with the real on-chain refUID.

How It's Built

1. Find

Zipwire scans the signer's own Idents — the same on-chain-attestation-to-account lookup used elsewhere in the platform — for any attestation whose schema is identity-interesting:

Schema
Priority

Private Data (ID check only — AML-report Private Data is excluded)

0 (highest)

IsAHuman

1

HasClearAML

2

Any age tier (IsThirteen … IsTwentyOne)

3 (lowest)

See Attestation Schemas for the full schema reference. If a signer holds more than one attestation of the same schema, only the freshest (by on-chain creation time) is kept.

2. Choose

At most one candidate is picked as the new signing attestation's refUID, by priority first (ID check beats IsAHuman beats HasClearAML beats age), then freshest wins ties within the same priority. An ID check is preferred because it's the most information-rich piece of evidence available; the others are weaker signals kept only as fallbacks.

3. Record

Every candidate found in step 1 — not just the one chosen for refUID — is written into the signerIdentityAttestations leaf, each entry flagged with whether it's the one referenced by this attestation's on-chain refUID.

Leaf Structure

Fields

Field
Meaning

SchemaName

Human-readable schema name (e.g. Private Data, Is A Human).

SchemaUID

The EAS schema's UID on the stated network.

AttestationUID

The UID of this specific attestation — query this on EAS Scan to verify it independently.

ServiceName

Always EAS today (Ethereum Attestation Service).

Network

The chain the attestation lives on, e.g. base-sepolia.

CreatedAtUtc

When the referenced attestation was created — not when the signing happened.

DocsPath

Relative path (within this GitBook) to the schema's own reference page, so a reviewer can look up what the schema means.

IsReferencedByThisAttestation

true for the single entry (if any) whose AttestationUID was also written to this signing attestation's on-chain refUID. At most one entry per leaf will be true.

Important Notes for Verification

  • This leaf is informational, not verifying. The signing attestation does not itself prove any of the listed attestations are valid, unrevoked, or unexpired — a reviewer must independently query each AttestationUID on the stated Network (e.g. via EAS Scan) to confirm validity. See Verifying Zipwire's Merkle Root Attestations for Developers.

  • Omitted, not empty, when there's nothing to show. If the signer holds no identity-interesting attestations at signing time, the signerIdentityAttestations key is absent from the tree entirely — it is never present as an empty array.

  • refUID is a hint, not a guarantee. Because EAS only exposes one refUID slot, the chosen reference is the best available evidence at signing time by the priority above, not necessarily the most relevant to every downstream use case. Consumers that need a different signal should read the full Attestations array rather than relying on refUID alone.

Related Resources

PreviousThe "Private Data" Attestation: Merkle RootsNextZipwire's Master Attester Wallet Address and Public Key

Last updated