rpc-0, rpc-1, archive-0, validator-0, and bootnode-0."
}
],
"description":"Submits the request body to the selected Besu JSON-RPC endpoint and returns its status and response body.\nUse this endpoint for any JSON-RPC method, such as `eth_blockNumber` or `eth_getBalance`.\n",
"requestBody":{
"required":true,
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/JsonRpcRequest"
},
"examples":{
"request_eth_block_number":{
"summary":"eth_blockNumber",
"value":{
"jsonrpc":"2.0",
"method":"eth_blockNumber",
"params":[
],
"id":1
}
},
"request_eth_get_balance":{
"summary":"eth_getBalance",
"value":{
"jsonrpc":"2.0",
"method":"eth_getBalance",
"params":[
"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"latest"
],
"id":2
}
}
}
}
}
},
"responses":{
"200":{
"description":"Returns the Besu JSON-RPC response.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/JsonRpcResponse"
},
"examples":{
"response_200_eth_block_number":{
"value":{
"jsonrpc":"2.0",
"id":1,
"result":"0x24a3f"
}
}
}
}
}
},
"4XX":{
"description":"Request error or Besu JSON-RPC error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/JsonRpcErrorResponse"
}
}
}
},
"5XX":{
"description":"Unexpected service error or Besu JSON-RPC error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/JsonRpcErrorResponse"
}
}
}
}
},
"x-internal-id":"v1-besu-proxy-post",
"x-filename-id":"v1-besu-proxy-post"
}
},
"/walletservice/{path}":{
"summary":"Access wallet service wallet and governance APIs. Append the Wallet Service resource path to `/walletservice/`, for example `/walletservice/wallets` or `/walletservice/governance/intents/deploy`. Supports GET, POST, PUT, and DELETE. Responses use the content type returned for the requested resource, including JSON, binary, and multipart content.",
"description":"Accesses Wallet Service Wallet and Governance resources. Append the Wallet Service resource path to\n`/walletservice/`, for example `/walletservice/wallets` or\n`/walletservice/governance/intents/deploy`.\n\nSupports GET, POST, PUT, and DELETE. Responses use the content type returned for the requested resource,\nincluding JSON, binary, and multipart content.\n",
"parameters":[
{
"in":"path",
"name":"path",
"required":true,
"schema":{
"type":"string",
"examples":[
"governance/intents/deploy"
]
},
"description":"Wallet Service resource path, containing one or more slash-separated segments.\n"
},
{
"$ref":"#/components/parameters/RequestId"
},
{
"in":"header",
"name":"Authorization",
"required":false,
"schema":{
"type":"string"
},
"description":"Optional Authorization credentials for the Wallet Service request."
}
],
"get":{
"tags":[
"Wallet Service"
],
"summary":"Get a Wallet Service Resource",
"operationId":"proxyWalletServiceGet",
"description":"Retrieves the requested Wallet Service resource.",
"responses":{
"default":{
"$ref":"#/components/responses/WalletServiceProxyResponse"
}
},
"x-internal-id":"walletservice-{path}-get",
"x-filename-id":"walletservice-path-get"
},
"post":{
"tags":[
"Wallet Service"
],
"summary":"Create or Invoke a Wallet Service Resource",
"operationId":"proxyWalletServicePost",
"description":"Creates or invokes the requested Wallet Service resource.",
"requestBody":{
"$ref":"#/components/requestBodies/WalletServiceProxyBody"
},
"responses":{
"default":{
"$ref":"#/components/responses/WalletServiceProxyResponse"
}
},
"x-internal-id":"walletservice-{path}-post",
"x-filename-id":"walletservice-path-post"
},
"put":{
"tags":[
"Wallet Service"
],
"summary":"Replace a Wallet Service Resource",
"operationId":"proxyWalletServicePut",
"description":"Replaces the requested Wallet Service resource.",
"requestBody":{
"$ref":"#/components/requestBodies/WalletServiceProxyBody"
},
"responses":{
"default":{
"$ref":"#/components/responses/WalletServiceProxyResponse"
}
},
"x-internal-id":"walletservice-{path}-put",
"x-filename-id":"walletservice-path-put"
},
"delete":{
"tags":[
"Wallet Service"
],
"summary":"Delete a Wallet Service Resource",
"operationId":"proxyWalletServiceDelete",
"description":"Deletes the requested Wallet Service resource.",
"responses":{
"default":{
"$ref":"#/components/responses/WalletServiceProxyResponse"
}
},
"x-internal-id":"walletservice-{path}-delete",
"x-filename-id":"walletservice-path-delete"
}
},
"/v1/besu/transaction":{
"post":{
"tags":[
"Transactions"
],
"summary":"Sign and Submit a Transaction",
"operationId":"submitTransaction",
"parameters":[
{
"in":"header",
"name":"X-Request-Id",
"required":false,
"schema":{
"type":"string"
},
"description":"Optional correlation ID. Echoed in the response when provided."
},
{
"in":"header",
"name":"X-Besu-Node",
"required":false,
"schema":{
"type":"string"
},
"description":"Optional operator-defined Besu node identifier. Supported values include rpc-0, rpc-1, archive-0, validator-0, and bootnode-0."
},
{
"in":"header",
"name":"Idempotency-Key",
"required":false,
"schema":{
"type":"string",
"maxLength":255
},
"description":"Optional idempotency key for transaction tracking. Reusing a key with the same request returns the existing operation; reusing it with a different request returns HTTP 409."
}
],
"description":"Signs and submits transactions to the configured Besu network for transfers, contract calls, and contract deployments.\n",
"requestBody":{
"required":true,
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/TransactionSubmitRequest"
},
"examples":{
"request_eip1559_transfer":{
"summary":"EIP-1559 native transfer",
"value":{
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x7d3c9e4f2a1b6c8d9e0f1234567890abcdef1234",
"ethValue":"10000000000000000",
"type":2,
"gasLimit":21000
}
},
"request_legacy_transfer":{
"summary":"Legacy native transfer",
"value":{
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x5e8b2c7d1a9f4063bcde12547890fa3b6c7d8e9f",
"ethValue":"5000000000000000",
"type":0,
"gasPrice":"20000000000",
"gasLimit":21000
}
},
"request_contract_call":{
"summary":"Contract call using explicit function signature",
"value":{
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"type":2,
"functionSignature":"transfer(address,uint256)",
"functionArgs":[
"0x2f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b",
"100"
],
"gasLimit":120000
}
},
"request_contract_call_context":{
"summary":"Contract call with context trailer",
"value":{
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"type":2,
"functionSignature":"purchaseToken(uint256,uint256)",
"functionArgs":[
"3403163951576305573097209448925113882771457",
"300"
],
"gasLimit":2589190,
"contextTrailer":{
"source":"treasury-settlement",
"businessRequestId":"settlement-2026-00842",
"businessOperation":"purchaseToken",
"requestHash":"0x4f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeef",
"target":{
"methodName":"purchaseToken",
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"argsHash":"0x489f15293001da8bfb47d1fb955ebd367e912c8d57fef9a08d8a539a62f580aa"
}
}
}
},
"request_contract_call_abi_inference":{
"summary":"Contract call with ABI-inferred signature",
"value":{
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"type":2,
"functionSignature":"transfer",
"functionArgs":[
"0x2f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b",
"100"
],
"contractAbi":[
{
"name":"transfer",
"type":"function",
"stateMutability":"nonpayable",
"inputs":[
{
"name":"to",
"type":"address"
},
{
"name":"value",
"type":"uint256"
}
],
"outputs":[
{
"name":"",
"type":"bool"
}
]
}
],
"gasLimit":120000
}
},
"request_contract_deployment":{
"summary":"Contract deployment with constructor arguments",
"value":{
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"type":2,
"gasLimit":2500000,
"bytecode":"0x6080604052348015600f57600080fd5b50604051610100380380610100833981016040819052602a6000556100b78061003c6000396000f3fe6080604052600080fdfea2646970667358221220aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa64736f6c63430008140033",
"abi":[
{
"type":"constructor",
"stateMutability":"nonpayable",
"inputs":[
{
"name":"initialValue",
"type":"uint256"
}
]
}
],
"constructorArgs":[
"42"
],
"metadata":{
"smartContractId":"PaymentTokenImplementation",
"version":"1.0.0",
"description":"PaymentToken implementation for settlement issuance",
"author":"Asset Administration",
"tags":{
"businessDomain":"payments",
"application":"payment-token",
"environment":"development"
}
}
}
},
"request_contract_deployment_data":{
"summary":"Contract deployment with pre-encoded data",
"value":{
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"type":2,
"gasLimit":2500000,
"toAddress":null,
"data":"0x6080604052348015600f57600080fd5b50604051610100380380610100833981016040819052602a6000556100b78061003c6000396000f3fe6080604052600080fdfea2646970667358221220aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa64736f6c63430008140033"
}
},
"request_contract_call_decode":{
"summary":"Contract call with input, event, and error decoding",
"value":{
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"type":2,
"functionSignature":"transfer(address,uint256)",
"functionArgs":[
"0x2f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b",
"100"
],
"contractAbi":[
{
"name":"transfer",
"type":"function",
"stateMutability":"nonpayable",
"inputs":[
{
"name":"to",
"type":"address"
},
{
"name":"value",
"type":"uint256"
}
],
"outputs":[
{
"name":"",
"type":"bool"
}
]
},
{
"name":"Transfer",
"type":"event",
"inputs":[
{
"name":"from",
"type":"address",
"indexed":true
},
{
"name":"to",
"type":"address",
"indexed":true
},
{
"name":"value",
"type":"uint256",
"indexed":false
}
]
}
],
"decode":{
"inputs":true,
"events":true,
"errors":true
},
"gasLimit":120000
}
},
"request_tracked_zero_fee":{
"summary":"Tracked transaction with managed nonce allocation",
"value":{
"operation":"NORMAL",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x7d3c9e4f2a1b6c8d9e0f1234567890abcdef1234",
"ethValue":"10000000000000000",
"type":0,
"gasLimit":21000,
"waitForReceipt":false,
"trackLifecycle":true
}
},
"request_tracked_preflight":{
"summary":"Tracked transaction with required preflight simulation",
"value":{
"operation":"NORMAL",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"type":0,
"functionSignature":"transfer(address,uint256)",
"functionArgs":[
"0x2f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b",
"100"
],
"gasLimit":120000,
"waitForReceipt":false,
"trackLifecycle":true,
"preflight":{
"simulate":true,
"estimateGas":true,
"requireSuccess":true,
"blockTag":"pending"
}
}
},
"request_tracked_callback":{
"summary":"Tracked transaction with lifecycle callback",
"value":{
"operation":"NORMAL",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x7d3c9e4f2a1b6c8d9e0f1234567890abcdef1234",
"ethValue":"1",
"type":0,
"gasLimit":21000,
"waitForReceipt":false,
"trackLifecycle":true,
"lifecycleCallback":{
"callbackUrl":"https://payments.example.com/api/v1/callbacks/transactions",
"events":[
"submitted_to_node",
"mined",
"confirmed",
"failed"
],
"maxCallbackRetry":5,
"retryBaseMs":1000,
"retryMaxMs":30000
}
}
},
"request_tracked_receipt":{
"summary":"Tracked transaction with receipt polling",
"value":{
"operation":"NORMAL",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x7d3c9e4f2a1b6c8d9e0f1234567890abcdef1234",
"ethValue":"1",
"type":0,
"gasLimit":21000,
"waitForReceipt":true,
"receiptWaitMs":1000,
"receiptMaxTries":20,
"txByHash":true,
"trackLifecycle":true
}
},
"request_tracked_nonce":{
"summary":"Tracked transaction with caller-provided nonce",
"value":{
"operation":"NORMAL",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x7d3c9e4f2a1b6c8d9e0f1234567890abcdef1234",
"ethValue":"1",
"type":0,
"gasLimit":21000,
"nonce":42,
"waitForReceipt":false,
"trackLifecycle":true
}
},
"request_encode_only":{
"summary":"Encode-only contract call",
"value":{
"operation":"ENCODE_ONLY",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"type":2,
"functionSignature":"transfer(address,uint256)",
"functionArgs":[
"0x2f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b",
"100"
],
"gasLimit":120000
}
},
"request_sign_only":{
"summary":"Sign-only transaction with pre-encoded calldata",
"value":{
"operation":"SIGN_ONLY",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"type":2,
"data":"0xa9059cbb0000000000000000000000002f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b0000000000000000000000000000000000000000000000000000000000000064",
"gasLimit":210000
}
},
"request_sign_and_send":{
"summary":"Sign and submit pre-encoded calldata",
"value":{
"operation":"SIGN_AND_SEND",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"type":2,
"data":"0xa9059cbb0000000000000000000000002f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b0000000000000000000000000000000000000000000000000000000000000064",
"gasLimit":210000
}
},
"request_encode_and_sign":{
"summary":"Encode-and-sign contract call",
"value":{
"operation":"ENCODE_AND_SIGN",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"functionSignature":"transfer(address,uint256)",
"functionArgs":[
"0x2f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b",
"100"
],
"contractAbi":[
{
"name":"transfer",
"type":"function",
"stateMutability":"nonpayable",
"inputs":[
{
"name":"to",
"type":"address"
},
{
"name":"value",
"type":"uint256"
}
],
"outputs":[
{
"name":"",
"type":"bool"
}
]
}
],
"gasLimit":210000
}
}
}
}
}
},
"responses":{
"200":{
"description":"Returns the transaction result.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/TransactionSubmitResponse"
},
"examples":{
"response_submitted":{
"summary":"Submitted transaction",
"value":{
"operation":"NORMAL",
"from":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"txHash":"0x4f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeef",
"rawResult":"0x4f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeef",
"to":"0x7d3c9e4f2a1b6c8d9e0f1234567890abcdef1234",
"data":"0x",
"nonce":"7",
"transactionReceipt":null
}
},
"response_contract_deployment":{
"summary":"Contract deployment with receipt",
"value":{
"operation":"NORMAL",
"txHash":"0x489f15293001da8bfb47d1fb955ebd367e912c8d57fef9a08d8a539a62f580aa",
"rawResult":"0x489f15293001da8bfb47d1fb955ebd367e912c8d57fef9a08d8a539a62f580aa",
"contractAddress":"0x6e5d4c3b2a1908f7e6d5c4b3a291807f6e5d4c3b",
"contractsAddedToRegistry":true,
"registryUpdateStatus":"succeeded",
"transactionReceipt":{
"status":"0x1",
"blockNumber":"0x10",
"transactionHash":"0x489f15293001da8bfb47d1fb955ebd367e912c8d57fef9a08d8a539a62f580aa",
"logs":[
]
}
}
},
"response_decoded_contract_call":{
"summary":"Submitted transaction with decoded input and events",
"value":{
"operation":"NORMAL",
"from":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"txHash":"0x3a32dcf20e9ae0d3a01a5b8f02e0c2f6309349ae2e73f0f0cafd2215c7dbf1f6",
"rawResult":"0x3a32dcf20e9ae0d3a01a5b8f02e0c2f6309349ae2e73f0f0cafd2215c7dbf1f6",
"to":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"data":"0xa9059cbb0000000000000000000000002f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b0000000000000000000000000000000000000000000000000000000000000064",
"nonce":"9",
"decoded":{
"meta":{
"abiSource":"request",
"issues":[
]
},
"function":{
"name":"transfer",
"signature":"transfer(address,uint256)",
"selector":"0xa9059cbb"
},
"events":[
{
"name":"Transfer",
"signature":"Transfer(address,address,uint256)",
"address":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"logIndex":0,
"topics":[
"0xddf252ad00000000000000000000000000000000000000000000000000000000"
],
"data":"0x0000000000000000000000000000000000000000000000000000000000000064",
"args":[
{
"name":"from",
"type":"address",
"indexed":true,
"value":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07"
},
{
"name":"to",
"type":"address",
"indexed":true,
"value":"0x2f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b"
},
{
"name":"value",
"type":"uint256",
"indexed":false,
"value":"100"
}
]
}
]
}
}
},
"response_encode_only":{
"summary":"Encode-only transaction",
"value":{
"operation":"ENCODE_ONLY",
"from":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"to":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"data":"0xa9059cbb0000000000000000000000002f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b0000000000000000000000000000000000000000000000000000000000000064",
"nonce":"10"
}
},
"response_sign_only":{
"summary":"Sign-only transaction",
"value":{
"operation":"SIGN_ONLY",
"from":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"txHash":"0x0208d5002a7a739b27f431d8b79a27a1323c2a8af3a18d6bb39c432369e5ad47",
"rawTransaction":"0x02f86b0180843b9aca00825208948ba1f109551bd432803012645ac136ddd64dba728080c001a04f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeefa0489f15293001da8bfb47d1fb955ebd367e912c8d57fef9a08d8a539a62f580aa",
"to":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"data":"0xa9059cbb0000000000000000000000002f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b0000000000000000000000000000000000000000000000000000000000000064",
"nonce":"11"
}
},
"response_sign_and_send":{
"summary":"Submitted signed transaction",
"value":{
"operation":"SIGN_AND_SEND",
"from":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"txHash":"0x7c3e1a9f6b5d4c2a8091e7f6d5c4b3a291807f6e5d4c3b2a1908f7e6d5c4b3a2",
"rawResult":"0x7c3e1a9f6b5d4c2a8091e7f6d5c4b3a291807f6e5d4c3b2a1908f7e6d5c4b3a2",
"rawTransaction":"0x02f86b0180843b9aca00825208948ba1f109551bd432803012645ac136ddd64dba728080c001a04f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeefa0489f15293001da8bfb47d1fb955ebd367e912c8d57fef9a08d8a539a62f580aa",
"to":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"data":"0xa9059cbb0000000000000000000000002f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b0000000000000000000000000000000000000000000000000000000000000064",
"nonce":"11"
}
},
"response_encode_and_sign":{
"summary":"Encoded and signed transaction",
"value":{
"operation":"ENCODE_AND_SIGN",
"from":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"txHash":"0x59be7d4c2a1f0e9d8c7b6a5948372615f4e3d2c1b0a9988776655443322110fe",
"rawTransaction":"0x02f86b0180843b9aca00825208948ba1f109551bd432803012645ac136ddd64dba728080c001a03a32dcf20e9ae0d3a01a5b8f02e0c2f6309349ae2e73f0f0cafd2215c7dbf1f6a00208d5002a7a739b27f431d8b79a27a1323c2a8af3a18d6bb39c432369e5ad47",
"to":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"data":"0xa9059cbb0000000000000000000000002f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b0000000000000000000000000000000000000000000000000000000000000064",
"nonce":"12"
}
},
"response_tracked":{
"summary":"Tracked transaction with lifecycle links",
"value":{
"operation":"NORMAL",
"txHash":"0x4f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeef",
"rawResult":"0x4f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeef",
"from":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"to":"0x7d3c9e4f2a1b6c8d9e0f1234567890abcdef1234",
"data":"0x",
"nonce":"7",
"operationId":"txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R8",
"status":"submitted",
"feeMode":"zero_fee",
"statusUrl":"/v1/besu/transaction/operations/txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R8",
"diagnosticsUrl":"/v1/besu/transaction/operations/txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R8/diagnostics",
"nonceQueueManaged":true,
"nonceState":"submitted",
"queuePosition":0,
"blockedByNonce":null,
"nextAllocatableNonce":8,
"broadcastStatus":{
"acceptedByProxy":true,
"validated":true,
"signed":true,
"submittedToNode":true,
"acceptedByNode":true,
"observedInTxpool":"unknown",
"mined":false,
"confirmed":false,
"executionStatus":"unknown",
"feeMode":"zero_fee"
}
}
},
"response_tracked_preflight":{
"summary":"Tracked transaction accepted after preflight",
"value":{
"operation":"NORMAL",
"txHash":"0x7c3e1a9f6b5d4c2a8091e7f6d5c4b3a291807f6e5d4c3b2a1908f7e6d5c4b3a2",
"rawResult":"0x7c3e1a9f6b5d4c2a8091e7f6d5c4b3a291807f6e5d4c3b2a1908f7e6d5c4b3a2",
"from":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"to":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"data":"0xa9059cbb0000000000000000000000002f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b0000000000000000000000000000000000000000000000000000000000000064",
"nonce":"8",
"operationId":"txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R9",
"status":"submitted",
"feeMode":"zero_fee",
"statusUrl":"/v1/besu/transaction/operations/txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R9",
"diagnosticsUrl":"/v1/besu/transaction/operations/txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R9/diagnostics",
"nonceQueueManaged":true,
"nonceState":"submitted",
"queuePosition":0,
"blockedByNonce":null,
"nextAllocatableNonce":9,
"preflight":{
"simulationStatus":"would_succeed",
"blockTag":"pending",
"gasEstimate":"52000",
"configuredGasLimit":"120000",
"gated":false,
"errorSummary":null,
"upstreamCode":null,
"decodedError":null
},
"policy":{
"decision":"submit",
"reasonCodes":[
],
"warnings":[
"zero_fee_network_profile"
]
}
}
}
}
}
}
},
"400":{
"description":"Validation failed.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_400_invalid_option_for_operation_decode_non_normal":{
"summary":"Decode options are invalid for non-normal operation modes",
"value":{
"error":"Decode options are not supported for this operation.",
"message":"Decode options are not supported for this operation."
}
},
"response_400_mutually_exclusive_inputs_wallet_id_and_from_address":{
"summary":"Wallet selector inputs are mutually exclusive",
"value":{
"error":"mutually_exclusive_inputs",
"message":"Specify only one of walletId or fromAddress"
}
},
"response_400_missing_wallet_selector":{
"summary":"Wallet-backed signing requires an explicit wallet selector",
"value":{
"error":"invalid_request",
"message":"Exactly one of walletId or fromAddress must be supplied"
}
}
}
}
}
},
"409":{
"description":"Request conflicts with an existing idempotency record or transaction state.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_409_idempotency_conflict":{
"summary":"Idempotency key reused with a different tracked request",
"value":{
"error":"idempotency_conflict",
"message":"Idempotency-Key was already used with a different request"
}
},
"response_409_nonce_queue_paused":{
"summary":"Managed nonce allocation is paused for the sender",
"value":{
"error":"nonce_queue_paused",
"message":"Transaction processing is temporarily paused for this sender."
}
}
}
}
}
},
"422":{
"description":"Transaction submission succeeded and a synchronously observed receipt reports EVM execution reverted. The response body remains a TransactionSubmitResponse, including the transaction hash and receipt.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/TransactionSubmitResponse"
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"502":{
"description":"Communication failure with the Besu node.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"503":{
"description":"Transaction lifecycle service is unavailable for an idempotent tracked submission.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_503_transaction_lifecycle_unavailable":{
"summary":"Lifecycle storage is unavailable for a tracked request",
"value":{
"error":"transaction_lifecycle_unavailable",
"message":"Transaction lifecycle tracking is temporarily unavailable."
}
}
}
}
}
}
},
"x-internal-id":"v1-besu-transaction-post",
"x-filename-id":"v1-besu-transaction-post"
}
},
"/v1/besu/transaction/operations/{operationId}":{
"get":{
"tags":[
"Transactions"
],
"summary":"Get Transaction Status",
"operationId":"getTransactionOperation",
"parameters":[
{
"in":"path",
"name":"operationId",
"required":true,
"schema":{
"type":"string",
"pattern":"^txop_[0-9A-HJKMNP-TV-Z]{26}$"
},
"description":"Unique identifier for the transaction operation."
},
{
"in":"header",
"name":"X-Request-Id",
"required":false,
"schema":{
"type":"string"
},
"description":"Optional correlation ID. Echoed in the response when provided."
}
],
"description":"Returns the current status of a transaction operation created with lifecycle tracking.\nThe operation is available only to the authenticated caller that created it. Requests from other callers return HTTP 404.\n",
"responses":{
"200":{
"description":"Returns the current transaction status.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/TransactionOperationStatusResponse"
},
"examples":{
"response_200_submitted":{
"summary":"Submitted tracked operation before receipt correlation",
"value":{
"operationId":"txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R8",
"status":"submitted",
"feeMode":"zero_fee",
"requestedMode":"NORMAL",
"senderAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"chainId":1337,
"walletId":null,
"diagnosticClassification":null,
"finalOutcome":null,
"createdAt":"2026-05-18T00:00:00Z",
"updatedAt":"2026-05-18T00:00:03Z",
"completedAt":null,
"statusUrl":"/v1/besu/transaction/operations/txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R8",
"diagnosticsUrl":"/v1/besu/transaction/operations/txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R8/diagnostics",
"nonceQueueManaged":true,
"nonceState":"submitted",
"queuePosition":0,
"blockedByNonce":null,
"nextAllocatableNonce":8,
"broadcastStatus":{
"acceptedByProxy":true,
"validated":true,
"signed":true,
"submittedToNode":true,
"acceptedByNode":true,
"observedInTxpool":"unknown",
"mined":false,
"confirmed":false,
"executionStatus":"unknown",
"feeMode":"zero_fee"
},
"latestAttempt":{
"attemptId":"txatt_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R8",
"attemptNumber":1,
"txHash":"0x4f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeef",
"nonce":7,
"sendStatus":"submitted",
"normalizedErrorCode":null,
"createdAt":"2026-05-18T00:00:02Z",
"updatedAt":"2026-05-18T00:00:03Z"
},
"receipt":null,
"receiptDetail":"summary",
"callbacks":[
]
}
},
"response_200_confirmed_with_receipt_and_callback":{
"summary":"Confirmed operation with redacted receipt summary and callback state",
"value":{
"operationId":"txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R9",
"status":"confirmed",
"feeMode":"zero_fee",
"requestedMode":"NORMAL",
"senderAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"chainId":1337,
"walletId":null,
"diagnosticClassification":"receipt_observed",
"finalOutcome":"success",
"createdAt":"2026-05-18T00:00:00Z",
"updatedAt":"2026-05-18T00:01:10Z",
"completedAt":"2026-05-18T00:01:10Z",
"statusUrl":"/v1/besu/transaction/operations/txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R9",
"diagnosticsUrl":"/v1/besu/transaction/operations/txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R9/diagnostics",
"nonceQueueManaged":true,
"nonceState":"completed",
"queuePosition":0,
"blockedByNonce":null,
"nextAllocatableNonce":9,
"broadcastStatus":{
"acceptedByProxy":true,
"validated":true,
"signed":true,
"submittedToNode":true,
"acceptedByNode":true,
"observedInTxpool":"observed",
"mined":true,
"confirmed":true,
"executionStatus":"success",
"feeMode":"zero_fee"
},
"latestAttempt":{
"attemptId":"txatt_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4R9",
"attemptNumber":1,
"txHash":"0x7c3e1a9f6b5d4c2a8091e7f6d5c4b3a291807f6e5d4c3b2a1908f7e6d5c4b3a2",
"nonce":8,
"sendStatus":"accepted_by_node",
"normalizedErrorCode":null,
"createdAt":"2026-05-18T00:00:02Z",
"updatedAt":"2026-05-18T00:00:03Z"
},
"receipt":{
"txHash":"0x7c3e1a9f6b5d4c2a8091e7f6d5c4b3a291807f6e5d4c3b2a1908f7e6d5c4b3a2",
"blockNumber":42,
"blockHash":"0x3a32dcf20e9ae0d3a01a5b8f02e0c2f6309349ae2e73f0f0cafd2215c7dbf1f6",
"transactionIndex":1,
"receiptStatus":"success",
"gasUsed":"21000",
"contractAddress":null,
"logsSummary":{
"logCount":0
},
"blockTimestamp":"2026-05-18T00:01:00Z",
"observedAt":"2026-05-18T00:01:05Z",
"confirmations":12,
"confirmed":true
},
"receiptDetail":"summary",
"callbacks":[
{
"callbackId":101,
"eventType":"confirmed",
"deliveryState":"delivered",
"attemptCount":1,
"nextAttemptAt":null,
"lastAttemptAt":"2026-05-18T00:01:12Z",
"deliveredAt":"2026-05-18T00:01:12Z",
"deadLetteredAt":null,
"lastError":null,
"createdAt":"2026-05-18T00:00:00Z",
"updatedAt":"2026-05-18T00:01:12Z"
}
]
}
},
"response_200_blocked_by_managed_lower_nonce":{
"summary":"Operation blocked by a lower managed sender nonce",
"value":{
"operationId":"txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4S0",
"status":"submitted",
"feeMode":"zero_fee",
"requestedMode":"NORMAL",
"senderAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"chainId":1337,
"walletId":null,
"diagnosticClassification":"blocked_by_lower_nonce",
"finalOutcome":null,
"createdAt":"2026-05-18T00:00:00Z",
"updatedAt":"2026-05-18T00:02:00Z",
"completedAt":null,
"statusUrl":"/v1/besu/transaction/operations/txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4S0",
"diagnosticsUrl":"/v1/besu/transaction/operations/txop_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4S0/diagnostics",
"nonceQueueManaged":true,
"nonceState":"blocked",
"queuePosition":1,
"blockedByNonce":8,
"nextAllocatableNonce":10,
"broadcastStatus":{
"acceptedByProxy":true,
"validated":true,
"signed":true,
"submittedToNode":true,
"acceptedByNode":true,
"observedInTxpool":"not_observed",
"mined":false,
"confirmed":false,
"executionStatus":"unknown",
"feeMode":"zero_fee"
},
"latestAttempt":{
"attemptId":"txatt_01JZ7M9V2Q9ZJ9Z9S0A3Y6T4S0",
"attemptNumber":1,
"txHash":"0x0208d5002a7a739b27f431d8b79a27a1323c2a8af3a18d6bb39c432369e5ad47",
"nonce":9,
"sendStatus":"submitted",
"normalizedErrorCode":null,
"createdAt":"2026-05-18T00:00:02Z",
"updatedAt":"2026-05-18T00:00:03Z"
},
"receipt":null,
"receiptDetail":"summary",
"callbacks":[
]
}
}
}
}
}
},
"400":{
"description":"Validation failed.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"404":{
"description":"Transaction operation not found.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"503":{
"description":"Transaction lifecycle service is unavailable.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-internal-id":"v1-besu-transaction-operations-{operationId}-get",
"x-filename-id":"v1-besu-transaction-operations-operationid-get"
}
},
"/v1/besu/transaction/by-hash/{txHash}":{
"get":{
"tags":[
"Transactions"
],
"summary":"Get Transaction Status by Transaction Hash",
"operationId":"getTransactionByHash",
"parameters":[
{
"in":"path",
"name":"txHash",
"required":true,
"schema":{
"type":"string",
"pattern":"^0x[0-9a-fA-F]{64}$"
},
"description":"Transaction hash associated with a tracked transaction attempt."
},
{
"in":"query",
"name":"receiptDetail",
"required":false,
"schema":{
"type":"string",
"default":"summary",
"enum":[
"summary",
"full"
]
},
"description":"Defaults to summary. Set to full to include the current Besu transaction receipt in rawReceipt.\n"
},
{
"in":"header",
"name":"X-Request-Id",
"required":false,
"schema":{
"type":"string"
},
"description":"Optional correlation ID. Echoed in the response when provided."
},
{
"in":"header",
"name":"X-Besu-Node",
"required":false,
"schema":{
"type":"string"
},
"description":"Optional operator-defined Besu node identifier used only when receiptDetail=full. Supported values include rpc-0, rpc-1, archive-0, validator-0, and bootnode-0."
}
],
"description":"Returns a transaction operation for the specified transaction hash.receipt: null until a receipt is available.receipt contains a redacted receipt summary.receiptDetail=full includes the current Besu receipt in rawReceipt for the same transaction operation.receiptDetail=full, X-Besu-Node selects the Besu node used for the live receipt lookup.rpc-0, rpc-1, archive-0, validator-0, and bootnode-0."
}
],
"description":"Executes a read-only smart contract call using the Ethereum JSON-RPC `eth_call` method. \nSupports encoding requests with `functionSignature` and `functionArgs`. A contract execution revert is a completed query and returns HTTP 200 with `executionStatus: REVERTED`. HTTP error responses are reserved for request validation failures and communication failures with the Besu node.",
"requestBody":{
"required":true,
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/QueryRequest"
},
"examples":{
"request_erc20_balance_of_signature":{
"summary":"ERC20 balanceOf via fully-specified signature",
"value":{
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"functionSignature":"balanceOf(address)",
"functionArgs":[
"0x2f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b"
],
"blockTag":"latest"
}
},
"request_erc20_balance_of_name_only_with_abi":{
"summary":"name-only signature with contractAbi to infer types",
"value":{
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"functionSignature":"balanceOf",
"functionArgs":[
"0x2f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b"
],
"contractAbi":[
{
"name":"balanceOf",
"type":"function",
"stateMutability":"view",
"inputs":[
{
"name":"account",
"type":"address"
}
],
"outputs":[
{
"name":"",
"type":"uint256"
}
]
}
]
}
},
"request_pre_encoded_calldata":{
"summary":"Provide pre-encoded calldata directly",
"value":{
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"data":"0x70a082310000000000000000000000002f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b",
"blockTag":"latest"
}
},
"request_erc20_balance_of_with_output_decode":{
"summary":"Decode outputs for balanceOf",
"value":{
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"functionSignature":"balanceOf(address)",
"functionArgs":[
"0x2f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b"
],
"blockTag":"latest",
"decode":{
"outputs":true,
"errors":true
}
}
},
"request_erc20_balance_of_name_only_without_abi":{
"summary":"Name-only signature without contractAbi",
"value":{
"toAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"fromAddress":"0x4ca7bf4e91d8c3a6f2b057e8d39c4a21b6f85d07",
"functionSignature":"balanceOf",
"functionArgs":[
"0x2f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b"
],
"blockTag":"latest"
}
}
}
}
}
},
"responses":{
"200":{
"description":"Returns the read-only contract query result.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/QueryResponse"
},
"examples":{
"response_200_query_raw_result":{
"value":{
"executionStatus":"SUCCESS",
"to":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"from":"0x0000000000000000000000000000000000000000",
"data":"0x70a082310000000000000000000000002f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b",
"blockTag":"latest",
"rawResult":"0x00000000000000000000000000000000000000000000000000000000000003e8"
}
},
"response_200_query_decoded_result":{
"summary":"Returns decoded output when requested",
"value":{
"executionStatus":"SUCCESS",
"to":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"from":"0x0000000000000000000000000000000000000000",
"data":"0x70a082310000000000000000000000002f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b",
"blockTag":"latest",
"rawResult":"0x00000000000000000000000000000000000000000000000000000000000003e8",
"decoded":{
"meta":{
"abiSource":"request",
"issues":[
]
},
"function":{
"name":"balanceOf",
"signature":"balanceOf(address)",
"selector":"0x70a08231"
},
"output":{
"returns":[
{
"name":"",
"type":"uint256",
"value":"1000"
}
]
}
}
}
},
"response_200_query_reverted":{
"summary":"Completed eth_call whose EVM execution reverted",
"value":{
"executionStatus":"REVERTED",
"to":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"from":"0x0000000000000000000000000000000000000000",
"data":"0x70a082310000000000000000000000002f3a8d7c6b5e4f1920a1b2c3d4e5f60718293a4b",
"blockTag":"latest",
"upstreamCode":-32000,
"upstreamData":"0x08c379a00000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001e496e73756666696369656e7420736574746c656d656e742062616c616e63650000",
"upstreamError":{
"code":-32000,
"message":"execution reverted: Insufficient settlement balance",
"data":"0x08c379a00000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001e496e73756666696369656e7420736574746c656d656e742062616c616e63650000"
},
"decodedError":{
"standardError":{
"selector":"0x08c379a0",
"message":"Insufficient settlement balance"
}
}
}
},
"response_200_query_decoded_uint256_array":{
"summary":"Decoded dynamic uint256[] output",
"value":{
"executionStatus":"SUCCESS",
"to":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"from":"0x0000000000000000000000000000000000000000",
"data":"0x6ff3c4f0",
"blockTag":"latest",
"rawResult":"0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003",
"decoded":{
"meta":{
"abiSource":"request",
"issues":[
]
},
"function":{
"name":"getValues",
"signature":"getValues()",
"selector":"0x6ff3c4f0"
},
"output":{
"returns":[
{
"name":"values",
"type":"uint256[]",
"value":[
"1",
"2",
"3"
]
}
]
}
}
}
},
"response_200_query_decoded_tuple_with_nested_array":{
"summary":"Decoded tuple output containing nested dynamic array",
"value":{
"executionStatus":"SUCCESS",
"to":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"from":"0x0000000000000000000000000000000000000000",
"data":"0x52f1a8f9",
"blockTag":"latest",
"rawResult":"0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000005000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000009000000000000000000000000000000000000000000000000000000000000000b",
"decoded":{
"meta":{
"abiSource":"request",
"issues":[
]
},
"function":{
"name":"getTuple",
"signature":"getTuple()",
"selector":"0x52f1a8f9"
},
"output":{
"returns":[
{
"name":"value",
"type":"(uint256,uint256[])",
"value":{
"a":"5",
"b":[
"9",
"11"
]
}
}
]
}
}
}
},
"response_200_query_partial_decode_with_issues":{
"summary":"Best-effort decode with partial nulls and structured issues",
"value":{
"executionStatus":"SUCCESS",
"to":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"from":"0x0000000000000000000000000000000000000000",
"data":"0x1f3f2f10",
"blockTag":"latest",
"rawResult":"0x000000000000000000000000000000000000000000000000000000000000002a00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000003",
"decoded":{
"meta":{
"abiSource":"request",
"issues":[
{
"code":"ARRAY_LENGTH_LIMIT_EXCEEDED",
"message":"Decoded dynamic array length exceeds configured limit",
"path":"output.returns[1]",
"severity":"error",
"surface":"output"
}
]
},
"function":{
"name":"partial",
"signature":"partial()",
"selector":"0x1f3f2f10"
},
"output":{
"returns":[
{
"name":"head",
"type":"uint256",
"value":"42"
},
{
"name":"tail",
"type":"uint256[]",
"value":null
}
]
}
}
}
}
}
}
}
},
"400":{
"description":"Validation failed.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"502":{
"description":"Communication failure with the Besu node; EVM reverts return HTTP 200.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_502_transport_error":{
"summary":"Upstream transport failure",
"value":{
"error":"Connection refused",
"message":"Connection refused",
"upstreamError":{
"type":"java.net.ConnectException",
"message":"Connection refused"
}
}
}
}
}
}
}
},
"x-internal-id":"v1-besu-query-post",
"x-filename-id":"v1-besu-query-post"
}
},
"/v1/contracts":{
"get":{
"tags":[
"Contracts"
],
"summary":"List Contract Deployments",
"description":"Returns a list of all contract deployments saved in the registry. It doesn't return the associated ABI or bytecode.",
"operationId":"listContracts",
"responses":{
"200":{
"description":"Returns the contract deployments without ABI or bytecode.",
"content":{
"application/json":{
"schema":{
"type":"array",
"items":{
"$ref":"#/components/schemas/ContractSummary"
}
},
"examples":{
"response_200_contract_summary_list":{
"summary":"Two contract summaries",
"value":[
{
"address":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"contractRole":"implementation",
"currentVersion":3,
"implementationAddress":null,
"txHash":"0x4f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeef",
"blockNum":"0x10",
"updatedAt":"2026-05-18T00:00:00Z",
"metadata":{
"smartContractId":"PaymentTokenImplementation",
"version":"1.0.0",
"description":"PaymentToken implementation for settlement issuance",
"author":"Asset Administration",
"tags":{
"businessDomain":"payments",
"application":"payment-token",
"environment":"development"
}
}
},
{
"address":"0x6e5d4c3b2a1908f7e6d5c4b3a291807f6e5d4c3b",
"contractRole":"proxy",
"currentVersion":1,
"implementationAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"txHash":"0x489f15293001da8bfb47d1fb955ebd367e912c8d57fef9a08d8a539a62f580aa",
"blockNum":"0x20",
"updatedAt":"2026-05-18T00:01:00Z"
}
]
}
}
}
}
}
},
"x-internal-id":"v1-contracts-get",
"x-filename-id":"v1-contracts-get"
}
},
"/v1/contracts/{address}":{
"get":{
"tags":[
"Contracts"
],
"summary":"Get Contract Deployment by Address",
"description":"Returns the full metadata for a registered contract at a particular address, if it is available in the contract registry.",
"operationId":"getContractByAddress",
"parameters":[
{
"in":"path",
"name":"address",
"required":true,
"schema":{
"type":"string"
},
"description":"Deployed contract address."
}
],
"responses":{
"200":{
"description":"Returns the requested contract deployment metadata, including ABI and bytecode.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/VersionRecord"
},
"examples":{
"response_200_contract_version_record":{
"value":{
"version":2,
"asOf":{
"txHash":"0x4f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeef",
"blockNum":"0x1a",
"timestamp":"2026-05-18T00:00:00Z"
},
"abi":[
{
"name":"balanceOf",
"type":"function",
"stateMutability":"view",
"inputs":[
{
"name":"account",
"type":"address"
}
],
"outputs":[
{
"name":"",
"type":"uint256"
}
]
}
],
"bytecode":"0x6080604052348015600f57600080fd5b50600080fdfea2646970667358221220c64e7d4a9b8f1e3d5c7a0b2e4f6d8c1a3b5e7f9d0c2a4b6e8f1d3c5a7b9e0f164736f6c63430008140033",
"bytecodeHash":"0x6d8f2b4c1e9a7053c6d8e1f4a7b0c3d6e9f2a5b8c1d4e7f0a3b6c9d2e5f8a1b4",
"storageLayouts":[
{
"type":"solc",
"schemaVersion":"0.8.26",
"capturedAt":"2026-05-18T00:00:00Z",
"sourceKind":"solc",
"content":{
"storage":[
],
"types":{
}
}
}
],
"implementationAddress":null,
"metadata":{
"smartContractId":"PaymentTokenImplementation",
"version":"1.0.0",
"description":"PaymentToken implementation for settlement issuance",
"author":"Asset Administration",
"tags":{
"businessDomain":"payments",
"application":"payment-token",
"environment":"development"
}
}
}
}
}
}
}
},
"404":{
"description":"Contract not found."
}
},
"x-internal-id":"v1-contracts-{address}-get",
"x-filename-id":"v1-contracts-address-get"
}
},
"/v1/contracts/{address}/at/{blockNum}":{
"get":{
"tags":[
"Contracts"
],
"summary":"Get Contract Version at a Specific Block",
"description":"Returns the full metadata for a registered contract at a particular address applicable at the given block number, if it is available in the contract registry.",
"operationId":"getContractVersionAt",
"parameters":[
{
"in":"path",
"name":"address",
"required":true,
"schema":{
"type":"string"
},
"description":"Deployed contract address."
},
{
"in":"path",
"name":"blockNum",
"required":true,
"schema":{
"type":"string"
},
"description":"Block number in 0x-prefixed hexadecimal or decimal format."
}
],
"responses":{
"200":{
"description":"Returns the requested contract version.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/VersionRecord"
},
"examples":{
"response_200_contract_version_at_block":{
"value":{
"version":1,
"asOf":{
"txHash":"0x489f15293001da8bfb47d1fb955ebd367e912c8d57fef9a08d8a539a62f580aa",
"blockNum":"0x20",
"timestamp":"2026-05-18T00:01:00Z"
},
"abi":[
{
"name":"totalSupply",
"type":"function",
"stateMutability":"view",
"inputs":[
],
"outputs":[
{
"name":"",
"type":"uint256"
}
]
}
],
"bytecode":"0x6080604052348015600f57600080fd5b50600080fdfea2646970667358221220c64e7d4a9b8f1e3d5c7a0b2e4f6d8c1a3b5e7f9d0c2a4b6e8f1d3c5a7b9e0f164736f6c63430008140033",
"bytecodeHash":"0x9a7c5e3d1b0f2468ace13579bdf02468ace13579bdf02468ace13579bdf02468",
"storageLayouts":[
{
"type":"solc",
"schemaVersion":"0.8.26",
"content":{
"storage":[
],
"types":{
}
}
}
],
"implementationAddress":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"metadata":{
"smartContractId":"PaymentTokenProxy",
"version":"2.1.0",
"description":"Upgrade proxy for the PaymentToken contract",
"author":"Digital Asset Operations",
"tags":{
"businessDomain":"payments",
"application":"payment-token",
"environment":"production"
}
}
}
}
}
}
}
},
"404":{
"description":"Contract version not found."
}
},
"x-internal-id":"v1-contracts-{address}-at-{blockNum}-get",
"x-filename-id":"v1-contracts-address-blocknum-get"
}
},
"/v1/besu/event-subscriptions":{
"post":{
"tags":[
"Event Subscriptions"
],
"summary":"Create Event Subscription",
"description":"Creates a callback-based subscription for newHeads or filtered logs events, with optional block ranges, retry settings, OAuth, and TLS configuration. It returns the newly created subscription, including its ID and running status.",
"operationId":"createEventSubscription",
"requestBody":{
"required":true,
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/CreateEventSubscriptionRequest"
},
"examples":{
"request_new_heads_minimal":{
"summary":"Minimal newHeads subscription",
"value":{
"type":"newHeads",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/events",
"expiresAt":"2026-06-30T00:00:00Z"
}
},
"request_new_heads_with_expiry_window":{
"summary":"newHeads subscription with finite range and expiry",
"value":{
"type":"newHeads",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/finalized-blocks",
"startBlock":150000,
"endBlock":155000,
"expiresAt":"2026-06-30T00:00:00Z"
}
},
"request_new_heads_non_empty_blocks_only":{
"summary":"newHeads subscription that only emits blocks with transactions",
"value":{
"type":"newHeads",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/non-empty-blocks",
"nonEmptyBlocksOnly":true,
"expiresAt":"2026-06-30T00:00:00Z"
}
},
"request_logs_with_oauth":{
"summary":"Logs subscription with OAuth callback authorization",
"value":{
"type":"logs",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/token-events",
"startBlock":120000,
"expiresAt":"2026-07-15T00:00:00Z",
"maxCallbackRetry":8,
"retryBaseMs":250,
"retryMaxMs":30000,
"oauth":{
"tokenUrl":"https://auth.example.com/oauth2/token",
"clientId":"event-delivery-client",
"clientSecret":"example-client-secret",
"grantType":"client_credentials",
"scopes":"callbacks.write",
"authInHeader":true
},
"logsFilter":{
"address":"0x8ba1f109551bd432803012645ac136ddd64dba72"
}
}
},
"request_logs_with_refresh_token_oauth":{
"summary":"Logs subscription with refresh-token OAuth callback authorization",
"value":{
"type":"logs",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/token-events",
"expiresAt":"2026-07-15T00:00:00Z",
"oauth":{
"grantType":"refresh_token",
"tokenUrl":"https://auth.example.com/oauth2/token",
"clientId":"event-delivery-client",
"clientSecret":"example-client-secret",
"refreshToken":"example-refresh-token",
"scopes":"callbacks.write",
"authInHeader":true
},
"logsFilter":{
"address":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"topics":[
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
null
]
}
}
},
"request_logs_minimal":{
"summary":"Logs subscription with default retry settings and no secrets",
"value":{
"type":"logs",
"callbackUrl":"https://partner.example.com/api/v1/callbacks/token-events",
"expiresAt":"2026-05-15T00:00:00Z",
"logsFilter":{
"topics":[
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
]
}
}
}
}
}
}
},
"responses":{
"201":{
"description":"Returns the created event subscription.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/EventSubscriptionResponse"
},
"examples":{
"response_201_subscription_created":{
"value":{
"subId":"0e9f6e0d-5b2f-4fbe-ae9b-0e5e23801a4d",
"type":"logs",
"status":"running",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/token-events",
"startBlock":120000,
"expiresAt":"2026-07-15T00:00:00Z"
}
},
"response_201_new_heads_subscription_created":{
"summary":"newHeads subscription with end block and expiry",
"value":{
"subId":"47eab3d1-91be-4f3a-8d67-0d5b7cbe2f14",
"type":"newHeads",
"status":"running",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/finalized-blocks",
"nonEmptyBlocksOnly":true,
"startBlock":150000,
"endBlock":155000,
"expiresAt":"2026-06-30T00:00:00Z"
}
}
}
}
}
},
"400":{
"description":"Validation failed.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_400_validation_error":{
"value":{
"error":"invalid_request",
"message":"retryMaxMs must be >= retryBaseMs",
"requestId":"b8f1c3a6-4d72-4e95-8a10-2f6b9c4d7e01"
}
},
"response_400_https_required":{
"summary":"HTTPS enforcement failure",
"value":{
"error":"invalid_request",
"message":"callbackUrl must use https",
"requestId":"a7e2d9c4-6b31-4f85-9c20-1d8a5e7b3f02"
}
}
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_500_internal_error":{
"value":{
"error":"internal_error",
"message":"The service could not complete the request.",
"requestId":"c9a4e1b7-3d68-4f20-8b95-6e2c7a1d4f03"
}
}
}
}
}
},
"503":{
"description":"Event subscriptions are unavailable.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_503_feature_disabled":{
"value":{
"error":"feature_disabled",
"message":"Event subscriptions are not available for this service.",
"requestId":"d1f6b8c3-5a29-4e70-9d14-7c3e8a2b5f04"
}
}
}
}
}
}
},
"x-internal-id":"v1-besu-event-subscriptions-post",
"x-filename-id":"v1-besu-event-subscriptions-post"
},
"get":{
"tags":[
"Event Subscriptions"
],
"summary":"List Event Subscriptions",
"description":"Generates a list of all the events subscribed to by the authenticated caller, with optional event type and lifecycle status filtering.",
"operationId":"listEventSubscriptions",
"parameters":[
{
"in":"query",
"name":"type",
"required":false,
"schema":{
"type":"string",
"enum":[
"newHeads",
"logs"
]
},
"description":"Optional event type filter. Matching is case-insensitive."
},
{
"in":"query",
"name":"status",
"required":false,
"schema":{
"type":"string",
"enum":[
"running",
"stopped",
"deleted",
"completed",
"expired"
]
},
"description":"Optional lifecycle status filter. Matching is case-insensitive."
}
],
"responses":{
"200":{
"description":"Returns the event subscriptions available to the authenticated caller.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ListEventSubscriptionsResponse"
},
"examples":{
"response_200_subscription_list":{
"value":{
"items":[
{
"subId":"47eab3d1-91be-4f3a-8d67-0d5b7cbe2f14",
"type":"newHeads",
"status":"running",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/finalized-blocks",
"nonEmptyBlocksOnly":true,
"endBlock":155000,
"expiresAt":"2026-06-30T00:00:00Z"
},
{
"subId":"a9d67c20-4be3-4f18-9d52-8c7f1e3b6a40",
"type":"logs",
"status":"running",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/token-events",
"startBlock":120000,
"expiresAt":"2026-07-15T00:00:00Z"
},
{
"subId":"f2c9a6d4-0e7b-41f8-9c3d-7b2e5a8f1d60",
"type":"logs",
"status":"stopped",
"callbackUrl":"https://custody.example.com/api/v1/callbacks/archive-events",
"endBlock":200000,
"expiresAt":"2026-05-10T00:00:00Z"
},
{
"subId":"8d5f2a71-3c9e-4b06-a8d1-6e4f0c2b9a35",
"type":"newHeads",
"status":"deleted",
"callbackUrl":"https://partner.example.com/api/v1/callbacks/legacy-events",
"nonEmptyBlocksOnly":false,
"expiresAt":"2026-04-30T00:00:00Z"
},
{
"subId":"c1b8e4d9-6f2a-4c70-9e35-1a7d5b8f2c46",
"type":"logs",
"status":"completed",
"stateReason":"end_block_reached",
"stateChangedAt":"2026-04-21T10:05:00Z",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/final-events",
"cursor":{
"lastLogBlock":220001,
"lastLogBlockHash":"0x8ba1f109551bd432803012645ac136ddd64dba72111111111111111111111111"
}
},
{
"subId":"5a3d9e71-8c2f-4b60-a1d5-7e9f3c6b2a48",
"type":"newHeads",
"status":"expired",
"stateReason":"expires_at_elapsed",
"stateChangedAt":"2026-04-21T10:07:00Z",
"callbackUrl":"https://partner.example.com/api/v1/callbacks/temporary-events"
}
]
}
}
}
}
}
},
"400":{
"description":"Validation failed.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_400_list_filter_validation_error":{
"value":{
"error":"invalid_request",
"message":"query parameter 'status' must be one of: running, stopped, deleted, completed, expired",
"requestId":"e2b7d4a9-6c30-4f81-8e25-9a4d1c7b6f05"
}
}
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_500_internal_error":{
"value":{
"error":"internal_error",
"message":"The service could not complete the request.",
"requestId":"f3c8e5b1-7d42-4a90-9f36-1b5e8c2d7a06"
}
}
}
}
}
},
"503":{
"description":"Event subscriptions are unavailable.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_503_feature_disabled":{
"value":{
"error":"feature_disabled",
"message":"Event subscriptions are not available for this service.",
"requestId":"a4d9f6c2-8e53-4b01-8a47-2c6f9d3e1b07"
}
}
}
}
}
}
},
"x-internal-id":"v1-besu-event-subscriptions-get",
"x-filename-id":"v1-besu-event-subscriptions-get"
}
},
"/v1/besu/event-subscriptions/{subId}":{
"parameters":[
{
"in":"path",
"name":"subId",
"required":true,
"schema":{
"type":"string"
},
"description":"Unique identifier for the event subscription."
}
],
"get":{
"tags":[
"Event Subscriptions"
],
"summary":"Get Event Subscription",
"description":"Retrieves an event subscription record by subscription identifier.",
"operationId":"getEventSubscription",
"responses":{
"200":{
"description":"Returns the requested event subscription.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/EventSubscriptionResponse"
},
"examples":{
"response_200_subscription_record":{
"value":{
"subId":"47eab3d1-91be-4f3a-8d67-0d5b7cbe2f14",
"type":"newHeads",
"status":"running",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/finalized-blocks",
"nonEmptyBlocksOnly":true,
"startBlock":150000,
"endBlock":155000,
"expiresAt":"2026-06-30T00:00:00Z"
}
}
}
}
}
},
"404":{
"description":"Event subscription not found.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_404_subscription_not_found":{
"value":{
"error":"not_found",
"message":"The requested event subscription could not be found.",
"requestId":"b5e1a7d3-9f64-4c12-9b58-3d7a1e4f2c08"
}
}
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_500_internal_error":{
"value":{
"error":"internal_error",
"message":"The service could not complete the request.",
"requestId":"c6f2b8e4-1a75-4d23-8c69-4e8b2f5a3d09"
}
}
}
}
}
},
"503":{
"description":"Event subscriptions are unavailable.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_503_feature_disabled":{
"value":{
"error":"feature_disabled",
"message":"Event subscriptions are not available for this service.",
"requestId":"d7a3c9f5-2b86-4e34-9d70-5f9c3a6b4e10"
}
}
}
}
}
}
},
"x-internal-id":"v1-besu-event-subscriptions-{subId}-get",
"x-filename-id":"v1-besu-event-subscriptions-subid-get"
},
"patch":{
"tags":[
"Event Subscriptions"
],
"summary":"Pause or Resume Event Subscription",
"description":"Pauses or resumes an event subscription by subscription ID.",
"operationId":"patchEventSubscription",
"requestBody":{
"required":true,
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/PatchEventSubscriptionRequest"
},
"examples":{
"request_pause_subscription":{
"summary":"Pause a running subscription",
"value":{
"action":"pause"
}
},
"request_resume_subscription":{
"summary":"Resume a paused subscription",
"value":{
"action":"resume"
}
}
}
}
}
},
"responses":{
"200":{
"description":"Returns the updated event subscription.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/EventSubscriptionResponse"
},
"examples":{
"response_200_subscription_paused":{
"value":{
"subId":"47eab3d1-91be-4f3a-8d67-0d5b7cbe2f14",
"type":"newHeads",
"status":"stopped",
"stateReason":"paused_by_user",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/finalized-blocks"
}
},
"response_200_subscription_resumed":{
"value":{
"subId":"47eab3d1-91be-4f3a-8d67-0d5b7cbe2f14",
"type":"newHeads",
"status":"running",
"stateReason":"resumed_by_user",
"callbackUrl":"https://payments.example.com/api/v1/callbacks/finalized-blocks"
}
}
}
}
}
},
"400":{
"description":"Validation failed.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_400_patch_validation_error":{
"value":{
"error":"invalid_request",
"message":"action must be one of: pause, resume",
"requestId":"e8b4d1a6-3c97-4f45-8e81-6a1d4b7c5f11"
}
},
"response_400_patch_malformed_json":{
"value":{
"error":"invalid_request",
"message":"The request body is not valid JSON.",
"requestId":"f9c5e2b7-4d18-4056-9f92-7b2e5c8d6a12"
}
}
}
}
}
},
"404":{
"description":"Event subscription not found.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_404_subscription_not_found":{
"value":{
"error":"not_found",
"message":"The requested event subscription could not be found.",
"requestId":"a1d6f3c8-5e29-4167-8a03-8c3f6d9e7b13"
}
}
}
}
}
},
"409":{
"description":"Requested lifecycle transition is invalid.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_409_invalid_state_transition":{
"value":{
"error":"invalid_state_transition",
"message":"pause not allowed when status is completed",
"requestId":"b2e7a4d9-6f30-4278-9b14-9d4a7e1f8c14"
}
}
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_500_internal_error":{
"value":{
"error":"internal_error",
"message":"The service could not complete the request.",
"requestId":"c3f8b5e1-7a42-4389-8c25-1e5b8f2a9d15"
}
}
}
}
}
},
"503":{
"description":"Event subscriptions are unavailable.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_503_feature_disabled":{
"value":{
"error":"feature_disabled",
"message":"Event subscriptions are not available for this service.",
"requestId":"d4a9c6f2-8b53-4490-9d36-2f6c9a3b1e16"
}
}
}
}
}
}
},
"x-internal-id":"v1-besu-event-subscriptions-{subId}-patch",
"x-filename-id":"v1-besu-event-subscriptions-subid-patch"
},
"delete":{
"tags":[
"Event Subscriptions"
],
"summary":"Delete Event Subscription",
"description":"Delete an event subscription by subscription ID.",
"operationId":"deleteEventSubscription",
"responses":{
"204":{
"description":"Returns confirmation that the event subscription was deleted."
},
"404":{
"description":"Event subscription not found.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_404_subscription_not_found":{
"value":{
"error":"not_found",
"message":"The requested event subscription could not be found.",
"requestId":"e5b1d7a3-9c64-4a01-8e47-3a7d1b4c2f17"
}
}
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_500_internal_error":{
"value":{
"error":"internal_error",
"message":"The service could not complete the request.",
"requestId":"f6c2e8b4-1d75-4b12-9f58-4b8e2c5d3a18"
}
}
}
}
}
},
"503":{
"description":"Event subscriptions are unavailable.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_503_feature_disabled":{
"value":{
"error":"feature_disabled",
"message":"Event subscriptions are not available for this service.",
"requestId":"a7d3f9c5-2e86-4c23-8a69-5c9f3d6e4b19"
}
}
}
}
}
}
},
"x-internal-id":"v1-besu-event-subscriptions-{subId}-delete",
"x-filename-id":"v1-besu-event-subscriptions-subid-delete"
}
},
"/v1/besu/event-subscriptions/test-callback":{
"post":{
"tags":[
"Event Subscriptions"
],
"summary":"Test Callback Endpoint",
"description":"Use this to verify delivery to an HTTPS callback URL without creating a subscription. It optionally supports OAuth, TLS, and a custom JSON payload.",
"operationId":"testEventSubscriptionCallback",
"requestBody":{
"required":true,
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/EventSubscriptionCallbackTestRequest"
},
"examples":{
"request_callback_connectivity_check":{
"value":{
"callbackUrl":"https://partner.example.com/api/v1/callbacks/connectivity"
}
},
"request_callback_connectivity_check_with_oauth":{
"value":{
"callbackUrl":"https://partner.example.com/api/v1/callbacks/connectivity",
"oauth":{
"tokenUrl":"https://auth.example.com/oauth2/token",
"clientId":"event-delivery-client",
"clientSecret":"example-client-secret",
"grantType":"client_credentials",
"authInHeader":true
},
"payload":{
"eventType":"SUBSCRIPTION_VERIFICATION",
"message":"Callback connectivity verification"
}
}
}
}
}
}
},
"responses":{
"204":{
"description":"Returns confirmation that callback delivery succeeded."
},
"400":{
"description":"Validation failed.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_400_test_callback_validation_error":{
"value":{
"error":"invalid_request",
"message":"A callback URL is required.",
"requestId":"b8e4a1d6-3f97-4d34-9b70-6d1a4e7f5c20"
}
},
"response_400_test_callback_malformed_json":{
"value":{
"error":"invalid_request",
"message":"The request body is not valid JSON.",
"requestId":"c9f5b2e7-4a18-4e45-8c81-7e2b5f8a6d21"
}
}
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_500_internal_error":{
"value":{
"error":"internal_error",
"message":"The service could not complete the request.",
"requestId":"d1a6c3f8-5b29-4f56-9d92-8f3c6a1b7e22"
}
}
}
}
}
},
"503":{
"description":"Event subscriptions are unavailable.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
},
"examples":{
"response_503_feature_disabled":{
"value":{
"error":"feature_disabled",
"message":"Event subscriptions are not available for this service.",
"requestId":"e2b7d4a9-6c30-4067-8e03-9a4d7b2c8f23"
}
}
}
}
}
}
},
"x-internal-id":"v1-besu-event-subscriptions-test-callback-post",
"x-filename-id":"v1-besu-event-subscriptions-test-callback-post"
}
},
"/openapi":{
"get":{
"tags":[
"OpenAPI"
],
"summary":"Get the OpenAPI Document",
"description":"Returns the gateway's current OpenAPI specification.",
"operationId":"getOpenApi",
"responses":{
"200":{
"description":"Returns the current OpenAPI document.",
"content":{
"application/vnd.oai.openapi":{
"schema":{
"type":"string"
}
}
}
},
"304":{
"description":"OpenAPI document has not changed."
}
},
"x-internal-id":"openapi-get",
"x-filename-id":"openapi-get"
}
},
"/v1/configuration/logging":{
"get":{
"tags":[
"Configuration"
],
"summary":"Get Logging Configuration",
"description":"Returns the service's current runtime logging level.",
"operationId":"getRuntimeLoggingConfiguration",
"parameters":[
{
"in":"header",
"name":"X-Request-Id",
"required":false,
"schema":{
"type":"string"
},
"description":"Optional request correlation ID."
}
],
"responses":{
"200":{
"description":"Returns the current logging configuration.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/LoggingConfigurationResponse"
},
"examples":{
"response_current_fine":{
"value":{
"level":"FINE"
}
}
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-internal-id":"v1-configuration-logging-get",
"x-filename-id":"v1-configuration-logging-get"
},
"put":{
"tags":[
"Configuration"
],
"summary":"Update Logging Configuration",
"operationId":"updateRuntimeLoggingConfiguration",
"parameters":[
{
"in":"header",
"name":"X-Request-Id",
"required":false,
"schema":{
"type":"string"
},
"description":"Optional request correlation ID."
}
],
"description":"Updates the logging level.\nAccepted level values are `SEVERE`, `WARNING`, `INFO`, and `FINE`.\n",
"requestBody":{
"required":true,
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/LoggingConfigurationRequest"
},
"examples":{
"request_set_fine":{
"value":{
"level":"FINE"
}
}
}
}
}
},
"responses":{
"200":{
"description":"Returns the updated logging configuration.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/LoggingConfigurationResponse"
},
"examples":{
"response_updated_fine":{
"value":{
"level":"FINE"
}
}
}
}
}
},
"400":{
"description":"Validation failed.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"503":{
"description":"Logging configuration is unavailable.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-internal-id":"v1-configuration-logging-put",
"x-filename-id":"v1-configuration-logging-put"
}
},
"/v1/instance/genesisdata":{
"get":{
"tags":[
"Instance"
],
"summary":"Get Genesis Configuration",
"operationId":"getGenesisData",
"parameters":[
{
"in":"header",
"name":"X-Request-Id",
"required":false,
"schema":{
"type":"string"
},
"description":"Optional request correlation ID."
}
],
"description":"Returns the `genesis.json` content for this blockchain instance. Access requires the founder role.",
"responses":{
"200":{
"description":"Returns the genesis configuration.",
"content":{
"application/json":{
"schema":{
"type":"object",
"additionalProperties":true
},
"examples":{
"response_200_genesis_configuration":{
"value":{
"config":{
"chainId":1337,
"homesteadBlock":0
},
"alloc":{
},
"nonce":"0x0",
"timestamp":"0x0",
"gasLimit":"0x47b760",
"difficulty":"0x1"
}
}
}
}
}
},
"403":{
"description":"Forbidden.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"404":{
"description":"Resource not found.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"502":{
"description":"Communication failure while retrieving the requested configuration.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-internal-id":"v1-instance-genesisdata-get",
"x-filename-id":"v1-instance-genesisdata-get"
}
},
"/v1/instance/genesisdata/zip":{
"get":{
"tags":[
"Instance"
],
"summary":"Download Genesis Bundle",
"operationId":"downloadGenesisBundle",
"parameters":[
{
"in":"header",
"name":"X-Request-Id",
"required":false,
"schema":{
"type":"string"
},
"description":"Optional request correlation ID."
}
],
"description":"Returns a ZIP archive containing `genesis.json` and `static-nodes.json` for creating a participant instance. Access requires the founder role.",
"responses":{
"200":{
"description":"Returns a ZIP archive containing genesis.json and static-nodes.json.",
"content":{
"application/zip":{
"schema":{
"type":"string",
"format":"binary"
}
}
}
},
"403":{
"description":"Forbidden.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"404":{
"description":"Resource not found.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"502":{
"description":"Communication failure while retrieving the requested configuration.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-internal-id":"v1-instance-genesisdata-zip-get",
"x-filename-id":"v1-instance-genesisdata-zip-get"
}
},
"/v1/instance/rhdb":{
"get":{
"tags":[
"Instance"
],
"summary":"Get Rich History Database Metadata",
"operationId":"instanceRhdbInfo",
"description":"Returns Rich History Database (RHDB) metadata for the blockchain instance. Available metadata can vary by instance and may include additional fields.\n",
"responses":{
"200":{
"description":"Returns the Rich History Database metadata.",
"content":{
"application/json":{
"schema":{
"type":"object",
"additionalProperties":true,
"description":"Rich History Database metadata."
}
}
}
},
"4XX":{
"description":"Returns a request error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"5XX":{
"description":"Returns an error while retrieving RHDB metadata.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-internal-id":"v1-instance-rhdb-get",
"x-filename-id":"v1-instance-rhdb-get"
}
},
"/v1/contracts/manifests":{
"get":{
"tags":[
"Contracts"
],
"summary":"List Imported Manifests",
"description":"Lists imported contract manifests available to the authenticated caller. It returns an array of manifest records and supports pagination through optional limit (default 50) and offset (default 0) query parameters.",
"operationId":"listManifestUploads",
"parameters":[
{
"in":"query",
"name":"limit",
"required":false,
"schema":{
"type":"integer",
"default":50
}
},
{
"in":"query",
"name":"offset",
"required":false,
"schema":{
"type":"integer",
"default":0
}
}
],
"responses":{
"200":{
"description":"Returns the imported manifests available to the authenticated caller.",
"content":{
"application/json":{
"schema":{
"type":"array",
"items":{
"$ref":"#/components/schemas/ManifestRecord"
}
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-internal-id":"v1-contracts-manifests-get",
"x-filename-id":"v1-contracts-manifests-get"
}
},
"/v1/contracts/manifests/{manifestLayoutId}":{
"get":{
"tags":[
"Contracts"
],
"summary":"Get Imported Manifest",
"description":"Returns the requested manifest and associated contract versions.",
"operationId":"getManifestUpload",
"parameters":[
{
"in":"path",
"name":"manifestLayoutId",
"required":true,
"schema":{
"type":"integer",
"format":"int64"
},
"description":"Unique identifier for the imported manifest."
}
],
"responses":{
"200":{
"description":"Returns the requested manifest and associated contract versions.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ManifestRecord"
}
}
}
},
"404":{
"description":"Manifest not found."
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-internal-id":"v1-contracts-manifests-{manifestLayoutId}-get",
"x-filename-id":"v1-contracts-manifests-manifestlayoutid-get"
}
},
"/v1/contracts/manifests/import":{
"post":{
"tags":[
"Contracts"
],
"summary":"Import Contract Manifest and Metadata",
"operationId":"importManifest",
"description":"Imports a manifest and contract-version metadata for the addresses in `contracts`.\nTo update an existing manifest, set `update=true` and provide `manifestLayoutId`.\nFor updates, `contracts` entries can include an address and metadata for versions associated with that manifest.\n",
"requestBody":{
"required":true,
"content":{
"application/json":{
"schema":{
"oneOf":[
{
"title":"ManifestAppendImportRequest",
"type":"object",
"required":[
"manifest",
"contracts"
],
"properties":{
"manifest":{
"type":"object",
"description":"OpenZeppelin/Hardhat manifest JSON"
},
"update":{
"type":"boolean",
"const":false,
"default":false,
"description":"Omit or set to `false` to import contract-version metadata."
},
"contracts":{
"type":"array",
"minItems":1,
"description":"Contract addresses with ABI, creation bytecode, and exactly one block reference.",
"items":{
"type":"object",
"required":[
"address",
"abi",
"bytecode"
],
"oneOf":[
{
"required":[
"blockNum"
]
},
{
"required":[
"txHash"
]
}
],
"properties":{
"address":{
"type":"string",
"description":"20-byte address in 0x-prefixed hexadecimal format."
},
"abi":{
"type":"array",
"description":"Standard JSON ABI entries.",
"items":{
"type":"object"
}
},
"bytecode":{
"type":"string",
"description":"Creation bytecode in 0x-prefixed hexadecimal format."
},
"blockNum":{
"type":"string",
"description":"Block number in 0x-prefixed hexadecimal or decimal format."
},
"txHash":{
"type":"string",
"description":"32-byte transaction hash in 0x-prefixed hexadecimal format."
},
"role":{
"type":[
"string",
"null"
],
"description":"Optional contract classification. Supported values are `regular`, `proxy`, `implementation`, and `library`; other values are treated as `regular`."
},
"metadata":{
"anyOf":[
{
"$ref":"#/components/schemas/ContractUserMetadata"
},
{
"type":"null"
}
],
"description":"Optional user-facing metadata stored with this contract version."
}
}
}
}
}
},
{
"title":"ManifestUpdateImportRequest",
"type":"object",
"required":[
"update",
"manifest",
"manifestLayoutId"
],
"properties":{
"update":{
"type":"boolean",
"const":true,
"description":"Set true to update an existing manifest layout."
},
"manifestLayoutId":{
"type":"integer",
"format":"int64",
"description":"Identifier of the existing manifest layout to update."
},
"manifest":{
"type":"object",
"description":"OpenZeppelin/Hardhat manifest JSON"
},
"contracts":{
"type":"array",
"description":"Optional metadata updates for versions associated with `manifestLayoutId`. Omitted metadata leaves existing metadata unchanged, `null` clears it, and an object replaces it.",
"items":{
"type":"object",
"required":[
"address"
],
"properties":{
"address":{
"type":"string",
"description":"20-byte 0x-prefixed address"
},
"role":{
"type":[
"string",
"null"
],
"description":"Optional contract classification update. Supported values are `regular`, `proxy`, `implementation`, and `library`; other values are treated as `regular`."
},
"metadata":{
"anyOf":[
{
"$ref":"#/components/schemas/ContractUserMetadata"
},
{
"type":"null"
}
],
"description":"Optional user-facing metadata patch for this contract version."
}
}
}
}
}
}
]
},
"examples":{
"request_manifest_import_payload":{
"value":{
"manifest":{
"manifestVersion":"3.2",
"proxies":[
],
"impls":{
"123abc":{
"address":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"txHash":"0x4f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeef"
}
}
},
"contracts":[
{
"address":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"abi":[
{
"name":"balanceOf",
"type":"function",
"stateMutability":"view",
"inputs":[
{
"name":"account",
"type":"address"
}
],
"outputs":[
{
"name":"",
"type":"uint256"
}
]
}
],
"bytecode":"0x6080604052348015600f57600080fd5b50600080fdfea2646970667358221220c64e7d4a9b8f1e3d5c7a0b2e4f6d8c1a3b5e7f9d0c2a4b6e8f1d3c5a7b9e0f164736f6c63430008140033",
"txHash":"0x4f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeef",
"role":"implementation",
"metadata":{
"smartContractId":"PaymentTokenImplementation",
"version":"1.0.0",
"description":"PaymentToken implementation for settlement issuance",
"author":"Asset Administration",
"tags":{
"businessDomain":"payments",
"application":"payment-token",
"environment":"development"
}
}
},
{
"address":"0x6e5d4c3b2a1908f7e6d5c4b3a291807f6e5d4c3b",
"abi":[
{
"name":"totalSupply",
"type":"function",
"stateMutability":"view",
"inputs":[
],
"outputs":[
{
"name":"",
"type":"uint256"
}
]
}
],
"bytecode":"0x6080604052348015600f57600080fd5b50600080fdfea2646970667358221220c64e7d4a9b8f1e3d5c7a0b2e4f6d8c1a3b5e7f9d0c2a4b6e8f1d3c5a7b9e0f164736f6c63430008140033",
"blockNum":"0x2a",
"role":"proxy"
}
]
}
},
"request_manifest_update_metadata":{
"value":{
"update":true,
"manifestLayoutId":42,
"manifest":{
"manifestVersion":"3.2",
"proxies":[
],
"impls":{
}
},
"contracts":[
{
"address":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"metadata":{
"smartContractId":"PaymentTokenImplementation",
"version":"1.0.1",
"description":"Updated metadata for the existing manifest-associated version",
"author":"Asset Administration",
"tags":{
"businessDomain":"payments",
"application":"payment-token",
"environment":"staging"
}
}
}
]
}
}
}
}
}
},
"responses":{
"202":{
"description":"Returns the accepted manifest import request.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ManifestImportResult"
}
}
}
},
"400":{
"description":"Validation failed.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-internal-id":"v1-contracts-manifests-import-post",
"x-filename-id":"v1-contracts-manifests-import-post"
}
},
"/v1/contracts/solc/import":{
"post":{
"tags":[
"Contracts"
],
"summary":"Import Contract Storage Layout, ABI, and Bytecode",
"operationId":"ingestSolc",
"description":"By default, imports metadata as a new contract version.\nFor a new version, asOf is required and must include at least one of blockNum or txHash. txHash is provided, the response identifies the corresponding blockNum.blockNum and txHash are provided, both are accepted as provided.update=true to update an existing version identified by exactly one of updateVersion or updateTxHash. The supplied creation bytecode is retained as provided; the response does not include runtime bytecode from the chain.\n",
"requestBody":{
"required":true,
"content":{
"application/json":{
"schema":{
"type":"object",
"required":[
"address",
"layout",
"abi",
"bytecode"
],
"properties":{
"address":{
"type":"string",
"description":"Deployed contract address."
},
"role":{
"type":"string",
"description":"Optional contract classification (regular, proxy, implementation, or library). Defaults to regular."
},
"update":{
"type":"boolean",
"default":false,
"description":"When true, update an existing contract version."
},
"updateVersion":{
"type":[
"integer",
"null"
],
"description":"Existing version number to update. Required when update=true unless updateTxHash is provided."
},
"updateTxHash":{
"type":[
"string",
"null"
],
"description":"Existing transaction hash that identifies the version to update. Required when update=true unless updateVersion is provided."
},
"asOf":{
"type":"object",
"description":"Required when creating a new version. Provide at least one of blockNum or txHash.",
"anyOf":[
{
"required":[
"blockNum"
]
},
{
"required":[
"txHash"
]
}
],
"properties":{
"txHash":{
"type":[
"string",
"null"
],
"description":"81642776211137670000000000000000000000000"
},
"blockNum":{
"type":"string",
"description":"74254541910102660000000000000"
},
"timestamp":{
"type":[
"string",
"null"
]
}
}
},
"layout":{
"type":"object",
"description":"Solidity compiler storage-layout JSON. Must include storage and types."
},
"abi":{
"type":"array",
"items":{
"type":"object"
}
},
"bytecode":{
"type":"string",
"description":"Creation bytecode in 0x-prefixed hexadecimal format."
},
"metadata":{
"anyOf":[
{
"$ref":"#/components/schemas/ContractUserMetadata"
},
{
"type":"null"
}
],
"description":"Optional user-facing metadata stored with this contract version."
}
}
},
"examples":{
"request_solc_import_payload":{
"value":{
"address":"0x8ba1f109551bd432803012645ac136ddd64dba72",
"asOf":{
"txHash":"0x4f6bc1c77fdb3e6c0f0f13d0f5f0c90216589c7b5b0f7fbef9ad1e0c5a0fbeef",
"blockNum":"0x10",
"timestamp":"2026-05-18T00:02:00Z"
},
"layout":{
"storage":[
],
"types":{
}
},
"abi":[
{
"type":"function",
"name":"balanceOf",
"stateMutability":"view",
"inputs":[
{
"name":"account",
"type":"address"
}
],
"outputs":[
{
"name":"",
"type":"uint256"
}
]
}
],
"bytecode":"0x6080604052348015600f57600080fd5b50600080fdfea2646970667358221220c64e7d4a9b8f1e3d5c7a0b2e4f6d8c1a3b5e7f9d0c2a4b6e8f1d3c5a7b9e0f164736f6c63430008140033",
"metadata":{
"smartContractId":"PaymentTokenImplementation",
"version":"1.0.0",
"description":"PaymentToken implementation for settlement issuance",
"author":"Asset Administration",
"tags":{
"businessDomain":"payments",
"application":"payment-token",
"environment":"development"
}
}
}
}
}
}
}
},
"responses":{
"202":{
"description":"Returns the accepted contract metadata import request.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/SolcIngestResult"
}
}
}
},
"400":{
"description":"Validation failed.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
},
"500":{
"description":"Unexpected service error.",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ErrorResponse"
}
}
}
}
},
"x-internal-id":"v1-contracts-solc-import-post",
"x-filename-id":"v1-contracts-solc-import-post"
}
}
},
"components":{
"parameters":{
"RequestId":{
"in":"header",
"name":"X-Request-Id",
"required":false,
"schema":{
"type":"string"
},
"description":"Optional correlation ID. Echoed in the response when provided."
}
},
"requestBodies":{
"WalletServiceProxyBody":{
"required":false,
"description":"Request body for the Wallet Service resource. JSON, binary, and multipart content types are supported.\n",
"content":{
"*/*":{
"schema":{
"type":"string",
"format":"binary"
}
}
}
}
},
"responses":{
"WalletServiceProxyResponse":{
"description":"Response returned by the Wallet Service.",
"content":{
"*/*":{
"schema":{
"type":"string",
"format":"binary"
}
}
}
}
},
"schemas":{
"CreateEventSubscriptionRequest":{
"type":"object",
"description":"Request to create a Besu event subscription. Supports recoverable event types only: `newHeads` and `logs`. `logsFilter` is only valid when `type=logs`.\n`nonEmptyBlocksOnly` is only valid when `type=newHeads`.",
"required":[
"type",
"callbackUrl"
],
"properties":{
"type":{
"type":"string",
"enum":[
"newHeads",
"logs"
],
"description":"Event type to subscribe to; supported values are newHeads and logs."
},
"callbackUrl":{
"type":"string",
"format":"uri",
"description":"HTTPS callback endpoint. HTTP endpoints are rejected by default."
},
"confirmations":{
"type":"integer",
"minimum":0,
"description":"Required block confirmations before callbacks are emitted."
},
"nonEmptyBlocksOnly":{
"type":"boolean",
"description":"When true, newHeads callbacks are emitted only for blocks that contain at least one transaction; empty blocks are not delivered."
},
"startBlock":{
"type":"integer",
"format":"int64",
"minimum":0,
"description":"Earliest block number to begin processing; omit to start from the current chain state."
},
"endBlock":{
"type":"integer",
"format":"int64",
"minimum":0,
"description":"Highest block number to process before the subscription is considered complete."
},
"expiresAt":{
"type":"string",
"format":"date-time",
"description":"Optional RFC 3339 timestamp after which the subscription is automatically expired."
},
"maxCallbackRetry":{
"type":"integer",
"minimum":1,
"description":"Maximum number of delivery attempts before a payload is dead-lettered."
},
"retryBaseMs":{
"type":"integer",
"minimum":1,
"description":"Initial delay in milliseconds used when scheduling callback retries."
},
"retryMaxMs":{
"type":"integer",
"minimum":1,
"description":"Upper bound in milliseconds for retry backoff; must be greater than or equal to retryBaseMs."
},
"oauth":{
"$ref":"#/components/schemas/EventSubscriptionOAuthConfig",
"description":"OAuth callback authentication configuration for token acquisition and credential transport."
},
"tls":{
"$ref":"#/components/schemas/EventSubscriptionTlsConfig",
"description":"TLS or mTLS configuration for callback transport."
},
"logsFilter":{
"$ref":"#/components/schemas/EventSubscriptionLogsFilter",
"description":"Log filter criteria applied when type is logs."
}
}
},
"EventSubscriptionCallbackTestRequest":{
"type":"object",
"description":"Request to test delivery to an event subscription callback endpoint.",
"required":[
"callbackUrl"
],
"properties":{
"callbackUrl":{
"type":"string",
"format":"uri",
"description":"HTTPS callback endpoint to test. HTTP endpoints are rejected by default."
},
"oauth":{
"$ref":"#/components/schemas/EventSubscriptionOAuthConfig",
"description":"Optional OAuth configuration for callback test authorization."
},
"tls":{
"$ref":"#/components/schemas/EventSubscriptionTlsConfig",
"description":"Optional TLS or mTLS configuration for callback test delivery."
},
"payload":{
"description":"Optional callback test payload. Accepts any valid JSON value; when omitted, a default test payload is sent."
}
}
},
"PatchEventSubscriptionRequest":{
"type":"object",
"description":"Lifecycle action for an existing event subscription.",
"required":[
"action"
],
"properties":{
"action":{
"type":"string",
"enum":[
"pause",
"resume"
],
"description":"Lifecycle action to apply. Only lifecycle actions are supported."
}
}
},
"EventSubscriptionOAuthConfig":{
"type":"object",
"description":"OAuth 2.0 configuration for callback authentication.",
"required":[
"tokenUrl",
"clientId",
"clientSecret"
],
"allOf":[
{
"if":{
"required":[
"grantType"
],
"properties":{
"grantType":{
"const":"refresh_token"
}
}
},
"then":{
"required":[
"refreshToken"
]
}
}
],
"properties":{
"tokenUrl":{
"type":"string",
"format":"uri",
"description":"OAuth 2.0 token endpoint used to obtain access tokens for callbacks."
},
"clientId":{
"type":"string",
"description":"OAuth 2.0 client identifier registered for the callback endpoint."
},
"clientSecret":{
"type":"string",
"description":"OAuth 2.0 client secret used for token acquisition."
},
"grantType":{
"type":"string",
"enum":[
"client_credentials",
"refresh_token"
],
"default":"client_credentials",
"description":"OAuth 2.0 token grant used for callback access-token acquisition.\nclient_credentials obtains an access token with the configured client credentials.\nrefresh_token uses the supplied refreshToken and retains any replacement refresh token returned by the identity provider.\n"
},
"refreshToken":{
"type":"string",
"description":"Required when grantType=refresh_token; pre-provisioned OAuth refresh token used to mint callback access tokens."
},
"scopes":{
"type":"string",
"description":"Space-delimited OAuth scopes requested during token exchange."
},
"authInHeader":{
"type":"boolean",
"default":true,
"description":"Controls OAuth token request client-auth placement.\nWhen true, sends `clientId:clientSecret` in an HTTP Basic Authorization header to the token endpoint.\nWhen false, sends client_id and client_secret form fields in the token request body.\n"
},
"tokenTls":{
"$ref":"#/components/schemas/EventSubscriptionTlsConfig",
"description":"Optional TLS or mTLS transport configuration used only for OAuth token-endpoint requests."
},
"tls":{
"$ref":"#/components/schemas/EventSubscriptionTlsConfig",
"description":"OAuth token endpoint TLS configuration. Use tokenTls for new integrations."
}
}
},
"EventSubscriptionTlsConfig":{
"type":"object",
"description":"TLS or mTLS configuration for callback delivery. If mTLS is used, both clientCert and clientKey must be provided together.",
"properties":{
"caCert":{
"type":"string",
"description":"PEM-encoded CA certificate used to verify callback server certificates."
},
"clientCert":{
"type":"string",
"description":"PEM-encoded client certificate for callback mTLS."
},
"clientKey":{
"type":"string",
"description":"PEM-encoded PKCS#8 private key for callback mTLS."
},
"insecureSkipVerify":{
"type":"boolean",
"default":false,
"description":"When true, skips TLS certificate verification. Use only in controlled non-production environments."
}
}
},
"EventSubscriptionLogsFilter":{
"type":"object",
"description":"Log filter criteria for a logs event subscription. Topic positions are ordered. Nested topic arrays (OR topic sets) are not supported.The filter is validated with eth_getLogs when the subscription is created.",
"properties":{
"address":{
"type":"string",
"description":"Contract address whose logs are included.",
"pattern":"^0x[0-9a-fA-F]{40}$",
"minLength":42,
"maxLength":42
},
"topics":{
"type":"array",
"maxItems":4,
"items":{
"type":[
"string",
"null"
],
"pattern":"^0x[0-9a-fA-F]{64}$",
"minLength":66,
"maxLength":66
},
"description":"Ordered topic filters; use null entries as wildcards for positional topics."
}
}
},
"EventSubscriptionResponse":{
"type":"object",
"description":"Event subscription configuration and current lifecycle state.",
"properties":{
"subId":{
"type":"string",
"description":"Unique identifier for the subscription."
},
"type":{
"type":"string",
"description":"Event type for the subscription (newHeads or logs)."
},
"status":{
"type":"string",
"description":"Current lifecycle state of the subscription (running, stopped, deleted, completed, or expired)."
},
"stateReason":{
"type":"string",
"description":"Optional transition reason for terminal state changes."
},
"stateChangedAt":{
"type":"string",
"format":"date-time",
"description":"Timestamp when the lifecycle status was most recently updated."
},
"callbackUrl":{
"type":"string",
"description":"HTTPS endpoint receiving callback deliveries."
},
"confirmations":{
"type":"integer",
"description":"Block confirmation threshold configured for the subscription."
},
"nonEmptyBlocksOnly":{
"type":"boolean",
"description":"Indicates whether empty newHeads blocks are suppressed for this subscription."
},
"startBlock":{
"type":"integer",
"format":"int64",
"description":"First block number considered when replaying events, when provided."
},
"endBlock":{
"type":"integer",
"format":"int64",
"description":"Final block number to process before stopping, when provided."
},
"expiresAt":{
"type":"string",
"format":"date-time",
"description":"Timestamp after which the subscription is automatically considered expired."
},
"cursor":{
"$ref":"#/components/schemas/EventSubscriptionCursor"
}
}
},
"EventSubscriptionCursor":{
"type":"object",
"description":"Event processing position for an event subscription.",
"properties":{
"lastFinalizedBlock":{
"type":"integer",
"format":"int64",
"description":"Most recent finalized block used for head progression."
},
"lastFinalizedBlockHash":{
"type":"string",
"description":"Block hash for lastFinalizedBlock, when known."
},
"lastLogBlock":{
"type":"integer",
"format":"int64",
"description":"Most recent block used for log delivery."
},
"lastLogBlockHash":{
"type":"string",
"description":"Block hash for lastLogBlock, when known."
},
"lastLogTxIndex":{
"type":"integer",
"description":"Last delivered transaction index in lastLogBlock when resuming within-block."
},
"lastLogIndex":{
"type":"integer",
"description":"Last delivered log index in lastLogBlock when resuming within-block."
}
}
},
"ListEventSubscriptionsResponse":{
"type":"object",
"description":"Collection of event subscriptions visible to the authenticated caller.",
"properties":{
"items":{
"type":"array",
"description":"Collection of subscriptions visible to the authenticated caller.",
"items":{
"$ref":"#/components/schemas/EventSubscriptionResponse"
}
}
}
},
"JsonRpcRequest":{
"type":"object",
"description":"JSON-RPC request submitted to a Besu node.",
"additionalProperties":true,
"required":[
"jsonrpc",
"method",
"params",
"id"
],
"properties":{
"jsonrpc":{
"type":"string",
"description":"JSON-RPC protocol version.",
"examples":[
"2.0"
]
},
"method":{
"type":"string",
"description":"JSON-RPC method name.",
"examples":[
"eth_blockNumber"
]
},
"params":{
"type":"array",
"description":"JSON-RPC parameters. The structure depends on the method.",
"items":{
"oneOf":[
{
"type":"object",
"additionalProperties":true
},
{
"type":"array",
"items":{
}
},
{
"type":"string"
},
{
"type":"number"
},
{
"type":"integer"
},
{
"type":"boolean"
},
{
"type":"null"
}
]
}
},
"id":{
"oneOf":[
{
"type":"string"
},
{
"type":"integer"
}
],
"description":"Request identifier echoed in the response.",
"examples":[
1
]
}
}
},
"JsonRpcResponse":{
"type":"object",
"description":"JSON-RPC response returned by a Besu node.",
"additionalProperties":true,
"properties":{
"jsonrpc":{
"type":"string",
"description":"JSON-RPC protocol version.",
"examples":[
"2.0"
]
},
"id":{
"oneOf":[
{
"type":"string"
},
{
"type":"integer"
}
],
"description":"Echoed request identifier.",
"examples":[
1
]
},
"result":{
"description":"JSON-RPC result payload. The structure depends on the method."
}
}
},
"JsonRpcErrorObject":{
"type":"object",
"description":"Error object returned in a JSON-RPC response.",
"properties":{
"code":{
"type":"integer",
"description":"JSON-RPC error code returned by the Besu node.",
"examples":[
-32603
]
},
"message":{
"type":"string",
"description":"JSON-RPC error message returned by the Besu node.",
"examples":[
"Internal error"
]
},
"data":{
"description":"Error data returned by the Besu node. Its structure varies by method."
}
}
},
"JsonRpcErrorResponse":{
"type":"object",
"description":"JSON-RPC error response returned by a Besu node.",
"properties":{
"jsonrpc":{
"type":"string",
"description":"JSON-RPC protocol version.",
"examples":[
"2.0"
]
},
"id":{
"oneOf":[
{
"type":"string"
},
{
"type":"integer"
},
{
"type":"null"
}
],
"description":"Echoed request identifier, when available."
},
"error":{
"$ref":"#/components/schemas/JsonRpcErrorObject",
"description":"JSON-RPC error payload containing code, message, and optional data."
}
}
},
"TransactionSubmitRequest":{
"type":"object",
"description":"Defines a transaction signing and submission request.",
"properties":{
"operation":{
"type":[
"string",
"null"
],
"description":"Operation mode for transaction submission.\nNORMAL signs and submits the transaction.\nENCODE_ONLY returns encoded transaction fields.\nSIGN_ONLY signs pre-encoded request data without function, ABI, or deployment encoding.\nENCODE_AND_SIGN encodes and signs the transaction without submitting it.\nSIGN_AND_SEND signs pre-encoded request data and submits the signed transaction.\nFor modes other than NORMAL, decode.inputs, decode.events, decode.errors, receipt, and txByHash are unavailable.\n",
"enum":[
"NORMAL",
"ENCODE_ONLY",
"SIGN_ONLY",
"ENCODE_AND_SIGN",
"SIGN_AND_SEND"
]
},
"walletId":{
"type":[
"string",
"null"
],
"description":"Wallet identifier for signing. Supply exactly one of walletId or fromAddress for wallet-backed requests."
},
"toAddress":{
"type":[
"string",
"null"
],
"description":"Recipient address. Omit for a contract deployment."
},
"fromAddress":{
"type":"string",
"description":"Sender address for signing. Supply exactly one of walletId or fromAddress for wallet-backed requests. The address must be available to the authenticated caller."
},
"ethValue":{
"type":"string",
"description":"Transfer amount in wei, represented as a decimal string, such as \"10000000000000000\"."
},
"data":{
"type":"string",
"description":"98701215921085330000000000000000000000000000000000000000000000000"
},
"contextTrailer":{
"type":[
"object",
"null"
],
"additionalProperties":true,
"description":"Optional context object appended to contract-call calldata using the version 1 context format.\nIf omitted or null, no context information is included. If provided, the value must be a non-empty JSON object.\n"
},
"functionSignature":{
"type":"string",
"description":"Function selector for ABI encoding when data is absent.\nYou may provide:\n - Fully specified signature, such as \"approve(address,uint256)\", or\n - Function name only, such as \"approve\"; parameter types are inferred from the provided ABI. For overloaded functions, the matching parameter count is used. If contractAbi is not supplied, the ABI associated with `toAddress is used when available.\n"
},
"functionArgs":{
"type":"array",
"items":{
"type":"string"
},
"description":"Function arguments as strings aligned with the parameter order.\nScalars: address, bool, string, int/uint (any width), bytes/bytesN (1..32).\nArrays (1-D) and tuples are supported by passing JSON strings:\n - Dynamic/fixed arrays, such as '[\"0xabc...\", \"0xdef...\"]' or '[\"1\",\"2\",\"3\"]'\n - Tuples and nested tuples, such as '[\"0xabc...\", \"42\"]'\n - Empty tuple-array fields are valid, such as '[..., [], ...]' for tuple params containing '(...)[]'\nFor a function name without types, `contractAbi` is used to infer parameter types. For overloaded functions, the matching parameter count is used.\n"
},
"contractAbi":{
"type":"array",
"description":"Optional ABI used to infer parameter types when `functionSignature` contains only a function name. For overloaded functions, the matching parameter count is used. If omitted, the ABI associated with `toAddress` is used when available.\n",
"items":{
"type":"object"
}
},
"type":{
"type":"integer",
"enum":[
0,
2
],
"default":2,
"description":"Transaction type: `0` for legacy or `2` for EIP-1559."
},
"gasLimit":{
"type":"integer",
"description":"Gas limit. Required for contract deployment and optional otherwise."
},
"gasPrice":{
"type":"string",
"description":"Gas price for legacy transactions. If omitted, the value is obtained through `eth_gasPrice`."
},
"gasTipCap":{
"type":"string",
"description":"EIP-1559 priority fee per gas."
},
"gasFeeCap":{
"type":"string",
"description":"EIP-1559 maximum fee per gas."
},
"nonce":{
"type":"integer",
"description":"Transaction nonce. If omitted, the pending nonce is obtained through `eth_getTransactionCount`."
},
"bytecode":{
"type":"string",
"description":"Contract bytecode in 0x-prefixed hexadecimal format. Required for deployment."
},
"abi":{
"type":"array",
"description":"Contract ABI. Required when `constructorArgs` is provided.",
"items":{
"type":"object"
}
},
"constructorArgs":{
"type":"array",
"items":{
"type":"string"
},
"description":"Optional constructor arguments, represented as strings."
},
"storageLayout":{
"type":"object",
"description":"Optional Solidity compiler storage-layout JSON."
},
"metadata":{
"anyOf":[
{
"$ref":"#/components/schemas/ContractUserMetadata"
},
{
"type":"null"
}
],
"description":"Optional user-facing contract metadata stored when this request deploys a contract. Rejected for non-deployment transactions."
},
"decode":{
"$ref":"#/components/schemas/SignDecodeOptions",
"description":"Decode controls for function inputs, emitted events, and revert error payloads."
},
"waitForReceipt":{
"type":"boolean",
"default":true,
"description":"When `true`, waits for a transaction receipt before responding. Default: `true`."
},
"receiptWaitMs":{
"type":"integer",
"default":1500,
"description":"Interval, in milliseconds, between receipt checks. Default: `1500`."
},
"receiptMaxTries":{
"type":"integer",
"default":60,
"description":"Maximum number of receipt checks. Default: `60`."
},
"txByHash":{
"type":"boolean",
"default":false,
"description":"When `true`, includes the `eth_getTransactionByHash` result in the response."
},
"trackLifecycle":{
"type":"boolean",
"default":false,
"description":"When `true` for `NORMAL` submissions, creates a transaction operation and returns `operationId` and `statusUrl`. Other operation modes reject this option."
},
"preflight":{
"$ref":"#/components/schemas/TransactionPreflightOptions",
"description":"Optional zero-fee preflight controls for `NORMAL` submissions. When `requireSuccess=true`, simulation must succeed before signing and submission."
},
"lifecycleCallback":{
"$ref":"#/components/schemas/TransactionLifecycleCallbackOptions",
"description":"Optional callback configuration for a transaction operation. Accepted only when `trackLifecycle=true` and `operation=NORMAL`."
}
}
},
"TransactionSubmitResponse":{
"type":"object",
"description":"Result of a transaction submission, encoding, or signing request.",
"properties":{
"operation":{
"type":[
"string",
"null"
],
"description":"Operation mode used to produce this response."
},
"txHash":{
"type":"string",
"description":"Hash of the submitted transaction."
},
"rawResult":{
"type":[
"string",
"null"
],
"description":"Result returned by the Ethereum JSON-RPC `eth_sendRawTransaction` method, typically the transaction hash."
},
"rawTransaction":{
"type":[
"string",
"null"
],
"description":"Signed raw transaction in 0x-prefixed hexadecimal format. Present for `SIGN_ONLY`, `ENCODE_AND_SIGN`, and `SIGN_AND_SEND`."
},
"transactionReceipt":{
"type":[
"object",
"null"
],
"description":"Transaction receipt returned when the transaction has been mined."
},
"transactionByHash":{
"type":[
"object",
"null"
],
"description":"Transaction details returned by the Ethereum JSON-RPC `eth_getTransactionByHash` method when requested and available.",
"additionalProperties":true
},
"contractAddress":{
"type":[
"string",
"null"
],
"description":"Deployed contract address, available after a contract deployment is mined."
},
"from":{
"type":[
"string",
"null"
],
"description":"Sender address used for signing and submission."
},
"to":{
"type":"string",
"description":"Target address. Empty for a contract deployment."
},
"data":{
"type":"string",
"description":"Hexadecimal calldata (or \"0x\") for the transaction. When `contextTrailer` is supplied, this is the final calldata after the version 1 context trailer is appended."
},
"nonce":{
"type":"string",
"description":"Nonce used for the transaction."
},
"decoded":{
"anyOf":[
{
"$ref":"#/components/schemas/DecodedResult"
},
{
"type":"null"
}
],
"description":"Decoded transaction data for enabled decode options. Error decoding requires `decode.errors=true` and decodable revert data."
},
"operationId":{
"type":[
"string",
"null"
],
"description":"Unique identifier for the transaction operation. Present only when `trackLifecycle=true` and tracking is available."
},
"status":{
"type":[
"string",
"null"
],
"enum":[
"submitted",
"mined",
null
],
"description":"Current status of the tracked transaction."
},
"feeMode":{
"type":[
"string",
"null"
],
"enum":[
"zero_fee",
null
],
"description":"Network fee profile for the tracked transaction."
},
"statusUrl":{
"type":[
"string",
"null"
],
"description":"URL for retrieving the transaction status."
},
"diagnosticsUrl":{
"type":[
"string",
"null"
],
"description":"Non-public lifecycle metadata URL, when available."
},
"nonceQueueManaged":{
"type":[
"boolean",
"null"
],
"description":"Indicates whether the sender's nonce was allocated through managed nonce allocation."
},
"nonceState":{
"type":[
"string",
"null"
],
"description":"Current managed nonce allocation state for the sender."
},
"queuePosition":{
"type":[
"integer",
"null"
],
"format":"int64",
"description":"Number of active lower nonce allocations for the sender."
},
"blockedByNonce":{
"type":[
"integer",
"null"
],
"format":"int64",
"description":"Lower nonce blocking this operation, when known."
},
"nextAllocatableNonce":{
"type":[
"integer",
"null"
],
"format":"int64",
"description":"Next nonce available through managed allocation for this sender."
},
"broadcastStatus":{
"anyOf":[
{
"$ref":"#/components/schemas/TransactionBroadcastStatus"
},
{
"type":"null"
}
]
},
"preflight":{
"anyOf":[
{
"$ref":"#/components/schemas/TransactionPreflightResult"
},
{
"type":"null"
}
]
},
"policy":{
"anyOf":[
{
"$ref":"#/components/schemas/TransactionPolicyDecision"
},
{
"type":"null"
}
]
},
"contractsAddedToRegistry":{
"type":[
"boolean",
"null"
],
"description":"For contract deployments, indicates whether deployment metadata was added to the contract registry. A value of `false` does not indicate whether the ledger deployment succeeded."
},
"registryUpdateStatus":{
"type":[
"string",
"null"
],
"enum":[
"succeeded",
"failed",
"not_attempted",
null
],
"description":"Status of the deployment metadata update in the contract registry."
},
"registryErrorCode":{
"type":[
"string",
"null"
],
"enum":[
"REGISTRY_API_KEY_EXPIRED",
"REGISTRY_API_KEY_INVALID",
"REGISTRY_API_KEY_MISSING",
"REGISTRY_API_KEY_INSUFFICIENT_SCOPE",
"REGISTRY_UPDATE_FAILED",
null
],
"description":"Machine-readable reason why deployment metadata could not be added to the contract registry."
},
"registryMessage":{
"type":[
"string",
"null"
],
"description":"Human-readable status or failure message for the contract registry update."
},
"registryAction":{
"type":[
"string",
"null"
],
"description":"Suggested next action when contract registry recording did not succeed or was not attempted."
}
}
},
"TransactionPreflightOptions":{
"type":"object",
"description":"Controls for preflight simulation before transaction signing and submission.",
"properties":{
"simulate":{
"type":"boolean",
"default":false,
"description":"Runs `eth_call` before signing and submission. Enabled automatically when `requireSuccess=true`."
},
"estimateGas":{
"type":"boolean",
"default":true,
"description":"Includes the gas estimate or configured gas limit in the preflight result when available."
},
"requireSuccess":{
"type":"boolean",
"default":false,
"description":"Prevents signing and submission if simulation reverts or is unavailable."
},
"blockTag":{
"type":"string",
"default":"pending",
"description":"Block tag used for simulation. Supports `pending`, `latest`, `earliest`, or a block number."
}
}
},
"TransactionLifecycleCallbackOptions":{
"type":"object",
"description":"Callback delivery options for a tracked transaction operation. Defines the callback target for a transaction operation. Callback credentials are never returned in API responses, support views, metrics, audit logs, or delivery records.",
"required":[
"callbackUrl"
],
"properties":{
"callbackUrl":{
"type":"string",
"format":"uri",
"description":"HTTPS callback endpoint. HTTP endpoints are rejected by default."
},
"events":{
"type":"array",
"items":{
"type":"string",
"enum":[
"submitted_to_node",
"accepted_by_node",
"mined",
"confirmed",
"failed",
"receipt_reorged",
"remediation_denied"
]
},
"description":"Optional event allowlist. When omitted or empty, callbacks default to confirmed and failed only."
},
"maxCallbackRetry":{
"type":"integer",
"minimum":1,
"description":"Maximum delivery attempts before dead-lettering."
},
"retryBaseMs":{
"type":"integer",
"minimum":1,
"description":"Initial retry delay in milliseconds."
},
"retryMaxMs":{
"type":"integer",
"minimum":1,
"description":"Maximum retry delay in milliseconds."
},
"oauth":{
"$ref":"#/components/schemas/EventSubscriptionOAuthConfig"
},
"tls":{
"$ref":"#/components/schemas/EventSubscriptionTlsConfig"
}
}
},
"TransactionPreflightResult":{
"type":"object",
"description":"Result of transaction preflight simulation.",
"properties":{
"simulationStatus":{
"type":"string",
"enum":[
"would_succeed",
"would_revert",
"unavailable",
"not_requested"
]
},
"blockTag":{
"type":"string"
},
"gasEstimate":{
"type":[
"string",
"null"
],
"description":"Estimated or prepared gas limit, represented as a decimal string."
},
"configuredGasLimit":{
"type":[
"string",
"null"
],
"description":"Gas limit configured on the prepared transaction."
},
"gated":{
"type":"boolean",
"description":"Indicates whether `requireSuccess=true` prevented submission."
},
"errorSummary":{
"type":[
"string",
"null"
],
"description":"Concise simulation failure summary. The complete Besu response is not returned."
},
"upstreamCode":{
"type":[
"integer",
"null"
],
"description":"Error code returned by the Besu JSON-RPC `eth_call` method, when available."
},
"decodedError":{
"anyOf":[
{
"$ref":"#/components/schemas/DecodedError"
},
{
"type":"null"
}
]
}
}
},
"TransactionPolicyDecision":{
"type":"object",
"description":"Policy decision associated with a transaction submission.",
"properties":{
"decision":{
"type":"string",
"enum":[
"submit",
"warn",
"deny"
]
},
"reasonCodes":{
"type":"array",
"items":{
"type":"string"
},
"description":"Stable reason codes behind warnings or denials."
},
"warnings":{
"type":"array",
"items":{
"type":"string"
},
"description":"Warning reason codes that did not block submission."
}
}
},
"TransactionOperationStatusResponse":{
"type":"object",
"description":"Current status of a tracked transaction operation.",
"properties":{
"operationId":{
"type":"string",
"description":"Unique identifier for the transaction operation."
},
"status":{
"type":"string",
"enum":[
"accepted",
"signing",
"submitted",
"mined",
"confirmed",
"failed"
],
"description":"Current lifecycle status of the transaction operation."
},
"feeMode":{
"type":"string",
"enum":[
"zero_fee"
],
"description":"Fee profile used for the transaction operation."
},
"requestedMode":{
"type":"string",
"enum":[
"NORMAL"
],
"description":"Requested transaction submission mode."
},
"senderAddress":{
"type":"string",
"description":"Sender address for the transaction operation."
},
"chainId":{
"type":"integer",
"format":"int64",
"description":"Ethereum chain identifier for the transaction operation."
},
"walletId":{
"type":[
"string",
"null"
],
"description":"Wallet identifier used for signing, when applicable."
},
"diagnosticClassification":{
"type":[
"string",
"null"
],
"description":"Current diagnostic classification, when available."
},
"finalOutcome":{
"type":[
"string",
"null"
],
"description":"Final transaction outcome, when available."
},
"createdAt":{
"type":"string",
"description":"Timestamp when the transaction operation was created."
},
"updatedAt":{
"type":"string",
"description":"Timestamp when the transaction operation was last updated."
},
"completedAt":{
"type":[
"string",
"null"
],
"description":"Timestamp when the transaction operation completed, when available."
},
"statusUrl":{
"type":"string",
"description":"URL for retrieving the transaction operation status."
},
"diagnosticsUrl":{
"type":"string",
"description":"Non-public lifecycle metadata URL, when available."
},
"nonceQueueManaged":{
"type":"boolean",
"description":"Indicates whether managed nonce allocation is used for the sender."
},
"nonceState":{
"type":[
"string",
"null"
],
"description":"Current managed nonce allocation state, when available."
},
"queuePosition":{
"type":[
"integer",
"null"
],
"format":"int64",
"description":"Number of active lower nonce allocations, when available."
},
"blockedByNonce":{
"type":[
"integer",
"null"
],
"format":"int64",
"description":"Lower nonce preventing progress, when available."
},
"nextAllocatableNonce":{
"type":[
"integer",
"null"
],
"format":"int64",
"description":"Next nonce available for managed allocation, when available."
},
"broadcastStatus":{
"$ref":"#/components/schemas/TransactionBroadcastStatus",
"description":"Current transaction broadcast progress."
},
"latestAttempt":{
"$ref":"#/components/schemas/TransactionAttemptSummary",
"description":"Most recent transaction submission attempt."
},
"receipt":{
"anyOf":[
{
"$ref":"#/components/schemas/TransactionReceiptSummary"
},
{
"type":"null"
}
],
"description":"Receipt summary, when a receipt is available."
},
"receiptDetail":{
"type":"string",
"enum":[
"summary",
"full"
],
"description":"Receipt detail level. Defaults to `summary`; `full` is returned only for by-hash lookups requested with `receiptDetail=full`."
},
"rawReceipt":{
"type":[
"object",
"null"
],
"additionalProperties":true,
"description":"Complete transaction receipt returned by Besu. Available only for by-hash lookups with `receiptDetail=full`; it can include receipt logs and topics."
},
"callbacks":{
"type":"array",
"description":"Redacted callback delivery state for the operation. Callback target URLs, OAuth credentials, TLS private keys, payload bodies, and raw callback errors are excluded.",
"items":{
"$ref":"#/components/schemas/TransactionCallbackDelivery"
}
}
}
},
"TransactionBroadcastStatus":{
"type":"object",
"description":"Summary of transaction broadcast progress.",
"properties":{
"acceptedByProxy":{
"type":"boolean",
"description":"Indicates whether the transaction request was accepted."
},
"validated":{
"type":"boolean",
"description":"Indicates whether the transaction request passed validation."
},
"signed":{
"type":"boolean",
"description":"Indicates whether the transaction was signed."
},
"submittedToNode":{
"type":"boolean",
"description":"Indicates whether the signed transaction was submitted to a Besu node."
},
"acceptedByNode":{
"type":"boolean",
"description":"Indicates whether the Besu node accepted the transaction."
},
"observedInTxpool":{
"type":"string",
"enum":[
"unknown",
"observed",
"not_observed"
],
"description":"Indicates whether the transaction was observed in the transaction pool."
},
"mined":{
"type":"boolean",
"description":"Indicates whether the transaction was included in a block."
},
"confirmed":{
"type":"boolean",
"description":"Indicates whether the transaction reached the required confirmation threshold."
},
"executionStatus":{
"type":"string",
"enum":[
"unknown",
"success",
"reverted"
],
"description":"Execution result for the mined transaction."
},
"feeMode":{
"type":"string",
"enum":[
"zero_fee"
],
"description":"Fee profile used for the transaction."
}
}
},
"TransactionAttemptSummary":{
"type":"object",
"description":"Summary of a transaction submission attempt.",
"properties":{
"attemptId":{
"type":"string",
"description":"Unique identifier for the transaction submission attempt."
},
"attemptNumber":{
"type":"integer",
"description":"Sequential number of the submission attempt."
},
"txHash":{
"type":[
"string",
"null"
],
"description":"Transaction hash for the attempt, when available."
},
"nonce":{
"type":[
"integer",
"null"
],
"format":"int64",
"description":"Nonce used for the attempt, when available."
},
"sendStatus":{
"type":"string",
"description":"Current submission status for the attempt."
},
"normalizedErrorCode":{
"type":[
"string",
"null"
],
"description":"Standardized error code for the submission attempt, when available. Use this value to classify failures programmatically."
},
"createdAt":{
"type":"string",
"description":"Timestamp when the attempt was created."
},
"updatedAt":{
"type":"string",
"description":"Timestamp when the attempt was last updated."
}
}
},
"TransactionReceiptSummary":{
"type":"object",
"description":"Summary of the receipt associated with a tracked transaction.",
"properties":{
"txHash":{
"type":"string",
"description":"Transaction hash associated with the receipt."
},
"blockNumber":{
"type":[
"integer",
"null"
],
"format":"int64",
"description":"Block number containing the transaction, when available."
},
"blockHash":{
"type":[
"string",
"null"
],
"description":"Hash of the block containing the transaction, when available."
},
"transactionIndex":{
"type":[
"integer",
"null"
],
"description":"Zero-based transaction index within the block, when available."
},
"receiptStatus":{
"type":"string",
"enum":[
"success",
"reverted",
"unknown",
"reorged"
],
"description":"Execution status reported in the receipt."
},
"gasUsed":{
"type":[
"string",
"null"
],
"description":"Gas used by the transaction, when available."
},
"contractAddress":{
"type":[
"string",
"null"
],
"description":"Address of the deployed contract, when applicable."
},
"logsSummary":{
"type":[
"object",
"null"
],
"additionalProperties":true,
"description":"Summary of receipt logs. Complete logs, topics, call data, and event payloads are excluded."
},
"blockTimestamp":{
"type":[
"string",
"null"
],
"description":"Timestamp of the block containing the transaction, when available."
},
"observedAt":{
"type":"string",
"description":"Timestamp when the receipt was observed."
},
"confirmations":{
"type":[
"integer",
"null"
],
"format":"int64",
"description":"Number of confirmations observed for the receipt, when available."
},
"confirmed":{
"type":"boolean",
"description":"Indicates whether the receipt reached the required confirmation threshold."
}
}
},
"TransactionCallbackDelivery":{
"type":"object",
"description":"Redacted callback delivery status for a tracked transaction.",
"properties":{
"callbackId":{
"type":"integer",
"format":"int64",
"description":"Unique identifier for the callback delivery."
},
"eventType":{
"type":"string",
"description":"Transaction lifecycle event associated with the callback."
},
"deliveryState":{
"type":"string",
"enum":[
"registered",
"pending",
"claimed",
"delivered",
"dead_letter"
],
"description":"Current delivery state of the callback."
},
"attemptCount":{
"type":"integer",
"description":"Number of delivery attempts performed."
},
"nextAttemptAt":{
"type":[
"string",
"null"
],
"description":"Timestamp of the next scheduled delivery attempt, when available."
},
"lastAttemptAt":{
"type":[
"string",
"null"
],
"description":"Timestamp of the most recent delivery attempt, when available."
},
"deliveredAt":{
"type":[
"string",
"null"
],
"description":"Timestamp when callback delivery succeeded, when available."
},
"deadLetteredAt":{
"type":[
"string",
"null"
],
"description":"Timestamp when delivery entered the dead-letter state, when available."
},
"lastError":{
"type":[
"string",
"null"
],
"description":"Concise, sanitized delivery error classification."
},
"createdAt":{
"type":"string",
"description":"Timestamp when callback delivery was created."
},
"updatedAt":{
"type":"string",
"description":"Timestamp when callback delivery was last updated."
}
}
},
"ContractSummary":{
"type":"object",
"description":"Summary of the latest metadata for a deployed contract.",
"properties":{
"address":{
"type":"string",
"description":"Contract deployment address."
},
"contractRole":{
"type":"string",
"description":"Contract role classification: `regular`, `proxy`, `implementation`, or `library`."
},
"currentVersion":{
"type":"integer",
"description":"Most recent contract version number."
},
"implementationAddress":{
"type":[
"string",
"null"
],
"description":"Implementation contract address for `proxy` deployments, when available."
},
"txHash":{
"type":[
"string",
"null"
],
"description":"Transaction hash associated with the most recent contract version."
},
"blockNum":{
"type":[
"string",
"null"
],
"description":"Block number for the most recent contract version."
},
"updatedAt":{
"type":[
"string",
"null"
],
"description":"Timestamp when the summary was last updated."
},
"metadata":{
"anyOf":[
{
"$ref":"#/components/schemas/ContractUserMetadata"
},
{
"type":"null"
}
],
"description":"User-facing metadata associated with the most recent contract version."
}
}
},
"ContractUserMetadata":{
"type":"object",
"description":"Optional user-facing metadata for a contract version.",
"additionalProperties":false,
"properties":{
"smartContractId":{
"type":[
"string",
"null"
],
"description":"User-facing smart contract identifier."
},
"version":{
"type":[
"string",
"null"
],
"description":"User-facing contract version."
},
"description":{
"type":[
"string",
"null"
],
"description":"Human-readable description of what the contract is about."
},
"author":{
"type":[
"string",
"null"
],
"description":"User-facing contract author."
},
"tags":{
"type":[
"object",
"null"
],
"description":"Arbitrary string key/value tags.",
"additionalProperties":{
"type":"string"
}
}
}
},
"ManifestImportResult":{
"type":"object",
"description":"Result of an asynchronous contract manifest import request.",
"properties":{
"update":{
"type":"boolean",
"description":"Indicates whether the operation updated an existing manifest record."
},
"manifestLayoutId":{
"type":"integer",
"format":"int64",
"description":"Identifier of the manifest layout affected by the import operation."
},
"affectedContractVersions":{
"type":"integer",
"description":"Number of contract versions created or updated by the import."
}
}
},
"SolcIngestResult":{
"type":"object",
"description":"Result of an asynchronous Solidity compiler metadata import request.",
"properties":{
"update":{
"type":"boolean",
"description":"Indicates whether the operation updated an existing contract version record."
},
"address":{
"type":"string",
"description":"Contract address associated with the ingested metadata."
},
"version":{
"type":[
"integer",
"null"
],
"description":"Logical contract version number associated with the ingest result, when available."
},
"versionRowId":{
"anyOf":[
{
"type":"integer",
"format":"int64"
},
{
"type":"null"
}
],
"description":"Identifier of the affected version record, when available."
}
}
},
"ManifestAssociation":{
"type":"object",
"description":"Association between a manifest layout and a contract version.",
"properties":{
"address":{
"type":"string",
"description":"Contract address linked to the manifest layout."
},
"version":{
"type":"integer",
"description":"Contract version number associated with the manifest."
},
"txHash":{
"type":[
"string",
"null"
],
"description":"Deployment transaction hash for the associated version, when available."
},
"blockNum":{
"type":"string",
"description":"Block number linked to the associated contract version."
},
"updatedAt":{
"type":[
"string",
"null"
],
"description":"Timestamp of the latest update for this association record."
},
"implementationAddress":{
"type":[
"string",
"null"
],
"description":"Implementation address for `proxy` associations, when available."
}
}
},
"ManifestRecord":{
"type":"object",
"description":"Imported contract manifest and its associated contract versions.",
"properties":{
"manifestLayoutId":{
"type":"integer",
"format":"int64",
"description":"Unique identifier for the manifest layout."
},
"schemaVersion":{
"type":"string",
"description":"Manifest schema version for this upload."
},
"capturedAt":{
"type":[
"string",
"null"
],
"description":"Capture timestamp reported by the source manifest, when available."
},
"sourceToolchain":{
"type":[
"string",
"null"
],
"description":"Toolchain identifier associated with the manifest source."
},
"associatedContractVersions":{
"type":"integer",
"description":"Count of contract versions linked to this manifest record."
},
"manifest":{
"type":[
"object",
"null"
],
"description":"Manifest content associated with this record."
},
"associatedContracts":{
"type":"array",
"description":"Contracts associated with this manifest layout.",
"items":{
"$ref":"#/components/schemas/ManifestAssociation"
}
}
}
},
"AsOf":{
"type":"object",
"description":"Chain reference that identifies a contract version snapshot.",
"required":[
"blockNum"
],
"properties":{
"txHash":{
"type":[
"string",
"null"
],
"description":"Transaction hash used to identify the version snapshot, when available."
},
"blockNum":{
"type":"string",
"description":"Block number in 0x-prefixed hexadecimal or decimal format."
},
"timestamp":{
"type":[
"string",
"null"
],
"description":"Timestamp associated with the version snapshot, when available."
}
}
},
"StorageLayoutVariantRef":{
"type":"object",
"description":"Storage layout variant associated with a contract version.",
"properties":{
"type":{
"type":"string",
"description":"Storage layout representation type identifier."
},
"schemaVersion":{
"type":"string",
"description":"Schema version for the storage layout representation."
},
"capturedAt":{
"type":[
"string",
"null"
],
"description":"Capture timestamp for this storage layout variant, when available."
},
"sourceKind":{
"type":"string",
"description":"Source category used to obtain the storage layout."
},
"sourceToolchain":{
"type":[
"string",
"null"
],
"description":"Toolchain metadata associated with the storage layout source."
},
"content":{
"type":[
"object",
"null"
],
"description":"Storage layout content."
}
}
},
"VersionRecord":{
"type":"object",
"description":"Metadata for a specific version of a deployed contract.",
"properties":{
"version":{
"type":"integer",
"description":"Contract version number."
},
"asOf":{
"$ref":"#/components/schemas/AsOf",
"description":"Chain reference used to identify the version snapshot."
},
"abi":{
"type":"array",
"description":"Contract ABI entries associated with this version.",
"items":{
"type":"object"
}
},
"bytecode":{
"type":[
"string",
"null"
],
"description":"Creation bytecode associated with this version, when available."
},
"bytecodeHash":{
"type":[
"string",
"null"
],
"description":"Hash of the stored bytecode for integrity verification and lookup."
},
"storageLayouts":{
"type":"array",
"description":"Storage layout variants associated with this version.",
"items":{
"$ref":"#/components/schemas/StorageLayoutVariantRef"
}
},
"implementationAddress":{
"type":[
"string",
"null"
],
"description":"Implementation address for `proxy` deployments, when available."
},
"metadata":{
"anyOf":[
{
"$ref":"#/components/schemas/ContractUserMetadata"
},
{
"type":"null"
}
],
"description":"User-facing metadata associated with this version."
}
}
},
"QueryRequest":{
"type":"object",
"description":"Defines a read-only contract query.",
"properties":{
"toAddress":{
"type":"string",
"description":"Target contract address."
},
"data":{
"type":"string",
"description":"Hexadecimal call data. If omitted and `functionSignature` is provided, call data is encoded automatically."
},
"functionSignature":{
"type":"string",
"description":"Function signature for ABI encoding. Provide a fully specified signature, such as \"balanceOf(address)\", or a function name. For a function name, parameter types are inferred from `contractAbi` when provided or, when available, from the contract address.\n"
},
"functionArgs":{
"type":"array",
"items":{
"type":"string"
},
"description":"Function arguments as strings. Scalars use plain strings; arrays and tuples use JSON strings, such as '[\"1\",\"2\"]'.\n"
},
"contractAbi":{
"type":"array",
"items":{
"type":"object"
},
"description":"Optional ABI used to infer parameter types when `functionSignature` contains only a function name. If omitted, the ABI associated with `toAddress` is used when available.\n"
},
"fromAddress":{
"type":"string",
"description":"Required call sender. Must belong to the authenticated caller."
},
"gasLimit":{
"type":"integer",
"description":"Optional gas limit for `eth_call` execution."
},
"ethValue":{
"type":"string",
"description":"Optional value in wei for `eth_call`."
},
"blockTag":{
"type":"string",
"description":"Block tag: `latest`, `pending`, `earliest`, or a hexadecimal or decimal block number."
},
"decode":{
"$ref":"#/components/schemas/QueryDecodeOptions",
"description":"Decode controls for output data and revert error payloads."
}
},
"required":[
"toAddress",
"fromAddress"
]
},
"QueryResponse":{
"type":"object",
"description":"Result of a read-only contract query.",
"required":[
"executionStatus",
"to",
"from",
"data",
"blockTag"
],
"properties":{
"executionStatus":{
"type":"string",
"enum":[
"SUCCESS",
"REVERTED"
],
"description":"`SUCCESS` when `eth_call` returns normally, or `REVERTED` when Besu completes\n`eth_call` and the EVM reverts. A reverted execution is returned with HTTP 200.\n"
},
"to":{
"type":"string",
"description":"Target contract address for the call."
},
"from":{
"type":"string",
"description":"Sender address used to execute `eth_call`."
},
"data":{
"type":"string",
"description":"Calldata used for the call, in 0x-prefixed hexadecimal format."
},
"blockTag":{
"type":"string",
"description":"Block parameter used for the call: `latest`, `pending`, `earliest`, or a block number."
},
"rawResult":{
"type":"string",
"description":"Return data from a successful `eth_call`, in 0x-prefixed hexadecimal format. Absent when `executionStatus` is `REVERTED`."
},
"decoded":{
"anyOf":[
{
"$ref":"#/components/schemas/DecodedResult"
},
{
"type":"null"
}
],
"description":"Decoded result for enabled decode options.\n`rawResult` contains the complete return value.\nFor successful queries, incomplete or invalid ABI data can return `null` for affected fields and include structured `meta.issues` without failing the request.\nOutput decoding applies to successful queries. Revert decoding is exposed through `decodedError`.\n"
},
"upstreamCode":{
"type":[
"integer",
"null"
],
"description":"Besu JSON-RPC error code when `executionStatus` is `REVERTED`."
},
"upstreamData":{
"type":[
"string",
"null"
],
"description":"Besu revert payload or error data when `executionStatus` is `REVERTED`."
},
"upstreamError":{
"type":[
"object",
"null"
],
"additionalProperties":true,
"description":"Complete Besu error object for a reverted execution, including revert information."
},
"decodedError":{
"anyOf":[
{
"$ref":"#/components/schemas/DecodedError"
},
{
"type":"null"
}
],
"description":"Decoded revert payload when `decode.errors=true` and sufficient information is available. Its absence does not change a reverted query into an HTTP error."
},
"requestId":{
"type":[
"string",
"null"
],
"description":"Client-provided correlation ID echoed for reverted queries."
}
}
},
"LoggingConfigurationRequest":{
"type":"object",
"description":"Request to update the logging configuration.",
"required":[
"level"
],
"properties":{
"level":{
"type":"string",
"enum":[
"SEVERE",
"WARNING",
"INFO",
"FINE"
],
"description":"Logging level to apply."
}
}
},
"LoggingConfigurationResponse":{
"type":"object",
"description":"Current logging configuration.",
"required":[
"level"
],
"properties":{
"level":{
"type":"string",
"enum":[
"SEVERE",
"WARNING",
"INFO",
"FINE"
],
"description":"Configured logging level."
}
}
},
"ErrorResponse":{
"type":"object",
"description":"Error response returned by the service.",
"properties":{
"error":{
"type":"string",
"description":"Short error summary suitable for display."
},
"message":{
"type":[
"string",
"null"
],
"description":"Additional error details, when available."
},
"hint":{
"type":[
"string",
"null"
],
"description":"Optional guidance for resolving the error."
},
"upstreamCode":{
"type":[
"integer",
"null"
],
"description":"Besu node error code, when provided by the RPC endpoint."
},
"upstreamData":{
"type":[
"string",
"null"
],
"description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
},
"upstreamError":{
"type":[
"object",
"null"
],
"additionalProperties":true,
"description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
},
"decodedError":{
"anyOf":[
{
"$ref":"#/components/schemas/DecodedError"
},
{
"type":"null"
}
],
"description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
},
"preflight":{
"anyOf":[
{
"$ref":"#/components/schemas/TransactionPreflightResult"
},
{
"type":"null"
}
],
"description":"Present for preflight-gated transaction submission errors."
},
"policy":{
"anyOf":[
{
"$ref":"#/components/schemas/TransactionPolicyDecision"
},
{
"type":"null"
}
],
"description":"Present for policy warnings or denials such as preflight failure."
},
"requestId":{
"type":[
"string",
"null"
],
"description":"Client-provided correlation ID echoed in the response."
}
}
},
"SignDecodeOptions":{
"type":"object",
"description":"Decode options. Each option defaults to `false` when omitted.",
"properties":{
"inputs":{
"type":"boolean",
"description":"Decodes function inputs for transaction submissions."
},
"events":{
"type":"boolean",
"description":"Decodes event logs for transaction submissions."
},
"errors":{
"type":"boolean",
"description":"Decode revert reasons. Decoding occurs only when true and decodable revert bytes are present."
}
}
},
"QueryDecodeOptions":{
"type":"object",
"description":"Decode options. Each option defaults to `false` when omitted.",
"properties":{
"outputs":{
"type":"boolean",
"description":"Decode `rawResult` into function outputs, including nested tuples and arrays when ABI is available.\nIf some values cannot be decoded, the response includes structured `meta.issues` and `null` for affected fields without failing the request.\n"
},
"errors":{
"type":"boolean",
"description":"Decode revert reasons. Decoding occurs only when true and decodable revert bytes are present."
}
}
},
"DecodedMeta":{
"type":"object",
"description":"Metadata for ABI decoding.",
"properties":{
"abiSource":{
"type":"string",
"description":"Source of the ABI used for decoding.",
"enum":[
"request",
"registry",
"none"
]
},
"issues":{
"type":"array",
"description":"Structured decode issues encountered while attempting to decode.",
"items":{
"$ref":"#/components/schemas/DecodedIssue"
}
}
}
},
"DecodedIssue":{
"type":"object",
"description":"Structured issue encountered during ABI decoding.",
"properties":{
"code":{
"type":[
"string",
"null"
],
"description":"Stable machine-readable issue code."
},
"message":{
"type":[
"string",
"null"
],
"description":"Human-readable issue detail."
},
"path":{
"type":[
"string",
"null"
],
"description":"JSON-path-like location associated with the issue."
},
"severity":{
"type":[
"string",
"null"
],
"description":"Issue severity level.",
"enum":[
"error",
"warning",
null
]
},
"surface":{
"type":[
"string",
"null"
],
"description":"Decode surface where the issue was emitted (input, output, error, event, or meta).",
"enum":[
"input",
"output",
"error",
"event",
"meta",
null
]
}
}
},
"DecodedFunctionInfo":{
"type":"object",
"description":"Decoded function identifier.",
"properties":{
"name":{
"type":"string",
"description":"Function name without parameter types."
},
"signature":{
"type":"string",
"description":"Fully specified function signature, including parameter types, such as \"approve(address,uint256)\"."
},
"selector":{
"type":"string",
"description":"Four-byte function selector in 0x-prefixed hexadecimal format."
}
}
},
"DecodedArgument":{
"type":"object",
"description":"Decoded ABI argument.",
"properties":{
"name":{
"type":"string",
"description":"Argument name. May be empty when unknown."
},
"type":{
"type":"string",
"description":"ABI type, such as `uint256`, `address`, `(uint256,address)`, or `uint256[]`"
},
"value":{
"type":[
"object",
"array",
"string",
"number",
"integer",
"boolean",
"null"
],
"description":"Decoded JSON value.\nScalars: addresses as lowercase 0x-hex, big integers as decimal strings, bytes as 0x-hex, booleans as JSON booleans.\nArrays decode to JSON arrays; tuples decode to JSON objects; nested tuple/array values are represented recursively.\nFor indexed dynamic event arguments, value may be the topic hash rather than a reconstructed preimage.\n"
},
"indexed":{
"type":[
"boolean",
"null"
],
"description":"Indicates whether the event parameter is indexed."
}
}
},
"DecodedInput":{
"type":"object",
"description":"Contains decoded function input arguments.",
"properties":{
"args":{
"type":"array",
"description":"Ordered list of decoded input arguments.",
"items":{
"$ref":"#/components/schemas/DecodedArgument"
}
}
}
},
"DecodedOutput":{
"type":"object",
"description":"Contains decoded function return values.",
"properties":{
"returns":{
"type":"array",
"description":"Ordered list of decoded return values.",
"items":{
"$ref":"#/components/schemas/DecodedArgument"
}
}
}
},
"DecodedEvent":{
"type":"object",
"description":"Decoded event log.",
"properties":{
"name":{
"type":"string",
"description":"Event name without parameter types."
},
"signature":{
"type":"string",
"description":"Fully specified event signature, including parameter types."
},
"address":{
"type":"string",
"description":"Contract address that emitted the log."
},
"logIndex":{
"type":[
"integer",
"null"
],
"description":"Zero-based index of the log within the block."
},
"topics":{
"type":"array",
"description":"Log topics in 0x-prefixed hexadecimal format.",
"items":{
"type":"string"
}
},
"data":{
"type":"string",
"description":"Event data payload in 0x-prefixed hexadecimal format."
},
"args":{
"type":"array",
"description":"Decoded event arguments. `indexed` indicates a topic-encoded parameter.",
"items":{
"$ref":"#/components/schemas/DecodedArgument"
}
}
}
},
"DecodedError":{
"type":"object",
"description":"Decoded EVM revert error.",
"properties":{
"standardError":{
"type":[
"object",
"null"
],
"description":"Decoded standard `Error(string)` revert.",
"properties":{
"selector":{
"type":"string",
"description":"4-byte selector for the standard `Error(string)` revert payload.",
"examples":[
"0x08c379a0"
]
},
"message":{
"type":[
"string",
"null"
],
"description":"Revert message."
}
}
},
"standardPanic":{
"type":[
"object",
"null"
],
"description":"Decoded `Panic(uint256)` revert.",
"properties":{
"selector":{
"type":"string",
"description":"4-byte selector for the standard `Panic(uint256)` revert payload.",
"examples":[
"0x4e487b71"
]
},
"code":{
"type":[
"string",
"null"
],
"description":"Panic code value, represented as a hexadecimal or decimal string."
},
"meaning":{
"type":[
"string",
"null"
],
"description":"Human-readable interpretation of the panic code, when known."
}
}
},
"customError":{
"type":[
"object",
"null"
],
"description":"Decoded custom error defined in the contract ABI.",
"properties":{
"name":{
"type":"string",
"description":"Custom error name."
},
"signature":{
"type":"string",
"description":"Fully specified custom error signature, including parameter types."
},
"selector":{
"type":"string",
"description":"4-byte selector for the custom error payload."
},
"args":{
"type":"array",
"description":"Decoded custom error arguments in declaration order.",
"items":{
"$ref":"#/components/schemas/DecodedArgument"
}
}
}
}
}
},
"DecodedResult":{
"type":"object",
"description":"Contains decoded information for the transaction or call.",
"properties":{
"meta":{
"$ref":"#/components/schemas/DecodedMeta",
"description":"Decoding metadata, including the ABI source and any issues."
},
"function":{
"$ref":"#/components/schemas/DecodedFunctionInfo",
"description":"Decoded function identifier information."
},
"input":{
"$ref":"#/components/schemas/DecodedInput",
"description":"Decoded function input arguments."
},
"output":{
"$ref":"#/components/schemas/DecodedOutput",
"description":"Decoded function output values."
},
"events":{
"type":"array",
"description":"Decoded event logs extracted from the transaction receipt.",
"items":{
"$ref":"#/components/schemas/DecodedEvent"
}
},
"error":{
"$ref":"#/components/schemas/DecodedError",
"description":"Decoded revert error details when available."
}
}
}
}
}
}