Trusset Protocol - Infrastructure for Asset Tokenization

This page is for the engineer running KYC in-house who needs verified customers on-chain. After reading it you will know which artifacts leave your infrastructure, which never do, and which claims a proof can and cannot back. You run the trusset-kyc-zk-proofs tool on your own machines. It reads your KYC records and writes, per subject, a Merkle root to publish on chain, one zk-STARK per proved field, and a manifest signed with your operator key.

What leaves your infrastructure

Trusset never sees the underlying KYC data. Names, birth dates, nationalities and document numbers stay on your machine, and no endpoint accepts them. What does travel is the evidence that a predicate held:

Artifact	Sent	Why
`kycHash` (the root)	Yes	Published on chain by `identity.verify`
`manifest.json`	Yes	Hashes, public inputs and claim descriptors
`manifest.sig`	Yes	Checked against your registered operator key
`proofs/*.bin`	Yes, on a production instance	The STARKs are verified server-side before a claim is filed
`secrets.enc`	Never	Encrypted witness material. No endpoint accepts it

A production instance requires the STARK bytes and verifies each one before filing a claim. Sending only the manifest is refused with PROOF_MISSING.A commitment carries no value and a STARK reveals nothing beyond the predicate, so uploading them discloses no personal data. secrets.enc is the file that would, and it is never accepted. Keep it and your .trusset/keys.env on your own machines.

Enforcement depends on the instance

Two settings decide how strict a submission is judged, and they are not the same field. A PRODUCTION instance requires proofs and rejects stub manifests, whatever the instance itself is set to. A DEVELOPMENT instance does neither by default, which is what makes a structural dry run possible without generating STARKs. An instance can also opt in on top of that. Read both from Get Operator Key: proofVerificationEnabled is what you asked for, proofVerificationEnforced is what a submission is actually judged against. Gate on the enforced flag.

Run the proof tool

git clone https://github.com/Trusset/trusset-kyc-zk-proofs
cd trusset-kyc-zk-proofs
npm install
npm run init

init asks four questions about your institution, generates both keys, pins the batch date, and prints your operator public key. Load the keys, drop records in input/, and run it:

set -a && . ./.trusset/keys.env && set +a
npm start -- --dry-run
npm start

output/
├── 0xAbCd.../                       # one bundle per subject wallet
│   ├── kycHash.hex                  # the root hash (0x + 64 hex chars)
│   ├── manifest.json                # what was asserted, by whom, on what evidence
│   ├── manifest.sig                 # ed25519 over a canonical view of the manifest
│   ├── proofs/<field>.bin           # one STARK per proving leaf
│   └── secrets.enc                  # encrypted witnesses - keep local
└── kyc_hashes_<timestamp>.csv       # batch index: one row per subject

The root hash appears in three places and they are the same value: kycHash.hex, the kycHash field of manifest.json, and the kycHash column of the batch CSV.

init pins the batch date into config.json. Leave it pinned. Every per-subject key and commitment derives from that number, so a bundle proved against a moving clock cannot be reproduced tomorrow, which is exactly what an auditor asks for.

From bundle to verified customer

Every manifest signature is checked against this key. Take the value npm run show prints.

await trusset.customers.identity.setOperatorKey({
  publicKey: 'd75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a',
  maxStalenessDays: 365,
})

Rotating it later does not re-verify anything already filed. Claims added under the old key stay on chain, and their manifests no longer verify against the new one. Keep the old key with the bundles it signed.

Verify on-chain with the root hash

Load the bundle’s manifest.json and call verifyFromManifest. The wallet address, root hash, country, investor type, and expiry days are read straight from the manifest; pass overrides for anything you want to change.

import { readFileSync } from 'node:fs'
import type { KycProofManifest } from '@trusset/sdk'

const manifest: KycProofManifest = JSON.parse(
  readFileSync('output/0xAbCd.../manifest.json', 'utf8'),
)

const result = await trusset.customers.identity.verifyFromManifest(manifest)

result.kycHash equals manifest.kycHash once the root hash is on-chain. result.operation is verify for a new identity and update for an existing one.If you only stored the root hash (for example from the batch CSV), call verify directly with kycHash:

await trusset.customers.identity.verify({
  walletAddress: '0xAbCd...',
  country: 'DEU',
  investorType: 'PROFESSIONAL',
  kycHash: '0x591aa0f6...',
  softExpiryDays: 365,
  hardExpiryDays: 730,
})

Add proof-backed claims

With the root on chain, the bundle can back claims. Send the signature and the STARKs alongside the manifest.

const bundle = 'output/0xAbCd...'

const claims = await trusset.customers.identity.addClaimsFromProof({
  walletAddress: manifest.walletAddress,
  manifest,
  manifestSig: readFileSync(`${bundle}/manifest.sig`, 'utf8').trim(),
  proofs: {
    country: readFileSync(`${bundle}/proofs/country.bin`).toString('base64'),
    nationality: readFileSync(`${bundle}/proofs/nationality.bin`).toString('base64'),
  },
})

claims.added counts what landed, and claims.claims holds one entry per claim as { claimType, dataHash, status, txHash }. One transaction is sent per claim. Use selected: ['KYC'] to add a subset.

