@lucid-evolution/tx-graph 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,477 @@
+import { RedeemerTag, TxHash, Credential, Unit, DatumHash, Datum, ScriptType, ScriptHash, Transaction, RewardAddress, UTxO, Provider, TxOutput } from '@lucid-evolution/core-types';
+import * as CML from '@anastasia-labs/cardano-multiplatform-lib-nodejs';
+
+type TraceAmount = string;
+type TraceAssets = Record<Unit | "lovelace", TraceAmount>;
+type TraceOutRef = {
+    readonly txHash: TxHash;
+    readonly outputIndex: number;
+};
+type TraceStatus = "built" | "signed" | "submitted" | "confirmed" | "failed";
+type TraceScriptRef = {
+    readonly type: ScriptType;
+    readonly hash?: ScriptHash;
+    readonly sizeBytes: number;
+};
+type TraceTxOutput = {
+    readonly address: string;
+    readonly paymentCredential?: Credential;
+    readonly stakeCredential?: Credential;
+    readonly assets: TraceAssets;
+    readonly datumHash?: DatumHash;
+    readonly datum?: Datum;
+    readonly scriptRef?: TraceScriptRef;
+};
+type TraceUtxo = TraceOutRef & TraceTxOutput & {
+    readonly resolution: "resolved" | "unresolved" | "genesis";
+    readonly unresolvedReason?: string;
+    readonly tags: string[];
+};
+type TraceRedeemer = {
+    readonly tag: RedeemerTag;
+    readonly index: TraceAmount;
+    readonly redeemerListIndex: number;
+    readonly data: string;
+    readonly exUnits: {
+        readonly mem: TraceAmount;
+        readonly steps: TraceAmount;
+    };
+};
+type TraceEvaluationRedeemer = {
+    readonly tag: RedeemerTag;
+    readonly redeemerIndex: number;
+    readonly exUnits: {
+        readonly mem: TraceAmount;
+        readonly steps: TraceAmount;
+    };
+};
+type TraceWithdrawal = {
+    readonly rewardAddress: RewardAddress;
+    readonly amount: TraceAmount;
+};
+type TraceCertificate = {
+    readonly index: number;
+    readonly kind: number;
+    readonly kindName: string;
+    readonly cbor?: string;
+};
+type TraceValidityInterval = {
+    readonly validFrom?: TraceAmount;
+    readonly validTo?: TraceAmount;
+};
+type TraceTransaction = {
+    readonly hash: TxHash;
+    readonly label?: string;
+    readonly status: TraceStatus;
+    readonly failureMessage?: string;
+    readonly cbor: Transaction;
+    readonly sizeBytes: number;
+    readonly fee: TraceAmount;
+    readonly validityInterval: TraceValidityInterval;
+    readonly inputs: TraceOutRef[];
+    readonly referenceInputs: TraceOutRef[];
+    readonly collateralInputs: TraceOutRef[];
+    readonly collateralReturn?: TraceTxOutput;
+    readonly totalCollateral?: TraceAmount;
+    readonly outputs: TraceUtxo[];
+    readonly mint: TraceAssets;
+    readonly mintedAssets: TraceAssets;
+    readonly burnedAssets: TraceAssets;
+    readonly withdrawals: TraceWithdrawal[];
+    readonly certificates: TraceCertificate[];
+    readonly redeemers: TraceRedeemer[];
+    readonly evaluation?: TraceEvaluationRedeemer[];
+    readonly requiredSigners: string[];
+    readonly auxiliaryDataHash?: string;
+};
+type TraceEdgeKind = "spends" | "reads" | "collateral" | "collateralReturn" | "produces" | "mints" | "burns" | "withdraws" | "certifies" | "requiresSigner";
+type TraceEdge = {
+    readonly kind: TraceEdgeKind;
+    readonly from: string;
+    readonly to: string;
+};
+type TraceWarning = {
+    readonly code: string;
+    readonly message: string;
+    readonly txHash?: TxHash;
+    readonly outRef?: TraceOutRef;
+};
+type TraceAliases = {
+    readonly assets: Record<string, string>;
+    readonly addresses: Record<string, string>;
+};
+type TxGraphTrace = {
+    readonly version: 1;
+    readonly createdAt?: string;
+    readonly transactions: TraceTransaction[];
+    readonly utxos: Record<string, TraceUtxo>;
+    readonly edges: TraceEdge[];
+    readonly warnings: TraceWarning[];
+    readonly aliases: TraceAliases;
+};
+
+type TxGraphTaggerContext = {
+    readonly utxo: TraceUtxo;
+    readonly direction: "input" | "output";
+    readonly transaction: TraceTransaction;
+    readonly graph: TxGraphTrace;
+};
+type TxGraphTagger = (context: TxGraphTaggerContext) => string | ReadonlyArray<string> | undefined;
+declare const tagByAddress: (label: string, address: string) => TxGraphTagger;
+declare const tagByCredential: (label: string, credential: Credential) => TxGraphTagger;
+declare const tagByUnit: (label: string, unit: Unit | "lovelace") => TxGraphTagger;
+declare const tagByPolicyId: (label: string, policyId: string) => TxGraphTagger;
+declare const tagByDatumHash: (label: string, datumHash: DatumHash) => TxGraphTagger;
+declare const tagByDatum: (label: string, predicate: (datum: string, context: TxGraphTaggerContext) => boolean) => TxGraphTagger;
+type TagByScriptRefOptions = {
+    readonly type?: ScriptType;
+    readonly hash?: string;
+};
+declare const tagByScriptRef: (label: string, options?: TagByScriptRefOptions) => TxGraphTagger;
+type TagChangeOptions = {
+    readonly changeAddress?: string;
+    readonly walletAddress?: string;
+    readonly knownWalletUtxos?: ReadonlyArray<UTxO>;
+};
+declare const tagChange: (label: string, options: TagChangeOptions) => TxGraphTagger;
+
+type TxGraphTransactionInput = Transaction | CML.Transaction | {
+    toCBOR: (options?: {
+        canonical: boolean;
+    }) => Transaction;
+} | {
+    toTransaction: () => CML.Transaction;
+};
+type ParseTransactionOptions = {
+    readonly label?: string;
+    readonly status?: TraceStatus;
+};
+declare const parseTransaction: (input: TxGraphTransactionInput, options?: ParseTransactionOptions) => TraceTransaction;
+declare const parseTransactionCbor: (cbor: Transaction, options?: ParseTransactionOptions) => TraceTransaction;
+
+type TxGraphResolutionProvider = Pick<Provider, "getUtxosByOutRef">;
+type TxGraphUtxoResolver = (outRefs: TraceOutRef[]) => Promise<ReadonlyArray<UTxO | TraceUtxo>> | ReadonlyArray<UTxO | TraceUtxo>;
+type TxGraphResolutionSource = "scenario-cache" | "provider" | "known-utxos" | "resolver" | "genesis" | "unresolved";
+type ResolveOutRefsOptions = {
+    readonly provider?: TxGraphResolutionProvider;
+    readonly resolver?: TxGraphUtxoResolver;
+};
+type ResolveOutRefsResult = {
+    readonly utxos: TraceUtxo[];
+    readonly sources: Record<string, TxGraphResolutionSource>;
+    readonly warnings: TraceWarning[];
+};
+type TxGraphResolutionCache = {
+    addProducedUtxos: (utxos: ReadonlyArray<TraceUtxo>) => void;
+    addTransactionOutputs: (transaction: Pick<TraceTransaction, "outputs">) => void;
+    addResolvedUtxos: (utxos: ReadonlyArray<UTxO | TraceUtxo>) => void;
+    getProducedUtxo: (outRef: TraceOutRef) => TraceUtxo | undefined;
+    getKnownUtxo: (outRef: TraceOutRef) => TraceUtxo | undefined;
+    resolveOutRefs: (outRefs: ReadonlyArray<TraceOutRef>, options?: ResolveOutRefsOptions) => Promise<ResolveOutRefsResult>;
+};
+declare const createResolutionCache: () => TxGraphResolutionCache;
+declare const outRefKey: (outRef: TraceOutRef) => string;
+declare const parseOutRefKey: (key: string) => TraceOutRef;
+declare const producedUtxosFromTransaction: (transaction: Pick<TraceTransaction, "outputs">) => TraceUtxo[];
+declare const toTraceUtxo: (utxo: UTxO, options?: {
+    readonly tags?: ReadonlyArray<string>;
+    readonly resolution?: TraceUtxo["resolution"];
+    readonly unresolvedReason?: string;
+}) => TraceUtxo;
+declare const toTraceTxOutput: (output: TxOutput) => TraceTxOutput;
+declare const unresolvedUtxo: (outRef: TraceOutRef, reason: string) => TraceUtxo;
+declare const genesisUtxo: (outRef: TraceOutRef) => TraceUtxo;
+
+type VisualRenderMode = "overview" | "audit" | "debug";
+type VisualRenderView = "flow" | "scriptInteraction";
+type VisualPrivacyPolicy = {
+    readonly hash: "full" | "short" | "hidden";
+    readonly address: "alias" | "short" | "full" | "hidden";
+    readonly datum: "marker" | "hash" | "short" | "full" | "hidden";
+    readonly redeemer: "label" | "constructor" | "short" | "full" | "hidden";
+    readonly cbor: "hidden" | "prefix" | "full";
+};
+type VisualComplexityBudget = {
+    readonly maxVisibleInputs: number;
+    readonly maxVisibleOutputs: number;
+    readonly maxVisibleAssetsPerUtxo: number;
+    readonly maxVisibleSigners: number;
+    readonly maxVisibleWarnings: number;
+    readonly maxVisibleRedeemerFields: number;
+};
+type VisualRendererOptions = {
+    readonly mode?: VisualRenderMode;
+    readonly view?: VisualRenderView;
+    readonly privacy?: Partial<VisualPrivacyPolicy>;
+    readonly budget?: Partial<VisualComplexityBudget>;
+};
+type ResolvedVisualRendererOptions = {
+    readonly mode: VisualRenderMode;
+    readonly view: VisualRenderView;
+    readonly privacy: VisualPrivacyPolicy;
+    readonly budget: VisualComplexityBudget;
+};
+type VisualEdgeStyle = {
+    readonly color: string;
+    readonly style: "solid" | "dashed" | "dotted";
+};
+declare const resolveVisualRendererOptions: (options?: VisualRendererOptions) => ResolvedVisualRendererOptions;
+declare const visualEdgeStyle: (kind: string) => VisualEdgeStyle;
+
+type VisualTone = "neutral" | "info" | "success" | "warning" | "danger" | "accent";
+type VisualNodeKind = "transaction" | "utxo" | "asset" | "signer" | "withdrawal" | "certificate" | "collateralReturn" | "diagnostic";
+type VisualEdgeKind = "spend" | "read" | "collateral" | "produce" | "collateralReturn" | "mint" | "burn" | "withdraw" | "certify" | "sign" | "diagnostic" | "summary";
+type VisualPortSide = "left" | "right" | "top" | "bottom";
+type VisualField = {
+    readonly id: string;
+    readonly label: string;
+    readonly rawLabel?: string;
+    readonly value: string;
+    readonly rawValue?: string;
+    readonly tone?: VisualTone;
+    readonly mono?: boolean;
+};
+type VisualSection = {
+    readonly id: string;
+    readonly title: string;
+    readonly rows: VisualField[];
+    readonly collapsed?: boolean;
+};
+type VisualChip = {
+    readonly label: string;
+    readonly tone?: VisualTone;
+};
+type VisualPort = {
+    readonly id: string;
+    readonly nodeId: string;
+    readonly side: VisualPortSide;
+    readonly label: string;
+    readonly edgeKind?: VisualEdgeKind;
+};
+type VisualRawRef = {
+    readonly type: "transaction";
+    readonly txHash: string;
+} | {
+    readonly type: "utxo";
+    readonly outRef: TraceOutRef;
+} | {
+    readonly type: "assetPolicy";
+    readonly policyId: string;
+} | {
+    readonly type: "signer";
+    readonly keyHash: string;
+} | {
+    readonly type: "withdrawal";
+    readonly rewardAddress: string;
+} | {
+    readonly type: "certificate";
+    readonly txHash: string;
+    readonly index: number;
+} | {
+    readonly type: "collateralReturn";
+    readonly txHash: string;
+} | {
+    readonly type: "diagnostic";
+    readonly code: string;
+    readonly count?: number;
+    readonly group?: string;
+};
+type VisualNode = {
+    readonly id: string;
+    readonly kind: VisualNodeKind;
+    readonly title: string;
+    readonly subtitle?: string;
+    readonly sections: VisualSection[];
+    readonly ports: VisualPort[];
+    readonly chips: VisualChip[];
+    readonly severity?: "info" | "warning" | "error";
+    readonly rawRef: VisualRawRef;
+};
+type RedeemerKey = {
+    readonly tag: TraceRedeemer["tag"];
+    readonly index: string;
+    readonly redeemerListIndex: number;
+};
+type VisualAction = {
+    readonly label: string;
+    readonly intent?: string;
+    readonly fields?: Record<string, string>;
+    readonly source: "user" | "schema" | "constructor" | "generic";
+    readonly confidence: "high" | "medium" | "fallback";
+};
+type VisualEdgeTargetRef = {
+    readonly type: "input";
+    readonly inputKind: "spend" | "read" | "collateral";
+    readonly txHash: string;
+    readonly index: number;
+    readonly outRef: TraceOutRef;
+} | {
+    readonly type: "output";
+    readonly txHash: string;
+    readonly index: number;
+    readonly outRef: TraceOutRef;
+} | {
+    readonly type: "assetPolicy";
+    readonly txHash: string;
+    readonly policyId: string;
+    readonly policyIndex: number;
+    readonly assets: Record<string, string>;
+} | {
+    readonly type: "withdrawal";
+    readonly txHash: string;
+    readonly index: number;
+    readonly rewardAddress: string;
+} | {
+    readonly type: "certificate";
+    readonly txHash: string;
+    readonly index: number;
+} | {
+    readonly type: "signer";
+    readonly txHash: string;
+    readonly keyHash: string;
+} | {
+    readonly type: "collateralReturn";
+    readonly txHash: string;
+} | {
+    readonly type: "diagnostic";
+    readonly txHash?: string;
+    readonly code: string;
+    readonly count?: number;
+    readonly group?: string;
+};
+type VisualEdge = {
+    readonly id: string;
+    readonly kind: VisualEdgeKind;
+    readonly from: string;
+    readonly to: string;
+    readonly fromPort?: string;
+    readonly toPort?: string;
+    readonly label: string;
+    readonly action?: VisualAction;
+    readonly redeemerKey?: RedeemerKey;
+    readonly targetRef: VisualEdgeTargetRef;
+    readonly severity?: "info" | "warning" | "error";
+    readonly rawRef: VisualRawRef;
+};
+type VisualDiagnostic = {
+    readonly id: string;
+    readonly severity: "warning" | "error";
+    readonly code: string;
+    readonly message: string;
+    readonly txHash?: string;
+    readonly outRef?: TraceOutRef;
+    readonly redeemerKey?: RedeemerKey;
+};
+type VisualLegendItem = {
+    readonly kind: string;
+    readonly label: string;
+};
+type VisualLegend = {
+    readonly nodes: VisualLegendItem[];
+    readonly edges: VisualLegendItem[];
+};
+type SemanticRenderGraph = {
+    readonly version: 1;
+    readonly nodes: VisualNode[];
+    readonly edges: VisualEdge[];
+    readonly diagnostics: VisualDiagnostic[];
+    readonly legend: VisualLegend;
+    readonly aliases: TraceAliases;
+};
+type RedeemerDescriberContext = {
+    readonly trace: TxGraphTrace;
+    readonly transaction: TraceTransaction;
+    readonly redeemer: TraceRedeemer;
+    readonly target: VisualEdgeTargetRef;
+    readonly edge: Omit<VisualEdge, "action">;
+};
+type RedeemerDescriber = (context: RedeemerDescriberContext) => VisualAction | undefined;
+type RedeemerSelector = {
+    readonly tag: TraceRedeemer["tag"];
+    readonly index: number | string;
+    readonly txHash?: string;
+    readonly target?: (target: VisualEdgeTargetRef) => boolean;
+};
+type ConstructorRedeemerSelector = RedeemerSelector & {
+    readonly constructor: number;
+};
+type SemanticRenderOptions = {
+    readonly redeemers?: ReadonlyArray<RedeemerDescriber>;
+};
+declare const buildSemanticRenderGraph: (trace: TxGraphTrace, options?: SemanticRenderOptions) => SemanticRenderGraph;
+declare const labelRedeemer: (selector: RedeemerSelector, label: string, intent?: string) => RedeemerDescriber;
+declare const describeRedeemerByConstructor: (selector: ConstructorRedeemerSelector, label: string, intent?: string) => RedeemerDescriber;
+declare const describeRedeemerWith: (describe: RedeemerDescriber) => RedeemerDescriber;
+
+type TraceToDotOptions = VisualRendererOptions & SemanticRenderOptions & {
+    readonly graphName?: string;
+    readonly legacy?: boolean;
+};
+declare const traceToDot: (trace: TxGraphTrace, options?: TraceToDotOptions) => string;
+
+type FormattedSemanticGraph = {
+    readonly nodes: VisualNode[];
+    readonly edges: VisualEdge[];
+};
+
+type TraceToSvgOptions = VisualRendererOptions & SemanticRenderOptions & {
+    readonly title?: string;
+};
+declare const traceToSvg: (trace: TxGraphTrace, options?: TraceToSvgOptions) => string;
+declare const semanticSvgForTesting: (trace: TxGraphTrace, options?: TraceToSvgOptions) => {
+    readonly semantic: FormattedSemanticGraph;
+    readonly nodes: VisualNode[];
+};
+
+type TraceToHtmlOptions = TraceToSvgOptions & SemanticRenderOptions & {
+    readonly title?: string;
+    readonly includeRawMetadata?: boolean;
+};
+declare const traceToHtml: (trace: TxGraphTrace, options?: TraceToHtmlOptions) => string;
+
+type TraceToMermaidOptions = VisualRendererOptions & SemanticRenderOptions & {
+    readonly direction?: "LR" | "TD";
+    readonly legacy?: boolean;
+};
+declare const traceToMermaid: (trace: TxGraphTrace, options?: TraceToMermaidOptions) => string;
+
+type TxGraphProviderWrapperOptions = {
+    readonly submitLabel?: string;
+    readonly evaluateLabel?: string;
+    readonly recordEvaluate?: boolean;
+};
+declare const wrapProvider: (provider: Provider, graph: TxGraph, options?: TxGraphProviderWrapperOptions) => Provider;
+
+type CreateTxGraphOptions = {
+    readonly provider?: TxGraphResolutionProvider;
+    readonly resolver?: TxGraphUtxoResolver;
+    readonly labels?: ReadonlyArray<TxGraphTagger>;
+    readonly assets?: Record<string, string>;
+    readonly addresses?: Record<string, string>;
+    readonly aliases?: Partial<TraceAliases>;
+    readonly createdAt?: string;
+};
+type TxGraphRecordOptions = ParseTransactionOptions & {
+    readonly status?: TraceStatus;
+    readonly failureMessage?: string;
+    readonly evaluation?: ReadonlyArray<TraceEvaluationRedeemer>;
+};
+type TxGraph = {
+    record: (tx: TxGraphTransactionInput, options?: TxGraphRecordOptions) => Promise<TraceTransaction>;
+    recordCbor: (cbor: string, options?: TxGraphRecordOptions) => Promise<TraceTransaction>;
+    addResolvedUtxos: (utxos: ReadonlyArray<UTxO | TraceUtxo>) => void;
+    resolveWith: (resolver: TxGraphUtxoResolver) => void;
+    addWarning: (warning: TraceWarning) => void;
+    wrapProvider: (provider: Provider, options?: TxGraphProviderWrapperOptions) => Provider;
+    toJSON: () => TxGraphTrace;
+    toSemantic: (options?: SemanticRenderOptions) => SemanticRenderGraph;
+    toDot: (options?: TraceToDotOptions) => string;
+    toHtml: (options?: TraceToHtmlOptions) => string;
+    toMermaid: (options?: TraceToMermaidOptions) => string;
+    toSvg: (options?: TraceToSvgOptions) => string;
+};
+declare const createTxGraph: (options?: CreateTxGraphOptions) => TxGraph;
+
+declare const traceToJSON: (trace: TxGraphTrace) => TxGraphTrace;
+
+export { type ConstructorRedeemerSelector, type CreateTxGraphOptions, type ParseTransactionOptions, type RedeemerDescriber, type RedeemerDescriberContext, type RedeemerKey, type RedeemerSelector, type ResolveOutRefsOptions, type ResolveOutRefsResult, type ResolvedVisualRendererOptions, type SemanticRenderGraph, type SemanticRenderOptions, type TagByScriptRefOptions, type TagChangeOptions, type TraceAliases, type TraceAmount, type TraceAssets, type TraceCertificate, type TraceEdge, type TraceEdgeKind, type TraceEvaluationRedeemer, type TraceOutRef, type TraceRedeemer, type TraceScriptRef, type TraceStatus, type TraceToDotOptions, type TraceToHtmlOptions, type TraceToMermaidOptions, type TraceToSvgOptions, type TraceTransaction, type TraceTxOutput, type TraceUtxo, type TraceValidityInterval, type TraceWarning, type TraceWithdrawal, type TxGraph, type TxGraphProviderWrapperOptions, type TxGraphRecordOptions, type TxGraphResolutionCache, type TxGraphResolutionProvider, type TxGraphResolutionSource, type TxGraphTagger, type TxGraphTaggerContext, type TxGraphTrace, type TxGraphTransactionInput, type TxGraphUtxoResolver, type VisualAction, type VisualChip, type VisualComplexityBudget, type VisualDiagnostic, type VisualEdge, type VisualEdgeKind, type VisualEdgeStyle, type VisualEdgeTargetRef, type VisualField, type VisualLegend, type VisualLegendItem, type VisualNode, type VisualNodeKind, type VisualPort, type VisualPortSide, type VisualPrivacyPolicy, type VisualRawRef, type VisualRenderMode, type VisualRenderView, type VisualRendererOptions, type VisualSection, type VisualTone, buildSemanticRenderGraph, createResolutionCache, createTxGraph, describeRedeemerByConstructor, describeRedeemerWith, genesisUtxo, labelRedeemer, outRefKey, parseOutRefKey, parseTransaction, parseTransactionCbor, producedUtxosFromTransaction, resolveVisualRendererOptions, semanticSvgForTesting, tagByAddress, tagByCredential, tagByDatum, tagByDatumHash, tagByPolicyId, tagByScriptRef, tagByUnit, tagChange, toTraceTxOutput, toTraceUtxo, traceToDot, traceToHtml, traceToJSON, traceToMermaid, traceToSvg, unresolvedUtxo, visualEdgeStyle, wrapProvider };