chit402-verify 0.3.4 → 0.4.0

package/dist/preimage.js

@@ -0,0 +1,363 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEAF_NOT_BOUND = void 0;
+exports.auditLeafBinding = auditLeafBinding;
+exports.requiredPreimageFields = requiredPreimageFields;
+exports.verifyPublishedPreimages = verifyPublishedPreimages;
+/**
+ * Recompute published receipt preimages.
+ * A missing or mismatched preimage fails closed when the caller requires it,
+ * and whenever a `preimages` block is present.
+ */
+const node_crypto_1 = require("node:crypto");
+const ethers_1 = require("ethers");
+const anchor_witness_js_1 = require("./anchor-witness.js");
+const row_hash_js_1 = require("./row-hash.js");
+const ALWAYS_REQUIRED = [
+    'row_hash',
+    'book_chain.row_hash',
+    'book_row.row_hash',
+    'inclusion.leaf',
+    'binding.expected_commitment',
+    'job_spec_hash',
+    'response_hash',
+];
+function sha256(buf) {
+    return (0, node_crypto_1.createHash)('sha256').update(buf).digest();
+}
+function bytesOf(entry) {
+    if (!entry)
+        return null;
+    if (typeof entry.preimage_hex === 'string' && entry.preimage_hex !== '') {
+        const hex = entry.preimage_hex.replace(/^0x/, '');
+        if (!/^[0-9a-fA-F]*$/.test(hex) || hex.length % 2)
+            return null;
+        return Buffer.from(hex, 'hex');
+    }
+    if (typeof entry.preimage_utf8 === 'string')
+        return Buffer.from(entry.preimage_utf8, 'utf8');
+    return null;
+}
+function leafInput(leaf) {
+    if (typeof leaf.preimage_hex === 'string' && leaf.preimage_hex !== '') {
+        return bytesOf(leaf);
+    }
+    if (typeof leaf.preimage_utf8 === 'string') {
+        return Buffer.concat([Buffer.from([0x00]), Buffer.from(leaf.preimage_utf8, 'utf8')]);
+    }
+    return null;
+}
+function merkleRoot(leaves) {
+    const level = [];
+    for (const leaf of leaves) {
+        const input = leafInput(leaf);
+        if (!input)
+            return null;
+        level.push(sha256(input));
+    }
+    if (!level.length)
+        return null;
+    let nodes = level;
+    while (nodes.length > 1) {
+        const next = [];
+        for (let i = 0; i < nodes.length; i += 2) {
+            if (i + 1 === nodes.length)
+                next.push(nodes[i]);
+            else
+                next.push(sha256(Buffer.concat([Buffer.from([0x01]), nodes[i], nodes[i + 1]])));
+        }
+        nodes = next;
+    }
+    return nodes[0].toString('hex');
+}
+function hasAuditPath(entry) {
+    return !!entry.audit_path && !!entry.leaf && Array.isArray(entry.audit_path.siblings);
+}
+/** The audit path folds to this receipt's leaf. A different leaf in the same prefix is not this receipt. */
+exports.LEAF_NOT_BOUND = 'leaf_not_bound';
+function receiptTaskId(receipt) {
+    return receipt.task_id == null || receipt.task_id === '' ? '' : String(receipt.task_id);
+}
+/**
+ * The row hash the leaf must name. `boundRowHash` agrees top-level
+ * `row_hash`, `book_chain.row_hash`, and `inclusion.row_hash`. Null and `''`
+ * are missing: do not hash `task_id|`. A disagreement is missing here too.
+ */
+function agreedRowHash(receipt) {
+    const inclusion = receipt.inclusion;
+    const extra = inclusion && typeof inclusion === 'object'
+        ? inclusion
+        : null;
+    const bound = (0, row_hash_js_1.boundRowHash)(receipt, extra);
+    if (!bound.ok || bound.row == null || bound.row === '')
+        return null;
+    return bound.row;
+}
+function decodeHexBytes(value) {
+    const hex = value.replace(/^0x/, '');
+    if (hex.length === 0 || hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex))
+        return null;
+    return Buffer.from(hex, 'hex');
+}
+function unknownPreimageKey(leaf) {
+    return Object.keys(leaf).some((key) => key.startsWith('preimage_') && key !== 'preimage_utf8' && key !== 'preimage_hex');
+}
+/**
+ * One leaf body, in bytes. `preimage_utf8` is that body. `preimage_hex` is
+ * either the same body or `0x00 || body` (the hash input). A leading `0x00`
+ * is the domain byte; a body that itself starts with `0x00` is ambiguous.
+ * Two encodings must name the same body. Any other encoding is rejected.
+ */
+function canonicalMerkleBody(leaf) {
+    if (!leaf || typeof leaf !== 'object' || unknownPreimageKey(leaf))
+        return null;
+    const utf8Present = typeof leaf.preimage_utf8 === 'string';
+    const hexPresent = typeof leaf.preimage_hex === 'string' && leaf.preimage_hex !== '';
+    if (!utf8Present && !hexPresent)
+        return null;
+    if (utf8Present && leaf.preimage_utf8 === '')
+        return null;
+    const utf8Body = utf8Present ? Buffer.from(leaf.preimage_utf8, 'utf8') : null;
+    let hexBody = null;
+    if (hexPresent) {
+        const raw = decodeHexBytes(leaf.preimage_hex);
+        if (!raw || raw.length === 0)
+            return null;
+        if (raw[0] === 0x00) {
+            if (raw.length < 2 || raw[1] === 0x00)
+                return null;
+            hexBody = raw.subarray(1);
+        }
+        else {
+            hexBody = raw;
+        }
+    }
+    if (utf8Body && hexBody && !utf8Body.equals(hexBody))
+        return null;
+    return utf8Body ?? hexBody;
+}
+/** SHA-256 input for an audit-path leaf: `0x00 ||` the canonical body. */
+function auditLeafHashInput(leaf) {
+    const body = canonicalMerkleBody(leaf);
+    if (!body)
+        return null;
+    return Buffer.concat([Buffer.from([0x00]), body]);
+}
+/**
+ * Bind an audit path to this receipt. Returns `leaf_not_bound` when any
+ * check fails, including when the agreed row hash is null, empty, or
+ * disagreed, or the leaf encoding does not canonicalize to `task_id|row_hash`.
+ * Inclusion leaf hash and leaf index are checked only when that field is present.
+ * Inclusion tree size is not compared: the witness can cover a longer log.
+ */
+function auditLeafBinding(receipt, entry) {
+    const leaf = entry.leaf;
+    const path = entry.audit_path;
+    if (!leaf || !path)
+        return exports.LEAF_NOT_BOUND;
+    const taskId = receiptTaskId(receipt);
+    if (!taskId || leaf.task_id == null || String(leaf.task_id) !== taskId)
+        return exports.LEAF_NOT_BOUND;
+    const rowHash = agreedRowHash(receipt);
+    const body = canonicalMerkleBody(leaf);
+    if (rowHash == null || !body)
+        return exports.LEAF_NOT_BOUND;
+    const expected = Buffer.from(`${taskId}|${rowHash}`, 'utf8');
+    if (!body.equals(expected))
+        return exports.LEAF_NOT_BOUND;
+    const inclusion = receipt.inclusion;
+    if (inclusion && typeof inclusion === 'object') {
+        const claimedLeaf = inclusion.leaf;
+        if (claimedLeaf != null && claimedLeaf !== '') {
+            const input = auditLeafHashInput(leaf);
+            if (!input)
+                return exports.LEAF_NOT_BOUND;
+            const hashed = sha256(input).toString('hex');
+            const want = String(claimedLeaf).replace(/^0x/, '').toLowerCase();
+            if (hashed !== want)
+                return exports.LEAF_NOT_BOUND;
+        }
+        const claimedIndex = inclusion.leaf_index;
+        if (claimedIndex != null && claimedIndex !== '') {
+            const want = Number(claimedIndex);
+            const got = Number(path.index);
+            if (!Number.isSafeInteger(want) || got !== want)
+                return exports.LEAF_NOT_BOUND;
+        }
+    }
+    return null;
+}
+/**
+ * Recompute the prefix root from this leaf and the sibling hashes.
+ * A full `leaves` array is the pre-redaction shape and is not read here.
+ */
+function auditRoot(entry) {
+    const path = entry.audit_path;
+    const leaf = entry.leaf;
+    if (!path || !leaf || !Array.isArray(path.siblings))
+        return null;
+    const index = Number(path.index);
+    const treeSize = Number(path.tree_size);
+    if (!Number.isSafeInteger(index) || !Number.isSafeInteger(treeSize))
+        return null;
+    if (leaf.index != null && Number(leaf.index) !== index)
+        return null;
+    const input = auditLeafHashInput(leaf);
+    if (!input)
+        return null;
+    const got = (0, anchor_witness_js_1.inclusionRoot)(sha256(input), index, treeSize, path.siblings.map((step) => ({ hash: String(step?.hash || '') })));
+    if (!got)
+        return null;
+    if (path.root != null && path.root !== '') {
+        const claimed = String(path.root).replace(/^0x/, '').toLowerCase();
+        if (claimed !== got)
+            return null;
+    }
+    return got;
+}
+function digestHex(entry) {
+    if (hasAuditPath(entry))
+        return auditRoot(entry);
+    if (entry.merkle === 'rfc6962' && Array.isArray(entry.leaves) && entry.leaves.length > 0) {
+        return merkleRoot(entry.leaves);
+    }
+    const bytes = bytesOf(entry);
+    if (!bytes)
+        return null;
+    if (entry.alg === 'keccak256')
+        return (0, ethers_1.keccak256)(bytes).toLowerCase();
+    if (entry.alg === 'sha256') {
+        const hex = sha256(bytes).toString('hex');
+        const published = String(entry.hash || '');
+        if (published.startsWith('0x') || published.startsWith('sha256:'))
+            return `0x${hex}`;
+        return hex;
+    }
+    return null;
+}
+function sameHash(left, right) {
+    const norm = (value) => value.trim().toLowerCase().replace(/^sha256=/, '');
+    return norm(left) === norm(right);
+}
+function readPath(receipt, field) {
+    if (field === 'job_spec_hash') {
+        return receipt.job_spec_hash
+            ?? receipt.board?.job_spec_hash
+            ?? receipt.a2a_escrow?.job_spec_hash
+            ?? null;
+    }
+    return field.split('.').reduce((obj, key) => {
+        if (obj == null || typeof obj !== 'object')
+            return undefined;
+        return obj[key];
+    }, receipt);
+}
+function hasHash(value) {
+    return value != null && value !== '';
+}
+function withheld(block, field) {
+    return (block?.not_recomputable || []).some((row) => row.field === field);
+}
+/**
+ * Fields a stranger is expected to recompute when they are present.
+ * Coverage and tree_head_hash count only when the issuer published a preimage.
+ * Output, HMAC, and book-row universe hashes do not.
+ */
+function requiredPreimageFields(receipt) {
+    const block = (receipt.preimages || null);
+    const fields = [];
+    for (const field of ALWAYS_REQUIRED) {
+        if (hasHash(readPath(receipt, field)) && !withheld(block, field))
+            fields.push(field);
+    }
+    for (const field of ['tree_head_hash', 'coverage.universe_hash', 'coverage.enumerated_hash']) {
+        if (block?.fields?.[field])
+            fields.push(field);
+    }
+    return [...new Set(fields)];
+}
+async function loadRemote(entry, fetchImpl, hosts) {
+    if (!entry.url)
+        return null;
+    let url;
+    try {
+        url = new URL(entry.url);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'https:' || !hosts.some((host) => host.toLowerCase() === url.hostname.toLowerCase())) {
+        return null;
+    }
+    const res = await fetchImpl(entry.url);
+    if (!res.ok)
+        return null;
+    const body = await res.json();
+    return body && typeof body === 'object' ? { ...entry, ...body } : null;
+}
+async function verifyPublishedPreimages(receipt, { requirePreimages = false, fetchImpl = globalThis.fetch, trustedHosts = ['api.chit402.com'], } = {}) {
+    const block = (receipt.preimages || null);
+    const required = requiredPreimageFields(receipt);
+    if (!block && !requirePreimages) {
+        return { checked: false, ok: true, errors: [], fields: [] };
+    }
+    if (!block && required.length === 0) {
+        return { checked: true, ok: true, errors: [], fields: [] };
+    }
+    const errors = [];
+    const fields = [];
+    const published = block?.fields || {};
+    const targets = new Set([...required, ...Object.keys(published)]);
+    for (const field of targets) {
+        if (withheld(block, field) && !published[field])
+            continue;
+        let entry = published[field];
+        if (!entry) {
+            const message = `preimage missing for ${field}`;
+            errors.push(message);
+            fields.push({ field, ok: false, reason: 'preimage_missing' });
+            continue;
+        }
+        if (entry.recomputable === false)
+            continue;
+        if (hasAuditPath(entry)) {
+            const bound = auditLeafBinding(receipt, entry);
+            if (bound) {
+                errors.push(`preimage leaf is not this receipt for ${field}`);
+                fields.push({ field, ok: false, reason: bound });
+                continue;
+            }
+        }
+        if (!bytesOf(entry) && !(entry.leaves && entry.leaves.length) && !hasAuditPath(entry) && entry.url && fetchImpl) {
+            try {
+                const remote = await loadRemote(entry, fetchImpl, trustedHosts);
+                if (remote)
+                    entry = remote;
+            }
+            catch {
+                /* fall through to missing */
+            }
+        }
+        const digest = digestHex(entry);
+        const expected = entry.hash != null ? String(entry.hash) : '';
+        const onReceipt = readPath(receipt, field);
+        if (digest == null) {
+            errors.push(`preimage missing for ${field}`);
+            fields.push({ field, ok: false, reason: 'preimage_missing' });
+            continue;
+        }
+        if (!sameHash(digest, expected)) {
+            errors.push(`preimage mismatch for ${field}: hash does not match the published bytes`);
+            fields.push({ field, ok: false, reason: 'preimage_mismatch' });
+            continue;
+        }
+        if (hasHash(onReceipt) && !sameHash(digest, String(onReceipt))) {
+            errors.push(`preimage mismatch for ${field}: recomputed hash does not match the receipt`);
+            fields.push({ field, ok: false, reason: 'preimage_mismatch' });
+            continue;
+        }
+        fields.push({ field, ok: true });
+    }
+    return { checked: true, ok: errors.length === 0, errors, fields };
+}
+//# sourceMappingURL=preimage.js.map

