@cardanowall/sdk-ts 0.0.0

package/dist/verifier/index.d.cts

@@ -0,0 +1,176 @@
+import { g as VerifyReport, E as ExitCode, h as VerifyTxInput, a as Profile, f as VerifyRecordSignature, l as VerifyUriCheck, d as VerifyItemDecryption, e as VerifyMerkleCheck, j as VerifyTxSummary, k as VerifyTxWitness } from '../types-CLXdbjqr.cjs';
+export { D as DecryptionVerdict, I as ItemHashCheck, M as MerkleVerdict, N as Network, P as PROFILE_RANK, S as SignatureFailureReason, b as SignatureVerdict, c as SignerType, V as Verdict, i as VerifyTxOutput } from '../types-CLXdbjqr.cjs';
+import { F as FetchOutbound, H as HttpCallRecord } from '../fetch-outbound-BT5-NiYN.cjs';
+export { B as BodyTooLargeError, D as DEFAULT_OUTBOUND_MAX_BYTES, a as DENY_HOSTS_DEFAULT, b as DenyHostError, c as FetchOutboundOptions, d as FetchOutboundResult, O as OutboundExhaustedError, R as RetryConfig, U as UnsupportedMethodError, g as UnsupportedProtocolError, W as WrapFetchOutboundConfig, h as defaultFetchOutbound, i as fetchOutbound, w as wrapFetchOutbound } from '../fetch-outbound-BT5-NiYN.cjs';
+import { PoeRecord, ValidationIssue } from '@cardanowall/poe-standard';
+export { ValidationIssue } from '@cardanowall/poe-standard';
+
+declare const CONFIRMATION_DEPTH_THRESHOLD_DEFAULT = 15;
+declare function verifyTx(input: VerifyTxInput): Promise<VerifyReport>;
+/**
+ * `verifyResolved` — same pipeline as `verifyTx` starting from step 3
+ * (structural validator). The caller has already resolved the label-309
+ * metadata bytes + block-info tuple from somewhere other than a live chain
+ * fetch (typically an indexer database mirror).
+ *
+ * Use this when you trust an upstream indexer for the (metadataCbor,
+ * blockTime, blockSlot, numConfirmations) tuple and want to skip the
+ * /tx_cbor + /tx_info round-trip. The caller is responsible for the
+ * confidence that the supplied bytes actually came from a CIP-309 label-309
+ * metadata field of a confirmed Cardano transaction.
+ */
+declare function verifyResolved(input: {
+    txHash: string;
+    metadataCbor: Uint8Array;
+    txCbor?: Uint8Array;
+    numConfirmations: number;
+    blockTime?: number;
+    blockSlot?: number;
+    network?: VerifyReport['network'];
+    cardanoNetwork?: VerifyTxInput['cardanoNetwork'];
+    profile?: Profile;
+    confirmationDepthThreshold?: number;
+    fetchOutbound?: FetchOutbound;
+    denyHosts?: ReadonlyArray<string>;
+    decryption?: VerifyTxInput['decryption'];
+    verifyMerkle?: boolean;
+}): Promise<VerifyReport>;
+declare function exitCodeForVerdict(report: VerifyReport): ExitCode;
+
+interface VerifyRecordSignaturesArgs {
+    readonly record: PoeRecord;
+    readonly input: VerifyTxInput;
+}
+declare function verifyRecordSignatures(args: VerifyRecordSignaturesArgs): Promise<VerifyRecordSignature[]>;
+
+interface TryDecryptionsArgs {
+    readonly record: PoeRecord;
+    readonly input: VerifyTxInput;
+    readonly fetchFn: FetchOutbound;
+    readonly httpCalls: HttpCallRecord[];
+    readonly uriChecksOut: VerifyUriCheck[];
+    readonly allowUriFetch: boolean;
+}
+interface TryDecryptionsResult {
+    readonly results: VerifyItemDecryption[];
+}
+declare function tryDecryptions(args: TryDecryptionsArgs): Promise<TryDecryptionsResult>;
+
+interface VerifyMerkleArgs {
+    readonly record: PoeRecord;
+    readonly input: VerifyTxInput;
+    readonly fetchFn: FetchOutbound;
+    readonly uriChecksOut: VerifyUriCheck[];
+}
+interface VerifyMerkleResult {
+    readonly checks: VerifyMerkleCheck[];
+}
+declare function verifyMerkleCommitments(args: VerifyMerkleArgs): Promise<VerifyMerkleResult>;
+
+declare const DEFAULT_PROFILE: Profile;
+declare function profileImplements(actual: Profile, required: Profile): boolean;
+interface ProfileSkipsResult {
+    readonly skips: ValidationIssue[];
+    readonly verifySignatures: boolean;
+    readonly verifyDecrypt: boolean;
+}
+declare function planProfileSkips(profile: Profile, record: PoeRecord): ProfileSkipsResult;
+
+interface ResolvedTx {
+    readonly txCbor: Uint8Array;
+    readonly numConfirmations: number;
+    readonly blockTime: number;
+    readonly blockSlot: number;
+    readonly provider: 'koios' | 'blockfrost';
+    readonly providerUrl: string;
+}
+declare const KOIOS_MAINNET_URL = "https://api.koios.rest/api/v1";
+declare const BLOCKFROST_MAINNET_HOST = "https://cardano-mainnet.blockfrost.io/api/v0";
+declare class NotACip309RecordError extends Error {
+    readonly code: "METADATA_NOT_FOUND";
+    constructor(message: string);
+}
+declare function resolveCardanoTx(args: {
+    readonly input: VerifyTxInput;
+    readonly fetchFn: FetchOutbound;
+}): Promise<ResolvedTx>;
+declare function extractLabel309Metadata(txCbor: Uint8Array): Uint8Array | null;
+
+/**
+ * Byte-faithful components of a Cardano transaction, located by walking the
+ * tx CBOR without a decode-then-re-encode pass.
+ *
+ * `txBody` and `witnessSet` are EXACT on-chain byte slices: `blake2b256(txBody)`
+ * equals the transaction hash, and the witness set decodes to the vkey
+ * witnesses that authorised the transaction. The slices are produced by the
+ * same position-aware walk that finds label 309, so they never round-trip
+ * through a CBOR re-encoder.
+ *
+ * `label309` is the reassembled label-309 value (chunked-bytes concatenated;
+ * see `reassembleLabel309Value`), `null` when auxiliary_data is null/undefined
+ * or label 309 is absent. `auxMetadataLabels` is the ascending-sorted list of
+ * every integer key in the auxiliary metadata map (`[]` when aux is null).
+ */
+interface TxComponents {
+    readonly label309: Uint8Array | null;
+    readonly txBody: Uint8Array;
+    readonly witnessSet: Uint8Array;
+    readonly auxMetadataLabels: number[];
+}
+/**
+ * Walk the transaction CBOR once and return its byte-faithful components.
+ *
+ * Throws `RangeError("MALFORMED_CBOR: …")` on structural violations. The body
+ * and witness-set slices are the producer's ORIGINAL bytes; `label309` carries
+ * the same byte-faithful guarantee `sliceLabel309Value` documents (no
+ * decode-then-re-encode, so non-canonical encodings reach the structural
+ * validator unchanged).
+ */
+declare function sliceTxComponents(txCbor: Uint8Array): TxComponents;
+/**
+ * Extract the byte slice corresponding to the value under metadata label 309.
+ * Returns `null` when auxiliary_data is null/undefined or when label 309 is
+ * absent. Throws `RangeError("MALFORMED_CBOR: …")` on structural violations.
+ *
+ * Returns the producer's ORIGINAL on-chain bytes — no decode-then-re-encode
+ * pass. The structural validator MUST receive these bytes verbatim so
+ * non-canonical encodings surface as `MALFORMED_CBOR` rather than being
+ * silently laundered.
+ */
+declare function sliceLabel309Value(txCbor: Uint8Array): Uint8Array | null;
+
+/**
+ * Decode the vkey witnesses of a transaction and verify each signature against
+ * the transaction body.
+ *
+ * Each Cardano vkey witness is `[vkey(32B), signature(64B)]`; the signed
+ * message is `blake2b256(txBody)` (the transaction hash). A witness whose vkey
+ * or signature is malformed, or whose signature does not verify, is reported
+ * with `signature_valid: false` rather than dropped — the caller surfaces it
+ * informationally and never fails the record on it.
+ */
+declare function decodeTxWitnesses(witnessSetBytes: Uint8Array, txBodyBytes: Uint8Array): VerifyTxWitness[];
+/**
+ * Decode a transaction body into a JSON-safe summary: fee, input/output counts,
+ * the output addresses + lovelace amounts, validity interval, required signer
+ * key hashes, and network id.
+ *
+ * All lovelace amounts are serialised as DECIMAL STRINGS so they survive JSON
+ * round-trips exactly (Cardano coin values can exceed `Number.MAX_SAFE_INTEGER`
+ * and BigInt is not JSON-native). Coin math is performed with BigInt internally.
+ */
+declare function decodeTxSummary(txBodyBytes: Uint8Array, witnessSetBytes: Uint8Array, network: 'mainnet' | 'preprod'): VerifyTxSummary;
+
+interface FetchItemCiphertextArgs {
+    readonly uris: ReadonlyArray<ReadonlyArray<string>>;
+    readonly arweaveGateways?: ReadonlyArray<string> | undefined;
+    readonly ipfsGateways?: ReadonlyArray<string> | undefined;
+    readonly fetchFn: FetchOutbound;
+    readonly uriChecksOut: VerifyUriCheck[];
+    readonly itemIndex: number;
+}
+declare function fetchItemCiphertext(args: FetchItemCiphertextArgs): Promise<Uint8Array>;
+
+declare function verifyReportToDict(report: VerifyReport): Record<string, unknown>;
+
+export { BLOCKFROST_MAINNET_HOST, CONFIRMATION_DEPTH_THRESHOLD_DEFAULT, DEFAULT_PROFILE, ExitCode, FetchOutbound, HttpCallRecord, KOIOS_MAINNET_URL, NotACip309RecordError, Profile, type ResolvedTx, type TxComponents, VerifyItemDecryption, VerifyMerkleCheck, VerifyRecordSignature, VerifyReport, VerifyTxInput, VerifyTxSummary, VerifyTxWitness, VerifyUriCheck, decodeTxSummary, decodeTxWitnesses, exitCodeForVerdict, extractLabel309Metadata, fetchItemCiphertext, planProfileSkips, profileImplements, resolveCardanoTx, sliceLabel309Value, sliceTxComponents, tryDecryptions, verifyMerkleCommitments, verifyRecordSignatures, verifyReportToDict, verifyResolved, verifyTx };

