4.1.0 • Published yesterday

@uvrn/identity

Licence

MIT

Version

4.1.0

Deps

Size

37 kB

Vulns

Weekly

Stars

Summary Dependency Versions

@uvrn/identity

@uvrn/identity tracks signer reputation from protocol-verifiable facts only. The package owns the scoring logic and thresholds. Storage is pluggable through the IdentityStore interface.

Minimal install

npm install @uvrn/identity @uvrn/core

Usage

import { IdentityRegistry, MockIdentityStore } from '@uvrn/identity';

const registry = new IdentityRegistry({
  store: new MockIdentityStore(),
});

await registry.record({
  signerAddress: '0xA9F1...',
  receiptId: 'rec_001',
  vScore: 88,
  consensusVScore: 91,
  canonized: true,
  timestamp: Date.now(),
});

const rep = await registry.reputation('0xA9F1...');

Evidence-based recording: `recordEvent()`

recordEvent() is the v4 path: each event may carry AttestedEvidence — an Ed25519 signature over the canonical JSON of { publicKeyRef, receiptHash, schemaVersion, sigVersion: 'uvrn-sig-1', signedAt? }, verified against the raw 32-byte public key in evidence.publicKey (base64). Payload bytes use the shared environment-pure @uvrn/core/canonical-serialize-2 module; identity contains no live serializer copy.

const result = await registry.recordEvent({
  signerAddress: '0xA9F1...', // used only when the event is unattested
  receiptId: 'rec_002',
  vScore: 88,
  consensusVScore: 91,
  canonized: true,
  timestamp: Date.now(),
  evidence: {
    receiptHash: 'sha256:…',
    schemaVersion: 'uvrn-receipt-4',
    signature: { alg: 'ed25519', publicKeyRef: 'uvrn:key:…', sig: '…' },
    publicKey: '…', // base64 raw 32-byte Ed25519 key
  },
});

result.attested; // true only if the signature verified

The attested/discount model

Attested (evidence present and the signature verifies): the event counts as a full receipt (weight 1), and the reputation is keyed by evidence.publicKey — in v4 the canonical reputation key is the public key. Free-string addresses remain for unattested/legacy events.
Unattested (no evidence, or verification fails): the event is still accepted and recorded — never hidden — but flagged attested: false and weighted at unattestedWeight (default 0.25, configurable on IdentityRegistryOptions).
receipts, canonRate, and accuracy accumulate the event's weight instead of a flat 1; attestedReceipts counts attested events only.
Optional time decay: set accuracyHalfLifeMs to multiply each event's weight by 2^(-(now − timestamp) / accuracyHalfLifeMs). Off by default.

buildEvidencePayload() and verifyAttestedEvidence() are exported so hosts can produce and check signatures with the exact canonical payload the registry verifies.

Sybil note

New keys start at the new level and earn standing only through attested protocol activity. UVRN claims sybil awareness — attested events are cryptographically tied to a key, and unattested events are discounted — not sybil resistance: nothing stops an actor from generating many fresh keys. Treat low-receipt identities accordingly.

`IdentityStore` contract

IdentityStore is the protocol-facing interface users implement for any backend:

interface IdentityStore {
  getReputation(address: string): Promise<ReputationScore | null>;
  saveReputation(rep: ReputationScore): Promise<void>;
  recordActivity(activity: ReputationActivity): Promise<void>;
  listLeaderboard(limit: number): Promise<ReputationScore[]>;
}