package/dist/preimage.js.map

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

package/dist/receipt-lane.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Unsigned receipt-lane decision beside book_seq.
+ *
+ * Design by Turbo on 1F916 (post 6579, comments 88201 and 88403):
+ * freeze a receipt-lane row only when seq is present, settled_by is
+ * `receipt`, the anchored tree head changed after that row was bound, and
+ * the row is not settled. anchor_changed_since_binding alone does not freeze.
+ *
+ * Comment 88596 freezes that ordering — seq + settled_by + (anchor_changed
+ * AND not settled) — and states the boundary: complete over registry marks,
+ * blind to payments the registry never joined. A binding past expiry with
+ * settled_by, receipt_id, observed_tx_hash, and observed_transfer_id all
+ * null is unverifiable_from_registry, not unpaid.
+ *
+ * These fields are derived. They are not inside the payment JWS and not
+ * inside the signed book_seq claims. payload_version is unchanged.
+ *
+ * Keep this rule in lockstep with services/gateway/src/receipt-lane.js.
+ */
+export declare const RECEIPT_LANE_SCHEMA = "chit402.receipt_lane.v1";
+export declare const RECEIPT_LANE_RULE: string;
+/** Frozen partition order. `settled_by` here is the receipt-lane conjunct (value `receipt`). */
+export declare const RECEIPT_LANE_ORDERING = "seq + settled_by + (anchor_changed AND not settled)";
+/** The ordering reads registry marks only. A transfer the registry never joined is outside it. */
+export declare const RECEIPT_LANE_BOUNDARY = "complete over registry marks, blind to payments the registry never joined";
+/**
+ * Base mainnet USDC. Same contract as USDC_ADDRESSES.base in
+ * services/gateway/src/foreign-x402-ingest.js. The hint does not call RPC.
+ */
+export declare const BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export type SettledBy = 'observed_transfer' | 'receipt' | null;
+export type RegistryClassification = 'receipt' | 'observed_transfer' | 'anchor_changed_unsettled' | 'unsettled' | 'unverifiable_from_registry';
+export interface LocalCheckHint {
+    method: 'base_usdc_transfer';
+    chain_id: 8453;
+    token: string;
+    payee: string;
+    amount_atomic: string;
+    claims_paid: false;
+}
+export interface AnchorIdentity {
+    root: string | null;
+    tree_size: number | null;
+    anchor_tx: string | null;
+    solana_signature: string | null;
+}
+export interface ReceiptLane {
+    schema: typeof RECEIPT_LANE_SCHEMA;
+    signed: false;
+    book_seq: number | null;
+    settled_by: SettledBy;
+    settled: boolean | null;
+    anchor_at_binding: AnchorIdentity | null;
+    anchor_current: AnchorIdentity | null;
+    anchor_changed_since_binding: boolean | null;
+    freeze: boolean;
+    reason: 'unsettled_anchor_changed' | null;
+    rule: string;
+    ordering: typeof RECEIPT_LANE_ORDERING;
+    boundary: typeof RECEIPT_LANE_BOUNDARY;
+    classification: RegistryClassification;
+    local_check: LocalCheckHint | null;
+}
+export interface LanePayer {
+    checked?: boolean;
+    valid?: boolean;
+}
+export interface LaneEntry {
+    book_seq?: number | null;
+    seq?: number | null;
+    book_chain?: {
+        seq?: number | null;
+    } | null;
+    payment?: {
+        ref?: string | null;
+        rail?: string | null;
+        collected?: boolean | null;
+    } | null;
+    payment_ref?: string | null;
+    rail?: string | null;
+    collected?: boolean | null;
+    evidence?: string | null;
+    source?: string | null;
+    foreign_x402?: boolean;
+    arrival_status?: string | null;
+    ingress_receipt?: {
+        ref?: string | null;
+    } | null;
+    settlement_status?: string | null;
+    usage_settled?: {
+        settlement_status?: string | null;
+    } | null;
+    expiry?: number | string | null;
+    receipt_id?: string | number | null;
+    observed_tx_hash?: string | null;
+    observed_transfer_id?: string | number | null;
+    settled_by?: SettledBy;
+    anchor_changed_since_binding?: boolean | null;
+    chain_id?: number | string | null;
+    chainId?: number | string | null;
+    token?: string | null;
+    asset?: string | null;
+    payout_address?: string | null;
+    address?: string | null;
+    payee?: string | null;
+    amount_atomic?: string | number | null;
+    docket_id?: string | null;
+}
+export interface ReceiptTreeHead {
+    root?: string | null;
+    tree_size?: number | null;
+    anchor_tx?: string | null;
+    anchor?: {
+        tx?: string | null;
+        status?: string | null;
+    } | null;
+    anchors?: {
+        base?: {
+            tx?: string | null;
+            status?: string | null;
+        } | null;
+        solana?: {
+            signature?: string | null;
+            status?: string | null;
+        } | null;
+    } | null;
+}
+export declare function normalizeRoot(root: string | null | undefined): string | null;
+export declare function anchorIdentity(head: ReceiptTreeHead | null | undefined): AnchorIdentity | null;
+export declare function anchorChangedSinceBinding(heads: ReceiptTreeHead[] | null | undefined, leafIndex: number | null | undefined): {
+    changed: boolean | null;
+    at: AnchorIdentity | null;
+    current: AnchorIdentity | null;
+};
+/** A 1F916 payout binding carries expiry plus a registry mark key. A book row does not. */
+export declare function isPayoutBinding(input: LaneEntry | null | undefined): boolean;
+/** Unix seconds, unix ms, or an ISO timestamp. Null when the field is absent or not a time. */
+export declare function expiryMillis(expiry: number | string | null | undefined): number | null;
+export declare function isPastExpiry(expiry: number | string | null | undefined, nowMs?: number): boolean;
+/**
+ * Partition a row. Expired and unmarked is unverifiable_from_registry, ahead
+ * of the clean-unsettled and anchor-changed buckets, and behind a joined
+ * settled_by (receipt or observed_transfer).
+ */
+export declare function classifyReceiptLane({ entry, settled_by, settled, anchor_changed_since_binding, now, }?: {
+    entry?: LaneEntry | null;
+    settled_by?: SettledBy;
+    settled?: boolean | null;
+    anchor_changed_since_binding?: boolean | null;
+    now?: number;
+}): RegistryClassification;
+/**
+ * Payee and amount a stranger can feed to the existing per-tx Base USDC check.
+ * Null unless this row is Base mainnet USDC. Does not claim the transfer happened
+ * and does not read the chain.
+ */
+export declare function baseUsdcLocalCheckHint(entry: LaneEntry | null | undefined): LocalCheckHint | null;
+export declare function deriveSettledBy(input: LaneEntry | null | undefined, { payer, issuerAssertsSettlement }?: {
+    payer?: LanePayer | null;
+    issuerAssertsSettlement?: boolean | null;
+}): SettledBy;
+export declare function deriveSettled(input: LaneEntry | null | undefined, { payer }?: {
+    payer?: LanePayer | null;
+}): boolean | null;
+export declare function bookSeqOf(input: LaneEntry | null | undefined): number | null;
+export declare function receiptLaneDecision(input: {
+    book_seq: number | null;
+    settled_by: SettledBy;
+    settled: boolean | null;
+    anchor_changed_since_binding: boolean | null;
+}): {
+    freeze: boolean;
+    reason: 'unsettled_anchor_changed' | null;
+};
+export declare function buildReceiptLane({ entry, payer, leafIndex, heads, issuerAssertsSettlement, anchorAtBinding, anchorCurrent, now, }?: {
+    entry?: LaneEntry | null;
+    payer?: LanePayer | null;
+    leafIndex?: number | null;
+    heads?: ReceiptTreeHead[] | null;
+    issuerAssertsSettlement?: boolean | null;
+    anchorAtBinding?: AnchorIdentity | null;
+    anchorCurrent?: AnchorIdentity | null;
+    now?: number;
+}): ReceiptLane;
+interface SignedClaims {
+    schema?: string | null;
+    payment?: {
+        ref?: string | null;
+        rail?: string | null;
+        collected?: boolean | null;
+    } | null;
+    settlement?: {
+        kind?: string | null;
+    } | null;
+}
+interface ReceiptLaneSource {
+    book_seq?: number | null;
+    book_chain?: {
+        seq?: number | null;
+    } | null;
+    tree_head?: ReceiptTreeHead | null;
+    head?: ReceiptTreeHead | null;
+    expiry?: number | string | null;
+    receipt_id?: string | number | null;
+    observed_tx_hash?: string | null;
+    observed_transfer_id?: string | number | null;
+    settled_by?: SettledBy;
+    anchor_changed_since_binding?: boolean | null;
+    chain_id?: number | string | null;
+    token?: string | null;
+    payout_address?: string | null;
+    address?: string | null;
+    amount_atomic?: string | number | null;
+    docket_id?: string | null;
+    receipt_lane?: {
+        anchor_at_binding?: AnchorIdentity | null;
+        anchor_current?: AnchorIdentity | null;
+        freeze?: boolean;
+        anchor_changed_since_binding?: boolean | null;
+    } | null;
+}
+/**
+ * Stranger view. Uses verified signed claims and an on-chain payer check.
+ * Ignores a stamped freeze bit. Unsigned payment.ref is not an assertion.
+ */
+export declare function receiptLaneFromVerification({ receipt, claims, issuerValid, payer, head, now, }: {
+    receipt: ReceiptLaneSource | null | undefined;
+    claims?: SignedClaims | null;
+    issuerValid?: boolean;
+    payer?: LanePayer | null;
+    head?: ReceiptTreeHead | null;
+    now?: number;
+}): ReceiptLane;
+export {};
+//# sourceMappingURL=receipt-lane.d.ts.map

package/dist/receipt-lane.d.ts.map

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