@decentrys/protect 0.1.0

package/dist/simulation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Simulation and plain-language decoding.
+ *
+ * These answer a different question from risk. "Is this dangerous?" is the
+ * classifier's job; "what does this transaction actually do?" is this one's,
+ * and for most users it is the more useful of the two. A person who can read
+ * "this grants unlimited spending of your USDC to an address you have never
+ * interacted with" does not need to be told a score.
+ */
+export interface BalanceChange {
+    /** Whose balance moves. Usually the signer, sometimes a contract. */
+    address: string;
+    asset: string;
+    symbol?: string;
+    decimals?: number;
+    /** Signed, base units. Negative leaves the address. */
+    delta: string;
+    usdValue?: number;
+}
+export interface ApprovalChange {
+    owner: string;
+    spender: string;
+    token: string;
+    symbol?: string;
+    /** Base units, or `unlimited`. */
+    amount: string;
+    unlimited: boolean;
+}
+export type SimulationOutcome = 'SUCCESS' | 'REVERT' | 'NOT_SUPPORTED' | 'UNAVAILABLE';
+export interface SimulationResult {
+    outcome: SimulationOutcome;
+    /** Present when the outcome is REVERT and the chain reported a reason. */
+    revertReason?: string;
+    balanceChanges: BalanceChange[];
+    approvalChanges: ApprovalChange[];
+    /** Contracts the transaction touches, in call order. */
+    contractsCalled: string[];
+    gasUsed?: string;
+    /**
+     * Why simulation could not run, when it could not. Stated rather than
+     * silently returning an empty result that reads like "nothing happens".
+     */
+    unavailableReason?: string;
+    simulatedAt: string;
+}
+export interface TransactionExplanation {
+    /** One sentence, in the words a user would use. */
+    summary: string;
+    /** Each distinct thing the transaction does, in order. */
+    actions: string[];
+    /** What the signer gives up if this is not what they intended. */
+    exposure: string[];
+    /** Anything the decoder could not resolve, stated as unresolved. */
+    undecoded: string[];
+}
+export declare function unavailableSimulation(reason: string, now?: Date): SimulationResult;
+//# sourceMappingURL=simulation.d.ts.map

package/dist/simulation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../src/simulation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,GAAG,eAAe,GAAG,aAAa,CAAC;AAEvF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,wDAAwD;IACxD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oEAAoE;IACpE,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAa,GAAG,gBAAgB,CASxF"}

package/dist/simulation.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Simulation and plain-language decoding.
+ *
+ * These answer a different question from risk. "Is this dangerous?" is the
+ * classifier's job; "what does this transaction actually do?" is this one's,
+ * and for most users it is the more useful of the two. A person who can read
+ * "this grants unlimited spending of your USDC to an address you have never
+ * interacted with" does not need to be told a score.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unavailableSimulation = unavailableSimulation;
+function unavailableSimulation(reason, now = new Date()) {
+    return {
+        outcome: 'UNAVAILABLE',
+        balanceChanges: [],
+        approvalChanges: [],
+        contractsCalled: [],
+        unavailableReason: reason,
+        simulatedAt: now.toISOString(),
+    };
+}
+//# sourceMappingURL=simulation.js.map

package/dist/simulation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulation.js","sourceRoot":"","sources":["../src/simulation.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAqDH,sDASC;AATD,SAAgB,qBAAqB,CAAC,MAAc,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE;IACpE,OAAO;QACL,OAAO,EAAE,aAAa;QACtB,cAAc,EAAE,EAAE;QAClB,eAAe,EAAE,EAAE;QACnB,eAAe,EAAE,EAAE;QACnB,iBAAiB,EAAE,MAAM;QACzB,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE;KAC/B,CAAC;AACJ,CAAC"}

package/dist/transport.d.ts