package/dist/verifier/index.d.ts

@@ -0,0 +1,176 @@
+import { g as VerifyReport, E as ExitCode, h as VerifyTxInput, a as Profile, f as VerifyRecordSignature, l as VerifyUriCheck, d as VerifyItemDecryption, e as VerifyMerkleCheck, j as VerifyTxSummary, k as VerifyTxWitness } from '../types-B8Q3gW54.js';
+export { D as DecryptionVerdict, I as ItemHashCheck, M as MerkleVerdict, N as Network, P as PROFILE_RANK, S as SignatureFailureReason, b as SignatureVerdict, c as SignerType, V as Verdict, i as VerifyTxOutput } from '../types-B8Q3gW54.js';
+import { F as FetchOutbound, H as HttpCallRecord } from '../fetch-outbound-BT5-NiYN.js';
+export { B as BodyTooLargeError, D as DEFAULT_OUTBOUND_MAX_BYTES, a as DENY_HOSTS_DEFAULT, b as DenyHostError, c as FetchOutboundOptions, d as FetchOutboundResult, O as OutboundExhaustedError, R as RetryConfig, U as UnsupportedMethodError, g as UnsupportedProtocolError, W as WrapFetchOutboundConfig, h as defaultFetchOutbound, i as fetchOutbound, w as wrapFetchOutbound } from '../fetch-outbound-BT5-NiYN.js';
+import { PoeRecord, ValidationIssue } from '@cardanowall/poe-standard';
+export { ValidationIssue } from '@cardanowall/poe-standard';
+
+declare const CONFIRMATION_DEPTH_THRESHOLD_DEFAULT = 15;
+declare function verifyTx(input: VerifyTxInput): Promise<VerifyReport>;
+/**
+ * `verifyResolved` — same pipeline as `verifyTx` starting from step 3
+ * (structural validator). The caller has already resolved the label-309
+ * metadata bytes + block-info tuple from somewhere other than a live chain
+ * fetch (typically an indexer database mirror).
+ *
+ * Use this when you trust an upstream indexer for the (metadataCbor,
+ * blockTime, blockSlot, numConfirmations) tuple and want to skip the
+ * /tx_cbor + /tx_info round-trip. The caller is responsible for the
+ * confidence that the supplied bytes actually came from a CIP-309 label-309
+ * metadata field of a confirmed Cardano transaction.
+ */
+declare function verifyResolved(input: {
+    txHash: string;
+    metadataCbor: Uint8Array;
+    txCbor?: Uint8Array;
+    numConfirmations: number;
+    blockTime?: number;
+    blockSlot?: number;
+    network?: VerifyReport['network'];
+    cardanoNetwork?: VerifyTxInput['cardanoNetwork'];
+    profile?: Profile;
+    confirmationDepthThreshold?: number;
+    fetchOutbound?: FetchOutbound;
+    denyHosts?: ReadonlyArray<string>;
+    decryption?: VerifyTxInput['decryption'];
+    verifyMerkle?: boolean;
+}): Promise<VerifyReport>;
+declare function exitCodeForVerdict(report: VerifyReport): ExitCode;
+
+interface VerifyRecordSignaturesArgs {
+    readonly record: PoeRecord;
+    readonly input: VerifyTxInput;
+}
+declare function verifyRecordSignatures(args: VerifyRecordSignaturesArgs): Promise<VerifyRecordSignature[]>;
+
+interface TryDecryptionsArgs {
+    readonly record: PoeRecord;
+    readonly input: VerifyTxInput;
+    readonly fetchFn: FetchOutbound;
+    readonly httpCalls: HttpCallRecord[];
+    readonly uriChecksOut: VerifyUriCheck[];
+    readonly allowUriFetch: boolean;
+}
+interface TryDecryptionsResult {
+    readonly results: VerifyItemDecryption[];
+}
+declare function tryDecryptions(args: TryDecryptionsArgs): Promise<TryDecryptionsResult>;
+
+interface VerifyMerkleArgs {
+    readonly record: PoeRecord;
+    readonly input: VerifyTxInput;
+    readonly fetchFn: FetchOutbound;
+    readonly uriChecksOut: VerifyUriCheck[];
+}
+interface VerifyMerkleResult {
+    readonly checks: VerifyMerkleCheck[];
+}
+declare function verifyMerkleCommitments(args: VerifyMerkleArgs): Promise<VerifyMerkleResult>;
+
+declare const DEFAULT_PROFILE: Profile;
+declare function profileImplements(actual: Profile, required: Profile): boolean;
+interface ProfileSkipsResult {
+    readonly skips: ValidationIssue[];
+    readonly verifySignatures: boolean;
+    readonly verifyDecrypt: boolean;
+}
+declare function planProfileSkips(profile: Profile, record: PoeRecord): ProfileSkipsResult;
+
+interface ResolvedTx {
+    readonly txCbor: Uint8Array;
+    readonly numConfirmations: number;
+    readonly blockTime: number;
+    readonly blockSlot: number;
+    readonly provider: 'koios' | 'blockfrost';
+    readonly providerUrl: string;
+}
+declare const KOIOS_MAINNET_URL = "https://api.koios.rest/api/v1";
+declare const BLOCKFROST_MAINNET_HOST = "https://cardano-mainnet.blockfrost.io/api/v0";
+declare class NotACip309RecordError extends Error {
+    readonly code: "METADATA_NOT_FOUND";
+    constructor(message: string);
+}
+declare function resolveCardanoTx(args: {
+    readonly input: VerifyTxInput;
+    readonly fetchFn: FetchOutbound;
+}): Promise<ResolvedTx>;
+declare function extractLabel309Metadata(txCbor: Uint8Array): Uint8Array | null;
+
+/**
+ * Byte-faithful components of a Cardano transaction, located by walking the
+ * tx CBOR without a decode-then-re-encode pass.
+ *
+ * `txBody` and `witnessSet` are EXACT on-chain byte slices: `blake2b256(txBody)`
+ * equals the transaction hash, and the witness set decodes to the vkey
+ * witnesses that authorised the transaction. The slices are produced by the
+ * same position-aware walk that finds label 309, so they never round-trip
+ * through a CBOR re-encoder.
+ *
+ * `label309` is the reassembled label-309 value (chunked-bytes concatenated;
+ * see `reassembleLabel309Value`), `null` when auxiliary_data is null/undefined
+ * or label 309 is absent. `auxMetadataLabels` is the ascending-sorted list of
+ * every integer key in the auxiliary metadata map (`[]` when aux is null).
+ */
+interface TxComponents {
+    readonly label309: Uint8Array | null;
+    readonly txBody: Uint8Array;
+    readonly witnessSet: Uint8Array;
+    readonly auxMetadataLabels: number[];
+}
+/**
+ * Walk the transaction CBOR once and return its byte-faithful components.
+ *
+ * Throws `RangeError("MALFORMED_CBOR: …")` on structural violations. The body
+ * and witness-set slices are the producer's ORIGINAL bytes; `label309` carries
+ * the same byte-faithful guarantee `sliceLabel309Value` documents (no
+ * decode-then-re-encode, so non-canonical encodings reach the structural
+ * validator unchanged).
+ */
+declare function sliceTxComponents(txCbor: Uint8Array): TxComponents;
+/**
+ * Extract the byte slice corresponding to the value under metadata label 309.
+ * Returns `null` when auxiliary_data is null/undefined or when label 309 is
+ * absent. Throws `RangeError("MALFORMED_CBOR: …")` on structural violations.
+ *
+ * Returns the producer's ORIGINAL on-chain bytes — no decode-then-re-encode
+ * pass. The structural validator MUST receive these bytes verbatim so
+ * non-canonical encodings surface as `MALFORMED_CBOR` rather than being
+ * silently laundered.
+ */
+declare function sliceLabel309Value(txCbor: Uint8Array): Uint8Array | null;
+
+/**
+ * Decode the vkey witnesses of a transaction and verify each signature against
+ * the transaction body.
+ *
+ * Each Cardano vkey witness is `[vkey(32B), signature(64B)]`; the signed
+ * message is `blake2b256(txBody)` (the transaction hash). A witness whose vkey
+ * or signature is malformed, or whose signature does not verify, is reported
+ * with `signature_valid: false` rather than dropped — the caller surfaces it
+ * informationally and never fails the record on it.
+ */
+declare function decodeTxWitnesses(witnessSetBytes: Uint8Array, txBodyBytes: Uint8Array): VerifyTxWitness[];
+/**
+ * Decode a transaction body into a JSON-safe summary: fee, input/output counts,
+ * the output addresses + lovelace amounts, validity interval, required signer
+ * key hashes, and network id.
+ *
+ * All lovelace amounts are serialised as DECIMAL STRINGS so they survive JSON
+ * round-trips exactly (Cardano coin values can exceed `Number.MAX_SAFE_INTEGER`
+ * and BigInt is not JSON-native). Coin math is performed with BigInt internally.
+ */
+declare function decodeTxSummary(txBodyBytes: Uint8Array, witnessSetBytes: Uint8Array, network: 'mainnet' | 'preprod'): VerifyTxSummary;
+
+interface FetchItemCiphertextArgs {
+    readonly uris: ReadonlyArray<ReadonlyArray<string>>;
+    readonly arweaveGateways?: ReadonlyArray<string> | undefined;
+    readonly ipfsGateways?: ReadonlyArray<string> | undefined;
+    readonly fetchFn: FetchOutbound;
+    readonly uriChecksOut: VerifyUriCheck[];
+    readonly itemIndex: number;
+}
+declare function fetchItemCiphertext(args: FetchItemCiphertextArgs): Promise<Uint8Array>;
+
+declare function verifyReportToDict(report: VerifyReport): Record<string, unknown>;
+
+export { BLOCKFROST_MAINNET_HOST, CONFIRMATION_DEPTH_THRESHOLD_DEFAULT, DEFAULT_PROFILE, ExitCode, FetchOutbound, HttpCallRecord, KOIOS_MAINNET_URL, NotACip309RecordError, Profile, type ResolvedTx, type TxComponents, VerifyItemDecryption, VerifyMerkleCheck, VerifyRecordSignature, VerifyReport, VerifyTxInput, VerifyTxSummary, VerifyTxWitness, VerifyUriCheck, decodeTxSummary, decodeTxWitnesses, exitCodeForVerdict, extractLabel309Metadata, fetchItemCiphertext, planProfileSkips, profileImplements, resolveCardanoTx, sliceLabel309Value, sliceTxComponents, tryDecryptions, verifyMerkleCommitments, verifyRecordSignatures, verifyReportToDict, verifyResolved, verifyTx };