{ "components": { "schemas": { "BrowserView": { "$ref": "browser-view.schema.json" }, "LedgerOperationError": { "additionalProperties": true, "properties": { "error": { "additionalProperties": true, "properties": { "category": { "enum": [ "malformed_hex", "malformed_cbor", "malformed_ledger_operation", "unknown_ledger_operation", "ledger_operation_failed", "missing_context" ], "type": "string" }, "detail": { "type": "string" } }, "required": [ "category", "detail" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "LedgerOperationRequest": { "$ref": "ledger-operation-request.schema.json" }, "LedgerOperationResponse": { "$ref": "ledger-operation-response.schema.json" }, "ProducerTxContext": { "$ref": "producer-tx-context.schema.json" }, "TxEvaluateScriptsResult": { "$ref": "tx-evaluate-scripts-result.schema.json" }, "TxIdentifyResult": { "$ref": "tx-identify-result.schema.json" }, "TxIntentResult": { "$ref": "tx-intent-result.schema.json" }, "TxValidateResult": { "$ref": "tx-validate-result.schema.json" }, "TxWitnessAttachResult": { "$ref": "tx-witness-attach-result.schema.json" }, "TxWitnessPlanResult": { "$ref": "tx-witness-plan-result.schema.json" } } }, "externalDocs": { "description": "Functional API contract", "url": "https://github.com/lambdasistemi/cardano-ledger-inspector/blob/main/specs/001-ledger-functional-layer/contracts/ledger-functional-api.md" }, "info": { "description": "This OpenAPI document describes the JSON control envelope used by host adapters around the Cardano Ledger WASI functional layer. The repository does not publish a stateful hosted service. WASI callers use the same request and response schemas through stdin/stdout; HTTP adapters can expose the POST shape documented here.", "license": { "name": "Apache-2.0", "url": "https://github.com/lambdasistemi/cardano-ledger-inspector/blob/main/LICENSE" }, "summary": "Functional ledger-operation boundary for Cardano transaction tooling.", "title": "Cardano Ledger WASI Functional API", "version": "0.1.0-draft" }, "openapi": "3.1.0", "paths": { "/ledger/operations": { "post": { "description": "Run one ledger-backed function over the supplied transaction CBOR. The host owns workspace state and sends the current transaction bytes on every call. WASI command failures are reported through stderr and process status; HTTP host adapters should map those failures to the JSON error shape documented here.", "operationId": "runLedgerOperation", "requestBody": { "content": { "application/json": { "examples": { "balance": { "summary": "Target shape for best-effort balancing", "value": { "args": { "change": { "address": "addr1...", "policy": "preserve-existing-or-add" }, "constraints": { "allow_collateral_change": true, "allow_output_reordering": false, "max_extra_inputs": 0 }, "network": "mainnet", "protocol_parameters": {}, "slot": 0, "utxo": {} }, "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.balance", "tx_cbor": "84a4..." } }, "browse": { "summary": "Browse a nested transaction value", "value": { "args": { "path": [ "body", "outputs", "#0" ] }, "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.browse", "tx_cbor": "84a4..." } }, "evaluateScripts": { "summary": "Evaluate phase-2 scripts or report missing context", "value": { "args": { "context": { "epoch": "507", "network": "mainnet", "producer_txs": { "0000000000000000000000000000000000000000000000000000000000000000": { "source": "blockfrost.txs.cbor", "tx_cbor": "84a4..." } }, "protocol_parameters": { "_shape": "complete Cardano.Ledger.Core.PParams ConwayEra JSON" }, "slot": "123456789" }, "input_policy": "preserve" }, "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.evaluate.scripts", "tx_cbor": "84a4..." } }, "identify": { "summary": "Identify a transaction", "value": { "args": {}, "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.identify", "tx_cbor": "84a4..." } }, "inspect": { "summary": "Inspect a transaction", "value": { "args": {}, "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.inspect", "tx_cbor": "84a4..." } }, "intent": { "summary": "Summarize signer-visible transaction intent", "value": { "args": { "input_policy": "preserve" }, "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.intent", "tx_cbor": "84a4..." } }, "validate": { "summary": "Validate a transaction or report missing context", "value": { "args": { "context": { "epoch": "507", "network": "mainnet", "producer_txs": { "0000000000000000000000000000000000000000000000000000000000000000": { "source": "blockfrost.txs.cbor", "tx_cbor": "84a4..." } }, "protocol_parameters": { "_shape": "complete Cardano.Ledger.Core.PParams ConwayEra JSON" }, "slot": "123456789" }, "input_policy": "preserve" }, "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.validate", "tx_cbor": "84a4..." } }, "witnessAttach": { "summary": "Attach or replace one vkey witness", "value": { "args": { "vkey_witness_cbor_hex": "825820000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f5840202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f" }, "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.witness.attach", "tx_cbor": "84a4..." } }, "witnessPlan": { "summary": "Plan transaction witnesses", "value": { "args": { "context": { "producer_txs": { "0000000000000000000000000000000000000000000000000000000000000000": { "source": "blockfrost.txs.cbor", "tx_cbor": "84a4..." } }, "resolution": { "errors": [], "missing": [], "provider": "blockfrost", "requested_input_count": 1, "requested_reference_input_count": 0, "requested_tx_count": 1, "resolved_count": 1, "source": "tx-cbor", "unspent_status": "not_checked" } }, "input_policy": "preserve" }, "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.witness.plan", "tx_cbor": "84a4..." } } }, "schema": { "$ref": "ledger-operation-request.schema.json" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "evaluateScripts": { "summary": "Script evaluation response envelope", "value": { "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.evaluate.scripts", "result": { "script_evaluation": { "body_hash": "1111111111111111111111111111111111111111111111111111111111111111", "complete": false, "context": { "decoded_producer_tx_count": 0, "evaluated_redeemer_count": 0, "input_policy": "preserve", "producer_tx_count": 0, "redeemer_count": 1, "unspent_status": "not_checked" }, "errors": [], "failures": [], "missing_context": [ { "index": 0, "input_kind": "input", "kind": "source_output", "message": "Supply producer transaction CBOR for the referenced transaction input.", "path": [ "body", "inputs", "#0" ], "required_for": [ "script.evaluate" ], "tx_id": "0000000000000000000000000000000000000000000000000000000000000000" } ], "redeemers": [ { "budget_ex_units": { "memory": "1000000", "steps": "500000000" }, "evaluated_ex_units": null, "index": 0, "key": "spend#0", "missing_context": [ "source_output" ], "path": [ "body", "inputs", "#0" ], "purpose": "spend", "redeemer_data_hash": "2222222222222222222222222222222222222222222222222222222222222222", "status": "not_evaluated", "warnings": [] } ], "resolved_inputs": [], "resolved_reference_inputs": [], "scripts_evaluate_for_supplied_context": null, "status": "incomplete", "total_ex_units": { "memory": "0", "partial": true, "steps": "0" }, "tx_id": "0000000000000000000000000000000000000000000000000000000000000000", "warnings": [] } } } }, "identify": { "summary": "Identity response envelope", "value": { "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.identify", "result": { "identification": { "body_hash": "1111111111111111111111111111111111111111111111111111111111111111", "cert_count": 0, "era": "Conway", "fee_lovelace": "0", "input_count": 1, "output_count": 2, "reference_input_count": 0, "required_signer_count": 1, "tx_id": "0000000000000000000000000000000000000000000000000000000000000000", "tx_size_bytes": 1234, "withdrawal_count": 0, "witness_counts": { "bootstrap": 0, "datum": 0, "native_script": 0, "plutus_v1": 0, "plutus_v2": 0, "plutus_v3": 0, "redeemer": 0, "vkey": 1 } } } } }, "inspect": { "summary": "Inspection response envelope", "value": { "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.inspect", "result": { "browser": { "breadcrumbs": [ { "label": "tx", "path": "[]" } ], "currentJson": "{}", "currentPath": "[]", "rows": [], "subtitle": "object / 10 fields", "title": "tx", "valid": true }, "inspection": { "era": "Conway", "fee_lovelace": "0" } } } }, "intent": { "summary": "Signer-focused intent response envelope", "value": { "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.intent", "result": { "intent": { "body_hash": "1111111111111111111111111111111111111111111111111111111111111111", "claims": [ { "detail": "Required to pay Antithesis as vendor / destination Network Compliance's treasury / metadata label 1694 / self-declared", "label": "Swap ADA<->USDM", "value": "Swapping ADA for $100k at a rate of $0.245 per ADA" } ], "fee_lovelace": "1043795", "input_policy": "preserve", "metrics": [ { "label": "Fee", "value": "1.043795 ADA" }, { "label": "Signer net ADA", "value": "unknown" }, { "label": "Missing signers", "value": "2 missing required signers" } ], "sections": [ { "empty": "No signer value perspective available.", "rows": [ { "copyValue": "unknown", "detail": "producer transaction CBOR must resolve every regular input before signer net can be known", "label": "Net signer ADA", "path": "[\"intent\",\"value\",\"signer_perspective\",\"#0\"]", "value": "unknown" } ], "title": "Signer value perspective" }, { "empty": "No transaction effects reported.", "rows": [], "title": "Critical effects" }, { "empty": "No declared required signers.", "rows": [ { "copyValue": "8bd03209d227956aaf9670751e0aa2057b51c1537a43f155b24fb1c1", "detail": "declared required signer not present in vkey or bootstrap witnesses", "label": "declared required signer", "path": "[\"intent\",\"signing\",\"required_signers\",\"#0\",\"hash\"]", "value": "8bd03209d227956aaf9670751e0aa2057b51c1537a43f155b24fb1c1" } ], "title": "Declared required signers" }, { "empty": "None missing.", "rows": [ { "copyValue": "8bd03209d227956aaf9670751e0aa2057b51c1537a43f155b24fb1c1", "detail": "declared required signer not present in vkey or bootstrap witnesses", "label": "declared required signer not present in vkey or bootstrap witnesses", "path": "[\"intent\",\"signing\",\"missing_vkey_witnesses\",\"#0\",\"hash\"]", "value": "8bd03209d227956aaf9670751e0aa2057b51c1537a43f155b24fb1c1" } ], "title": "Missing required signers" } ], "signing": { "missing_vkey_witness_count": 2, "missing_vkey_witnesses": [ { "hash": "8bd03209d227956aaf9670751e0aa2057b51c1537a43f155b24fb1c1", "reason": "declared required signer not present in vkey or bootstrap witnesses" } ], "present_bootstrap_witness_count": 0, "present_bootstrap_witnesses": [], "present_vkey_witness_count": 0, "present_vkey_witnesses": [], "required_signer_count": 2, "required_signers": [ { "hash": "8bd03209d227956aaf9670751e0aa2057b51c1537a43f155b24fb1c1", "source": "tx_body.required_signers", "witness_status": "missing" }, { "hash": "f3ab64b0f97dcf0f91232754603283df5d75a1201337432c04d23e2e", "source": "tx_body.required_signers", "witness_status": "missing" } ] }, "subtitle": "1 metadata claim / 2 missing required signers / 2 redeemers", "title": "Signing summary", "tx_id": "0000000000000000000000000000000000000000000000000000000000000000", "value": { "net_spend_known": false, "net_spend_note": "Signer net is unknown until producer transaction CBOR resolves every regular input; output totals are still ledger facts.", "output_buckets": [ { "asset_class_count": 0, "bucket": "script", "label": "Script", "lovelace": "1162532800000", "tx_out_count": 11 } ], "resolved_input_buckets": [], "signer_lovelace": { "basis": "payment key credentials matching declared required signers or present key witnesses", "external_or_script_output_lovelace": "1212430755481", "known": false, "net_lovelace": null, "output_lovelace": "0", "resolved_input_lovelace": "0" } }, "warnings": [ "Metadata describes intent but is self-declared; verify it against the destination addresses and contract policy." ], "withdrawals": [ { "amount_lovelace": "0", "credential": { "hash": "a64d1b9e1aeffe54056034d84977061b45a92691efc282fbee3fc094", "kind": "script" }, "index": 0, "network": "mainnet", "reward_account_hex": "f1a64d1b9e1aeffe54056034d84977061b45a92691efc282fbee3fc094" } ] } } } }, "patch": { "summary": "Target shape for a transforming operation", "value": { "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.patch", "result": { "changes": [], "tx_cbor": "84a4...", "warnings": [] } } }, "validate": { "summary": "Validation response envelope", "value": { "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.validate", "result": { "validation": { "body_hash": "1111111111111111111111111111111111111111111111111111111111111111", "checks": [ { "id": "ledger.apply_tx", "message": "Validation needs explicit context before Conway applyTx can run.", "path": [ "args", "context" ], "required_context": [ "source_output", "protocol_parameters", "slot", "epoch", "network" ], "scope": "ledger", "status": "not_evaluated", "title": "Conway ledger validation" } ], "complete": false, "context": { "decoded_producer_tx_count": 0, "input_count": 1, "input_policy": "preserve", "missing_input_count": 1, "missing_reference_input_count": 0, "producer_tx_count": 0, "reference_input_count": 0, "resolved_input_count": 0, "resolved_reference_input_count": 0, "unspent_status": "not_checked" }, "errors": [], "failures": [ { "index": 0, "kind": "ledger_failure", "message": "Transaction witness or UTxO validation failed: ", "path": [ "body" ], "predicate": "", "rule": "UTXOW" } ], "missing_context": [ { "index": 0, "kind": "source_output", "message": "Supply producer transaction CBOR for the referenced transaction input.", "path": [ "args", "context", "producer_txs" ], "required_for": [ "ledger.apply_tx" ], "tx_id": "0000000000000000000000000000000000000000000000000000000000000000" } ], "resolved_inputs": [], "resolved_reference_inputs": [], "status": "incomplete", "tx_id": "0000000000000000000000000000000000000000000000000000000000000000", "valid_for_supplied_context": null, "warnings": [] } } } }, "witnessAttach": { "summary": "Witness attachment response envelope", "value": { "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.witness.attach", "result": { "tx_cbor": "84a4...", "witness_attachment": { "body_hash": "1111111111111111111111111111111111111111111111111111111111111111", "errors": [], "signed_tx_cbor_hex": "84a4...", "status": "applied", "tx_cbor": "84a4...", "tx_id": "0000000000000000000000000000000000000000000000000000000000000000", "warnings": [], "witness_patch_action": "inserted" } } } }, "witnessAttachRejected": { "summary": "Rejected witness attachment with stable diagnostics", "value": { "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.witness.attach", "result": { "witness_attachment": { "body_hash": "1111111111111111111111111111111111111111111111111111111111111111", "errors": [ { "code": "missing_vkey_witness_cbor_hex", "details": null, "message": "Supply args.vkey_witness_cbor_hex as hex-encoded CBOR for a single vkey witness.", "path": [ "args", "vkey_witness_cbor_hex" ] } ], "status": "rejected", "tx_id": "0000000000000000000000000000000000000000000000000000000000000000", "warnings": [] } } } }, "witnessPlan": { "summary": "Witness plan response envelope", "value": { "ledger_functional_layer": "cardano-ledger-functional/v1", "op": "tx.witness.plan", "result": { "witness_plan": { "context": { "complete": true, "decoded_producer_tx_count": 1, "input_count": 1, "input_policy": "preserve", "missing_input_count": 0, "missing_reference_input_count": 0, "producer_tx_count": 1, "producer_tx_errors": [], "reference_input_count": 0, "resolution": { "errors": [], "missing": [], "provider": "blockfrost", "requested_input_count": 1, "requested_reference_input_count": 0, "requested_tx_count": 1, "resolved_count": 1, "source": "tx-cbor", "unspent_status": "not_checked" }, "resolved_input_count": 1, "resolved_reference_input_count": 0, "supplied": true }, "datums": [], "missing_vkey_witnesses": [], "present_bootstrap_witnesses": [], "present_vkey_witnesses": [ { "hash": "00000000000000000000000000000000000000000000000000000000", "source": "witness_set.vkey" } ], "redeemers": [ { "ex_units": { "memory": 1, "steps": 1 }, "purpose": "ConwayMinting (AsIx {unAsIx = 0})", "redeemer_data_hash": "2222222222222222222222222222222222222222222222222222222222222222" } ], "reference_inputs": [], "required_signers": [], "resolved_inputs": [ { "index": 0, "key": "0000000000000000000000000000000000000000000000000000000000000000#0", "resolved": true, "source": "blockfrost.txs.cbor", "tx_id": "0000000000000000000000000000000000000000000000000000000000000000", "tx_out": { "address_hex": "01...", "assets": {}, "coin_lovelace": "10000000", "datum": { "kind": "no_datum" } } } ], "resolved_reference_inputs": [], "scripts": [], "summary": { "datum_count": 0, "missing_vkey_witness_count": 0, "present_bootstrap_witness_count": 0, "present_vkey_witness_count": 1, "redeemer_count": 1, "reference_input_count": 0, "required_signer_count": 0, "script_count": 0 }, "warnings": [ "Producer transaction CBOR resolved every visible transaction input; live unspent status is not checked by this operation." ] } } } } }, "schema": { "$ref": "ledger-operation-response.schema.json" } } }, "description": "Successful ledger operation response." }, "400": { "content": { "application/json": { "examples": { "unknownOperation": { "summary": "Unknown operation", "value": { "error": { "category": "unknown_ledger_operation", "detail": "tx.unknown" } } } }, "schema": { "$ref": "#/components/schemas/LedgerOperationError" } } }, "description": "Malformed request, malformed transaction bytes, or ledger operation failure." } }, "summary": "Run a ledger functional operation", "tags": [ "Ledger Operations" ] } } }, "servers": [ { "description": "Host adapter root. This repository publishes the contract and WASI artifact, not a public hosted ledger service.", "url": "/" } ], "tags": [ { "description": "Pure ledger-backed operations over explicit transaction CBOR and arguments.", "name": "Ledger Operations" } ] }