@@ -0,0 +1,61 @@
+/**
+ * HTTP transport for the Protect SDK.
+ *
+ * Three properties matter more than anything else here, because this code runs
+ * inside a wallet on the path to signing a transaction:
+ *
+ *  1. **It always returns.** A hung request is worse than a failed one — the
+ *     user is staring at a spinner holding a signature. Every request carries
+ *     a deadline it cannot exceed.
+ *  2. **It never retries a write.** Retrying an idempotent lookup is free;
+ *     retrying anything else risks doing the thing twice.
+ *  3. **It has no ambient dependencies.** `fetch` is injected rather than
+ *     reached for, so the same code runs in a browser extension, React Native,
+ *     a Node service and a test without a global to patch.
+ */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text: () => Promise<string>;
+}>;
+export type TransportFailure = 'timeout' | 'network' | 'unauthorized' | 'forbidden' | 'rate_limited' | 'invalid_request' | 'server_error' | 'malformed_response';
+export declare class TransportError extends Error {
+    readonly failure: TransportFailure;
+    readonly status?: number;
+    constructor(failure: TransportFailure, message: string, status?: number);
+}
+export interface RequestOptions {
+    path: string;
+    body?: unknown;
+    /**
+     * Safe to repeat. Only idempotent requests are retried; everything else
+     * fails on the first attempt rather than risking a duplicate.
+     */
+    idempotent?: boolean;
+    signal?: AbortSignal;
+}
+export interface TransportConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeoutMs: number;
+    /** Retries for idempotent requests only. 0 disables retrying entirely. */
+    retries: number;
+    fetch: FetchLike;
+    userAgent: string;
+}
+export interface Transport {
+    request<T>(options: RequestOptions): Promise<T>;
+}
+export declare class HttpTransport implements Transport {
+    private readonly config;
+    constructor(config: TransportConfig);
+    request<T>(options: RequestOptions): Promise<T>;
+    private attempt;
+}
+export declare function joinUrl(base: string, path: string): string;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KACE,OAAO,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,SAAS,GACT,cAAc,GACd,WAAW,GACX,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,oBAAoB,CAAC;AAEzB,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAMxE;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACjD;AAaD,qBAAa,aAAc,YAAW,SAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,eAAe;IAE9C,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;YAwBvC,OAAO;CA0DtB;AAuBD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D"}

