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 two artifacts leave your infrastructure, which never do, and which claims a proof can and cannot back. Trusset never sees or hashes your customers’ KYC data. You run the trusset-kyc-zk-proofs tool on your own infrastructure, and only two artifacts from its output ever reach Trusset:

The root hash (kycHash) - a Rescue-Prime Merkle root over per-field commitments, stored on-chain by identity.verify.
The bundle manifest (manifest.json) - hashes and public inputs only, used by identity.addClaimsFromProof to derive on-chain claims.

Names, birth dates, and document data stay on your machine. The proofs themselves (proofs/*.bin) and the encrypted witness material (secrets.enc) are never uploaded.

Run the proof tool

The tool is a separate repository you clone and run locally. It reads subject rows from /input (JSON or CSV) and writes one proof bundle per subject. Clone and configure it:

git clone https://github.com/Trusset/trusset-kyc-zk-proofs
cd trusset-kyc-zk-proofs
npm install
cp config.example.json config.json
export TRUSSET_KYC_MASTER_KEY=$(openssl rand -hex 32)
export TRUSSET_KYC_SIGNING_KEY=$(openssl rand -hex 32)

Place your customer rows in /input, then run it:

npm start

output/
├── 0xAbCd.../                       # one bundle per subject wallet
│   ├── kycHash.hex                  # the root hash (0x + 64 hex chars)
│   ├── manifest.json                # signed manifest: root hash + proof leaves
│   ├── manifest.sig                 # ed25519 signature
│   ├── proofs/<field>.bin           # zk-STARK proofs - keep local
│   └── secrets.enc                  # encrypted witnesses - keep local, never upload
└── kyc_hashes_<timestamp>.csv       # batch index: one row per subject

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

secrets.enc and proofs/*.bin must never leave your infrastructure. Trusset endpoints only accept the manifest (hashes and public inputs) and the root hash.

Stub vs production manifests

Each manifest carries a mode. production manifests are accepted everywhere. stub manifests (CI smoke mode, --skip-proofs) are accepted by development instances only - a production instance rejects them with STUB_NOT_ALLOWED.

From bundle to verified customer

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 hash on-chain, the manifest can back on-chain claims. The backend re-checks that the manifest’s kycHash matches the on-chain identity before adding anything.

const claims = await trusset.customers.identity.addClaimsFromProof({
  walletAddress: manifest.walletAddress,
  manifest,
})

claims.added counts what landed, and claims.claims holds one entry per claim as { claimType, 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. getClaims returns the active claims with their data hashes and expiries.

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`

AML, TAX_RESIDENCY, SANCTIONS_CHECK, and PEP_CHECK are not proof-backed - add them with addClaim.

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.

Troubleshooting

Error code	Meaning	Fix
`NOT_VERIFIED`	The wallet has no on-chain identity yet	Run `verify` / `verifyFromManifest` first
`HASH_MISMATCH`	Manifest root hash differs from the on-chain hash	Re-verify with this manifest’s `kycHash`, or use the bundle that matches the chain
`WALLET_MISMATCH`	Manifest belongs to a different wallet	Use the bundle generated for this wallet
`STUB_NOT_ALLOWED`	Stub-mode manifest on a production instance	Re-run the tool without `--skip-proofs`
`INVALID_MANIFEST`	Malformed or incomplete manifest	Pass the unmodified `manifest.json` object
`INVALID_HASH`	`kycHash` is not a 32-byte hex string	Use the exact value from `kycHash.hex`
`NO_SELECTED_CLAIMS`	`selected` names claim types this proof cannot back	See the claim derivation table above

Getting Started

Customers

KYC Proofs

Run the proof tool

Stub vs production manifests

From bundle to verified customer

Which claims a proof can back

Onboard in batch

Troubleshooting

​Run the proof tool

​Stub vs production manifests

​From bundle to verified customer

​Which claims a proof can back

​Onboard in batch

​Troubleshooting

Run the proof tool

Stub vs production manifests

From bundle to verified customer

Which claims a proof can back

Onboard in batch

Troubleshooting