Trusset Protocol - Infrastructure for Asset Tokenization

The sync sub-module handles bulk migration of customer data between your existing systems and Trusset. It is designed for institutions with established customer databases that need to onboard thousands of records without manual entry. Records are mapped by externalId - your system’s unique customer identifier. This key is used for deduplication and conflict resolution across syncs.

Import records

import { SyncRecord } from '@trusset/sdk'

const records: SyncRecord[] = existingCustomers.map(row => ({
  externalId: row.customerId,       // required - your unique ID
  name: row.fullName,
  walletAddress: row.ethAddress,    // optional
  country: row.countryCode,
  investorType: 'RETAIL',
  kycHash: row.kycRootHash,         // root hash from the KYC proof tool
  metadata: { source: 'core-banking', migrationBatch: '2025-Q1' },
}))

const result = await trusset.customers.sync.importRecords(records, {
  batchSize: 50,
  onConflict: 'update',
  onProgress: (done, total) => {
    console.log(`${done}/${total} processed`)
  },
})

result.total    // total records submitted
result.created  // new customers created
result.updated  // existing customers updated
result.skipped  // skipped due to onConflict: 'skip'
result.errors   // array of { externalId, code, message }

The SDK processes records in configurable batches to avoid overloading the API. Each record is matched against existing customers by externalId. If a match is found, the onConflict strategy determines the outcome.

Conflict strategies

Strategy	Behavior
`update`	Overwrites name, country, investorType, walletAddress, and metadata on the existing record. Default.
`skip`	Leaves the existing record untouched. Counted in `result.skipped`.

With on-chain verification

Set verifyOnChain: true to automatically batch-verify imported records that have both a walletAddress and a country. This runs after the database import completes and requires a verified registered wallet on the instance. Each record’s kycHash (the root hash from the KYC proof tool) is passed through to the on-chain verification, so proof-backed claims can be added later.

const result = await trusset.customers.sync.importRecords(records, {
  onConflict: 'update',
  verifyOnChain: true,
  verificationDefaults: {
    softExpiryDays: 365,
    hardExpiryDays: 730,
  },
})

On-chain verification failures do not roll back the database import. Failed verifications appear in result.errors with code VERIFY_FAILED.

Show SyncOptions reference

number

default:50

Records per API call. Range: 1-200. Higher values reduce HTTP overhead but increase per-request latency.

string

default:"update"

update or skip. Determines behavior when a customer with the same externalId already exists.

boolean

default:false

If true, batch-verifies addresses on the IdentityRegistry after import. Only applies to records with both walletAddress and country.

object

Default softExpiryDays and hardExpiryDays for on-chain verification.

function

Callback invoked after each batch: (processed: number, total: number) => void.

Export records

Pull all customer data back out as flat SyncRecord objects. Useful for syncing Trusset state back into your core systems or for audit purposes.

const records = await trusset.customers.sync.exportRecords({
  includeArchived: false,
})

// records: SyncRecord[]
// Each record: { externalId, walletAddress?, name?, country?, investorType?, metadata? }

The method paginates internally - it fetches all records regardless of total count. For very large datasets (50k+ customers), consider using the list endpoint directly with pagination for more control.

SyncRecord schema

Every record requires externalId. All other fields are optional.

interface SyncRecord {
  externalId: string          // your system's unique customer ID
  walletAddress?: string      // Ethereum address
  name?: string               // display name
  country?: string            // ISO country code
  investorType?: string       // preset or custom verification profile key
  kycHash?: string            // root hash from the KYC proof tool
  metadata?: Record<string, unknown>
}

Error handling

Import errors are collected per-record rather than failing the entire batch. The errors array in the result contains one entry per failed record:

const result = await trusset.customers.sync.importRecords(records)

for (const err of result.errors) {
  console.error(`Failed: ${err.externalId} - ${err.code}: ${err.message}`)
}

Common error codes:

Code	Cause
`INVALID_ADDRESS`	Wallet address failed checksum validation
`CUSTOMER_EXISTS`	Duplicate wallet address (different externalId)
`VERIFY_FAILED`	On-chain batch verification failed for this entry
`UNKNOWN`	Unexpected server error - check `message` for details

Getting Started

Customers

Database Sync

Import records

Conflict strategies

With on-chain verification

Export records

SyncRecord schema

Error handling

​Import records

​Conflict strategies

​With on-chain verification

​Export records

​SyncRecord schema

​Error handling

Import records

Conflict strategies

With on-chain verification

Export records

SyncRecord schema

Error handling