package/dist/transport.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * HTTP transport for the Protect SDK.
+ *
+ * Three properties matter more than anything else here, because this code runs
+ * inside a wallet on the path to signing a transaction:
+ *
+ *  1. **It always returns.** A hung request is worse than a failed one — the
+ *     user is staring at a spinner holding a signature. Every request carries
+ *     a deadline it cannot exceed.
+ *  2. **It never retries a write.** Retrying an idempotent lookup is free;
+ *     retrying anything else risks doing the thing twice.
+ *  3. **It has no ambient dependencies.** `fetch` is injected rather than
+ *     reached for, so the same code runs in a browser extension, React Native,
+ *     a Node service and a test without a global to patch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpTransport = exports.TransportError = void 0;
+exports.joinUrl = joinUrl;
+class TransportError extends Error {
+    failure;
+    status;
+    constructor(failure, message, status) {
+        super(message);
+        this.name = 'TransportError';
+        this.failure = failure;
+        this.status = status;
+    }
+}
+exports.TransportError = TransportError;
+/** 4xx that will never succeed on a repeat. Retrying these only adds latency. */
+function failureForStatus(status) {
+    if (status === 401)
+        return 'unauthorized';
+    if (status === 403)
+        return 'forbidden';
+    if (status === 429)
+        return 'rate_limited';
+    if (status >= 400 && status < 500)
+        return 'invalid_request';
+    return 'server_error';
+}
+const RETRYABLE = ['network', 'timeout', 'server_error', 'rate_limited'];
+class HttpTransport {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async request(options) {
+        const attempts = options.idempotent ? this.config.retries + 1 : 1;
+        let last = new TransportError('network', 'No attempt was made.');
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            try {
+                return await this.attempt(options);
+            }
+            catch (error) {
+                last = error instanceof TransportError
+                    ? error
+                    : new TransportError('network', error instanceof Error ? error.message : 'Unknown error.');
+                if (!RETRYABLE.includes(last.failure))
+                    throw last;
+                if (attempt === attempts - 1)
+                    throw last;
+                // A short, bounded backoff. Anything longer defeats the point: the
+                // user is waiting on a signing screen, not a batch job.
+                await delay(120 * (attempt + 1));
+            }
+        }
+        throw last;
+    }
+    async attempt(options) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        // The caller's own cancellation (the user navigated away, the popup
+        // closed) has to reach the request too, or it keeps running after the
+        // screen that wanted it is gone.
+        const onAbort = () => controller.abort();
+        options.signal?.addEventListener('abort', onAbort);
+        try {
+            const response = await this.config.fetch(joinUrl(this.config.baseUrl, options.path), {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-api-key': this.config.apiKey,
+                    'user-agent': this.config.userAgent,
+                },
+                body: JSON.stringify(options.body ?? {}),
+                signal: controller.signal,
+            });
+            const text = await response.text();
+            if (!response.ok) {
+                throw new TransportError(failureForStatus(response.status), messageFrom(text) ?? `Decentrys returned HTTP ${response.status}.`, response.status);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                throw new TransportError('malformed_response', 'The response was not valid JSON.');
+            }
+            // The platform wraps every successful body as `{ data: ... }`. Accepting
+            // a bare body too keeps the SDK usable against a proxy that unwraps it.
+            const envelope = parsed;
+            return (envelope && typeof envelope === 'object' && 'data' in envelope
+                ? envelope.data
+                : parsed);
+        }
+        catch (error) {
+            if (error instanceof TransportError)
+                throw error;
+            if (isAbort(error)) {
+                throw options.signal?.aborted
+                    ? new TransportError('network', 'The request was cancelled by the caller.')
+                    : new TransportError('timeout', `No response within ${this.config.timeoutMs}ms.`);
+            }
+            throw new TransportError('network', error instanceof Error ? error.message : 'Network request failed.');
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', onAbort);
+        }
+    }
+}
+exports.HttpTransport = HttpTransport;
+function isAbort(error) {
+    return (typeof error === 'object'
+        && error !== null
+        && (error.name === 'AbortError'
+            || error.code === 'ABORT_ERR'));
+}
+/** Surface the API's own message when it sent one; it is better than ours. */
+function messageFrom(text) {
+    try {
+        const body = JSON.parse(text);
+        if (typeof body.message === 'string' && body.message.trim())
+            return body.message;
+        if (typeof body.error === 'string' && body.error.trim())
+            return body.error;
+    }
+    catch {
+        // Not JSON. Nothing to surface.
+    }
+    return null;
+}
+function joinUrl(base, path) {
+    return `${base.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}
+function delay(ms) {
+    return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}

package/dist/wire.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The wire contract, and the boundary that defends the rule.
+ *
+ * Decentrys sends **evidence**, not a verdict. The SDK classifies locally with
+ * `classify()`. That is not a stylistic choice — it has two consequences that
+ * matter:
+ *
+ *  - An integrator can audit exactly why a level was reached, in code they can
+ *    read, without trusting a remote score.
+ *  - The rule is enforced on the client, where it cannot be undone by a server
+ *    change, a proxy, or a future endpoint written by someone who has not read
+ *    the model.
+ *
+ * That last point is concrete rather than theoretical. Decentrys also operates
+ * an AML engine for exchanges and custodians, and in *that* product a new
+ * address legitimately raises a score — money-laundering typologies genuinely
+ * care about freshly created accounts, and regulators expect it to be flagged.
+ * The same signal reaching a consumer wallet unchanged would tax every new
+ * project on earth. So the boundary below refuses coverage signals no matter
+ * who sends them, and turns them into what they actually are: history.
+ */
+import type { HistoryStatus, ObservedFact, TechnicalCapability, ThreatSignal, UnknownField } from './model';
+export type SubjectKind = 'address' | 'contract' | 'token' | 'transaction' | 'approval' | 'dapp';
+export interface SubjectRef {
+    kind: SubjectKind;
+    chain: string;
+    identifier: string;
+}
+/** What every Protect endpoint returns. Evidence in, classification local. */
+export interface EvidencePayload {
+    subject: SubjectRef;
+    facts: ObservedFact[];
+    capabilities: TechnicalCapability[];
+    threatSignals: ThreatSignal[];
+    unknowns: UnknownField[];
+    historyStatus: HistoryStatus;
+    historyConfidence?: number;
+    producedAt: string;
+}
+/**
+ * Signal types that describe how much *we* know, not how dangerous a subject
+ * is. If one arrives as a threat signal it is demoted to a fact and its
+ * explanation is preserved, so nothing is hidden — it simply stops being able
+ * to raise a risk level.
+ *
+ * Every entry here is a real signal name used somewhere in the industry, and
+ * several are emitted by Decentrys' own AML engine.
+ */
+export declare const COVERAGE_SIGNAL_TYPES: Set<string>;
+export interface NormalizedEvidence extends EvidencePayload {
+    /** Signals demoted at the boundary, kept so an integrator can see it happen. */
+    demotedSignals: string[];
+}
+/**
+ * Coerce an untrusted payload into the model's shape.
+ *
+ * A wallet must not crash because a field arrived as a number instead of a
+ * string, or because a proxy inserted something. Anything unusable is dropped
+ * rather than guessed at, and a dropped item is simply absent — never
+ * converted into a finding.
+ */
+export declare function normalizeEvidence(raw: unknown, fallback: SubjectRef): NormalizedEvidence;
+//# sourceMappingURL=wire.d.ts.map

package/dist/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACW,aAAa,EAAE,YAAY,EAAgB,mBAAmB,EACnE,YAAY,EAAE,YAAY,EAC3C,MAAM,SAAS,CAAC;AAEjB,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,aAAa,GAAG,UAAU,GAAG,MAAM,CAAC;AAEjG,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,YAAY,EAAE,mBAAmB,EAAE,CAAC;IACpC,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,aAAa,EAAE,aAAa,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,aAuBhC,CAAC;AAUH,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,gFAAgF;IAChF,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,GAAG,kBAAkB,CA+CxF"}

package/dist/wire.js

@@ -0,0 +1,274 @@
+"use strict";
+/**
+ * The wire contract, and the boundary that defends the rule.
+ *
+ * Decentrys sends **evidence**, not a verdict. The SDK classifies locally with
+ * `classify()`. That is not a stylistic choice — it has two consequences that
+ * matter:
+ *
+ *  - An integrator can audit exactly why a level was reached, in code they can
+ *    read, without trusting a remote score.
+ *  - The rule is enforced on the client, where it cannot be undone by a server
+ *    change, a proxy, or a future endpoint written by someone who has not read
+ *    the model.
+ *
+ * That last point is concrete rather than theoretical. Decentrys also operates
+ * an AML engine for exchanges and custodians, and in *that* product a new
+ * address legitimately raises a score — money-laundering typologies genuinely
+ * care about freshly created accounts, and regulators expect it to be flagged.
+ * The same signal reaching a consumer wallet unchanged would tax every new
+ * project on earth. So the boundary below refuses coverage signals no matter
+ * who sends them, and turns them into what they actually are: history.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COVERAGE_SIGNAL_TYPES = void 0;
+exports.normalizeEvidence = normalizeEvidence;
+// ---------------------------------------------------------------------------
+// Coverage signals — never threat signals
+// ---------------------------------------------------------------------------
+/**
+ * Signal types that describe how much *we* know, not how dangerous a subject
+ * is. If one arrives as a threat signal it is demoted to a fact and its
+ * explanation is preserved, so nothing is hidden — it simply stops being able
+ * to raise a risk level.
+ *
+ * Every entry here is a real signal name used somewhere in the industry, and
+ * several are emitted by Decentrys' own AML engine.
+ */
+exports.COVERAGE_SIGNAL_TYPES = new Set([
+    'NEW_ADDRESS',
+    'NEW_CONTRACT',
+    'NEW_DEPLOYMENT',
+    'LOW_ACTIVITY',
+    'LIMITED_HISTORY',
+    'NO_HISTORY',
+    'ESTABLISHED_HISTORY',
+    'UNVERIFIED_SOURCE',
+    'UNVERIFIED_CONTRACT',
+    'NO_AUDIT',
+    'UNAUDITED',
+    'ANONYMOUS_DEPLOYER',
+    'ANONYMOUS_TEAM',
+    'UNKNOWN_DEPLOYER',
+    'LOW_LIQUIDITY',
+    'THIN_LIQUIDITY',
+    'SMALL_MARKET_CAP',
+    'HOLDER_CONCENTRATION',
+    'LOW_HOLDER_COUNT',
+    'NOT_ON_TOKEN_LIST',
+    'UNKNOWN_TOKEN',
+    'NO_SOCIAL_PRESENCE',
+]);
+/**
+ * The coverage signals that say there is *no* record at all, as opposed to a
+ * thin one. Used only when the server sent no `historyStatus`: without this,
+ * demoting the signal would throw away the one thing it told us, and a subject
+ * we know nothing about would be reported as merely thinly covered.
+ */
+const NO_HISTORY_TYPES = new Set(['NO_HISTORY', 'UNKNOWN_TOKEN']);
+// ---------------------------------------------------------------------------
+// Defensive normalization
+// ---------------------------------------------------------------------------
+/**
+ * Coerce an untrusted payload into the model's shape.
+ *
+ * A wallet must not crash because a field arrived as a number instead of a
+ * string, or because a proxy inserted something. Anything unusable is dropped
+ * rather than guessed at, and a dropped item is simply absent — never
+ * converted into a finding.
+ */
+function normalizeEvidence(raw, fallback) {
+    const body = isRecord(raw) ? raw : {};
+    const demotedSignals = [];
+    const facts = asArray(body.facts).map(toFact).filter(isPresent);
+    const capabilities = asArray(body.capabilities).map(toCapability).filter(isPresent);
+    const unknowns = asArray(body.unknowns).map(toUnknown).filter(isPresent);
+    const threatSignals = [];
+    let noHistoryObserved = false;
+    for (const item of asArray(body.threatSignals)) {
+        const signal = toSignal(item);
+        if (!signal)
+            continue;
+        if (exports.COVERAGE_SIGNAL_TYPES.has(signal.type)) {
+            demotedSignals.push(signal.type);
+            if (NO_HISTORY_TYPES.has(signal.type))
+                noHistoryObserved = true;
+            facts.push({
+                type: signal.type,
+                value: null,
+                statement: signal.explanation,
+                source: signal.evidence[0]?.source ?? 'decentrys',
+                observedAt: signal.lastSeen,
+            });
+            continue;
+        }
+        threatSignals.push(signal);
+    }
+    // LIMITED is the neutral default, and deliberately so: it is the correct
+    // state for anything recently deployed and carries no accusation.
+    const declaredHistory = asHistoryStatus(body.historyStatus);
+    const historyStatus = declaredHistory ?? (noHistoryObserved ? 'NONE' : 'LIMITED');
+    return {
+        subject: toSubject(body.subject, fallback),
+        facts,
+        capabilities,
+        threatSignals,
+        unknowns,
+        historyStatus,
+        historyConfidence: asNumber(body.historyConfidence) ?? undefined,
+        producedAt: asString(body.producedAt) ?? new Date().toISOString(),
+        demotedSignals,
+    };
+}
+// ---------------------------------------------------------------------------
+// Field coercion
+// ---------------------------------------------------------------------------
+function toSubject(raw, fallback) {
+    if (!isRecord(raw))
+        return fallback;
+    const kind = asString(raw.kind);
+    return {
+        kind: isSubjectKind(kind) ? kind : fallback.kind,
+        chain: asString(raw.chain) ?? fallback.chain,
+        identifier: asString(raw.identifier) ?? fallback.identifier,
+    };
+}
+function toFact(raw) {
+    if (!isRecord(raw))
+        return null;
+    const type = asString(raw.type);
+    const statement = asString(raw.statement);
+    if (!type || !statement)
+        return null;
+    return {
+        type,
+        value: asFactValue(raw.value),
+        statement,
+        source: asString(raw.source) ?? 'decentrys',
+        observedAt: asString(raw.observedAt) ?? new Date().toISOString(),
+    };
+}
+function toCapability(raw) {
+    if (!isRecord(raw))
+        return null;
+    const type = asString(raw.type);
+    const statement = asString(raw.statement);
+    if (!type || !statement)
+        return null;
+    const severity = asString(raw.severity);
+    return {
+        type,
+        // An unrecognised severity becomes INFO, the least consequential value.
+        // Guessing upward would let a typo raise someone's risk level.
+        severity: severity === 'NOTABLE' || severity === 'SIGNIFICANT' ? severity : 'INFO',
+        statement,
+        grantedBy: asString(raw.grantedBy) ?? undefined,
+    };
+}
+function toSignal(raw) {
+    if (!isRecord(raw))
+        return null;
+    const type = asString(raw.type);
+    const explanation = asString(raw.explanation);
+    if (!type || !explanation)
+        return null;
+    const evidence = asArray(raw.evidence).map(toEvidence).filter(isPresent);
+    const createdAt = asString(raw.createdAt) ?? new Date().toISOString();
+    return {
+        type,
+        severity: asSeverity(raw.severity),
+        confidence: clamp01(asNumber(raw.confidence) ?? 0),
+        explanation,
+        // A missing hop count means we do not know how far away this is, and an
+        // unknown distance is an inference, not a direct observation.
+        hops: Math.max(0, Math.trunc(asNumber(raw.hops) ?? 1)),
+        evidence,
+        status: asSignalStatus(raw.status),
+        createdAt,
+        lastSeen: asString(raw.lastSeen) ?? createdAt,
+        expiresAt: asString(raw.expiresAt) ?? undefined,
+    };
+}
+function toEvidence(raw) {
+    if (!isRecord(raw))
+        return null;
+    const id = asString(raw.id);
+    const type = asString(raw.type);
+    if (!id || !type)
+        return null;
+    return {
+        id,
+        type,
+        source: asString(raw.source) ?? 'decentrys',
+        chain: asString(raw.chain) ?? undefined,
+        txHash: asString(raw.txHash) ?? undefined,
+        contract: asString(raw.contract) ?? undefined,
+        address: asString(raw.address) ?? undefined,
+        observedAt: asString(raw.observedAt) ?? new Date().toISOString(),
+        confidence: clamp01(asNumber(raw.confidence) ?? 0),
+        // Defaults to false. `analystVerified` is what gates KNOWN_MALICIOUS, so
+        // an absent field must never be read as a human having checked.
+        analystVerified: raw.analystVerified === true,
+        metadata: isRecord(raw.metadata) ? raw.metadata : undefined,
+    };
+}
+function toUnknown(raw) {
+    if (!isRecord(raw))
+        return null;
+    const field = asString(raw.field);
+    const statement = asString(raw.statement);
+    if (!field || !statement)
+        return null;
+    const reason = asString(raw.reason);
+    const reasons = ['UNKNOWN', 'INSUFFICIENT_DATA', 'PROVIDER_UNAVAILABLE', 'NOT_APPLICABLE'];
+    return {
+        field,
+        reason: reasons.includes(reason) ? reason : 'UNKNOWN',
+        statement,
+    };
+}
+// ---------------------------------------------------------------------------
+// Primitives
+// ---------------------------------------------------------------------------
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function asFactValue(value) {
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    return null;
+}
+function asSeverity(value) {
+    const severities = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+    return severities.includes(value) ? value : 'LOW';
+}
+function asSignalStatus(value) {
+    const statuses = ['ACTIVE', 'STALE', 'RESOLVED', 'DISPUTED_FACT', 'REMOVED'];
+    return statuses.includes(value) ? value : 'ACTIVE';
+}
+function asHistoryStatus(value) {
+    const statuses = ['ESTABLISHED', 'MODERATE', 'LIMITED', 'NONE'];
+    return statuses.includes(value) ? value : null;
+}
+function isSubjectKind(value) {
+    return value === 'address' || value === 'contract' || value === 'token'
+        || value === 'transaction' || value === 'approval' || value === 'dapp';
+}
+function clamp01(value) {
+    return Math.min(1, Math.max(0, value));
+}
+function isPresent(value) {
+    return value !== null;
+}
+//# sourceMappingURL=wire.js.map