Check the result

status.onChain.isVerified is now true and status.onChain.kycHash matches the manifest.

const status = await trusset.customers.identity.getStatus(manifest.walletAddress)

const { claims } = await trusset.customers.identity.getClaims(manifest.walletAddress)

Which claims a proof can back

The KYC claim always derives from the root hash. Field-level claims derive from the manifest’s proof leaves:

Claim type	Derived from	Circuit
`KYC`	the root hash itself	`merkle_root`
`RESIDENCY`	`country` leaf	`set_membership`
`CITIZENSHIP`	`nationality` leaf	`set_membership`
`ACCREDITATION`	`investorType` leaf	`tier_threshold`

A canonical field proved with a different circuit is skipped rather than filed elsewhere. A country leaf proved with preimage_knowledge backs nothing, because filing it under another slot would let it read as an unrelated attestation. AML, TAX_RESIDENCY, SANCTIONS_CHECK, and PEP_CHECK are not proof-backed. Add them with addClaim. Those four are also the only slots a leaf with no canonical meaning may be filed under.

Re-proving a subject

Re-running the tool always produces a new root, because the batch date is bound into every leaf hash. The bundle is legitimate and supersedes the registered one, but its root no longer matches what the registry holds. addClaimsFromProof refuses that with HASH_MISMATCH. Rotating the registered root to the new bundle is a separate, opt-in operation: see Attest Proofs, which takes the rotation transaction alongside the claims.

Onboard in batch

The tool’s batch CSV maps row-for-row onto batchVerify entries - up to 500 subjects in one on-chain transaction:

await trusset.customers.identity.batchVerify(rows.map(row => ({
  walletAddress: row.walletAddress,
  country: row.country,
  investorType: row.investorType,
  kycHash: row.kycHash,
  softExpiryDays: Number(row.softExpiryDays) || undefined,
  hardExpiryDays: Number(row.hardExpiryDays) || undefined,
})))

Addresses that are already actively verified are skipped on-chain (their existing root hash is kept); revoked identities are re-verified. Claims still go one bundle at a time, because each one carries its own proofs.

Troubleshooting

Error code	Meaning	Fix
`NOT_VERIFIED`	The wallet has no on-chain identity yet	Run `verify` / `verifyFromManifest` first
`WALLET_MISMATCH`	Manifest belongs to a different wallet	Use the bundle generated for this wallet
`ROOT_MISMATCH`	The root recomputed from the leaves does not equal the one the manifest states	The bundle is inconsistent. Re-run the tool rather than editing the manifest
`HASH_MISMATCH`	Manifest root differs from the on-chain root	A newer bundle. Rotate the root, or use the bundle that matches the chain
`UNREGISTERED_OPERATOR_KEY`	No operator key on this instance	Register it with `setOperatorKey`
`INVALID_SIGNATURE`	`manifest.sig` is malformed, or signed by a different key	Send the unmodified `manifest.sig` from the same bundle
`PROOF_MISSING`	A claimed leaf has no STARK, or is commitment-only	Send its `proofs/<field>.bin`. A commitment-only leaf cannot be attested under enforcement
`PROOF_INVALID`	A STARK failed verification	Re-run the tool. Do not hand-edit anything in the bundle
`PROOF_STALE`	The batch date is older than `maxStalenessDays`	Re-prove the subject, or raise the bound deliberately
`PROOF_TOO_LARGE`	One proof, or the payload, is over the size cap	Send fewer leaves per call
`CIRCUIT_MISMATCH`	A canonical field was proved with the wrong circuit	Fix the predicate in `config.json` and re-prove
`UNAPPROVED_PARAMS`	The threshold is outside the network’s trust anchors	Use approved parameters
`UNAPPROVED_LIST`	The allowlist the proof committed to is not accepted	Record an approved list version and re-prove
`STUB_NOT_ALLOWED`	Stub-mode manifest where proofs are enforced	Re-run the tool without `--skip-proofs`
`INVALID_MANIFEST`	Malformed or incomplete manifest	Pass the unmodified `manifest.json` object
`NO_SELECTED_CLAIMS`	`selected` names claim types this proof cannot back	See the claim derivation table above
`VERIFY_BUSY`	Verification capacity is saturated	Retry shortly. Nothing was cached
`VERIFY_TIMEOUT`	Verification did not finish in time	Retry shortly. Nothing was cached

A verdict is stored against the bundle, so re-submitting the same bundle answers from the recorded report rather than re-running the STARK verification. verification.cached tells you which happened. A transient VERIFY_BUSY or VERIFY_TIMEOUT is never cached.

Getting Started

Customers

KYC Proofs

What leaves your infrastructure

Enforcement depends on the instance

Run the proof tool

From bundle to verified customer

Which claims a proof can back

Re-proving a subject

Onboard in batch

Troubleshooting

​What leaves your infrastructure

​Enforcement depends on the instance

​Run the proof tool

​From bundle to verified customer

​Which claims a proof can back

​Re-proving a subject

​Onboard in batch

​Troubleshooting

What leaves your infrastructure

Enforcement depends on the instance

Run the proof tool

From bundle to verified customer

Which claims a proof can back

Re-proving a subject

Onboard in batch

Troubleshooting