Skip to main content

JSON-RPC API

POST 

/ledger

Hyperledger Besu Ethereum Enterprise Client JSON-RPC API.

Read-only methods (eth_getBlock*, eth_getTransaction*, etc.) are forwarded directly to the underlying Besu node and do not require authentication.

A batch request can carry at most 1024 requests, of which at most 100 can be eth_sendRawTransaction transactions (notifications, i.e. requests without an id, are not counted). A batch that exceeds either limit is rejected as a whole, with a single -32005 error object (not an array) and none of its requests are processed.

Write transactions (eth_sendRawTransaction) are validated against the access token scope before being forwarded:

ScopeRegistryAllowed functions
openid did-registry:inviteDID RegistryinsertDidDocument
openid did-registry:writeDID RegistryaddController, addVerificationMethod, addVerificationRelationship, expireVerificationMethod, revokeController, revokeVerificationMethod, rollVerificationMethod, updateBaseDocument
openid issuers-registry:inviteIssuers RegistrysetAttributeData
openid issuers-registry:writeIssuers RegistryaddIssuerProxy, removeIssuerProxy, setAttributeData, setAttributeMetadata, updateIssuerProxy
openid policies-registry:writePolicies RegistryactivatePolicy, deactivatePolicy, deleteUserAttributes, insertPolicy, insertUserAttributes, updatePolicy
openid schemas-registry:writeSchemas RegistryinsertSchema, updateMetadata, updateSchema
openid timestamp:writeTimestampappendRecordVersionHashes, commitTimestampHashes, detachRecordVersionHash, insertHashAlgorithm, insertRecordOwner, insertRecordVersionInfo, revokeRecordOwner, timestampHashes, timestampRecordHashes, timestampRecordVersionHashes, timestampVersionHashes, updateHashAlgorithm
openid track-and-trace:authoriseTrack and TraceauthoriseDid
openid track-and-trace:createTrack and TracecommitCreateDocument, createDocument
openid track-and-trace:writeTrack and TracegrantAccess, removeDocument, revokeAccess, writeEvent
openid ledger:invokeTrusted ContractsAny function on an allowlisted contract

The schema written by insertSchema and updateSchema must be a JSON Schema: a document without a $schema keyword, or with an unsupported $schema value, is rejected with a JsonRpcError. The schema is also rejected when it has more than 5000 nodes, is nested deeper than 32 levels (each object and array counts as a level, properties maps and allOf arrays included), has more than 100 allOf/anyOf/oneOf entries or has more than 25 distinct external $ref targets (each one is a chain read). The same limits apply to the bundled schema, i.e. once the referenced schemas are inlined, and at most 50 referenced schemas are read per bundle.

addVerificationMethod and rollVerificationMethod require vMethodId to be the RFC 7638 SHA-256 thumbprint of publicKey — the same convention insertDidDocument enforces via the token's cnf.jkt (see the access_token_response schema).

Every Timestamp function that timestamps hashes (appendRecordVersionHashes, timestampHashes, timestampRecordHashes, timestampRecordVersionHashes, timestampVersionHashes) is the reveal leg of a commit-reveal flow and takes a trailing salt argument. It must be preceded, at least TIMESTAMP_COMMITMENT_MATURITY blocks earlier (currently 5) and from the same sender address, by a commitTimestampHashes transaction carrying the commitment returned by the contract's computeTimestampCommitment view for those exact arguments. Both legs require the timestamp:write scope, and each is submitted as its own eth_sendRawTransaction. Revealing without a matured commitment reverts (CommitmentUnknown, CommitmentNotMatured), so keep the salt secret until the reveal — that is what stops a third party from front-running the timestamp.

In those functions, hashAlgorithmIds, hashValues and timestampData carry at most 3 entries, like on-chain; a transaction with more is rejected with a JsonRpcError.

createDocument is likewise the reveal leg of a Track and Trace commit-reveal flow and takes a trailing salt argument (both the block-sourced overload and the external-timestamp overload). It must be preceded, at least CREATE_DOCUMENT_COMMITMENT_MATURITY blocks earlier (currently 5) and from the same sender address, by a commitCreateDocument transaction carrying the commitment returned by the contract's computeCreateDocumentCommitment view for those exact arguments. Both legs require the track-and-trace:create scope, and each is submitted as its own eth_sendRawTransaction. Revealing without a matured commitment reverts (CommitmentUnknown, CommitmentNotMatured), so keep the salt secret until the reveal — that is what stops a third party from front-running document creation.

An access token can also combine several of the registry-write scopes above in a single request, e.g. openid did-registry:write issuers-registry:write (see the scope schema for the full list of combinable scopes). When the token combines more than one scope, the transaction is routed to whichever registry its target function belongs to, and that registry's scope must be present in the token — otherwise the request is rejected with a JsonRpcError naming the missing scope.

A JsonRpcError (code -32600) is returned when the payload fails validation, or when the signer cannot be recovered from the signature of the raw transaction (Invalid raw transaction signature).

Two kinds of eth_sendRawTransaction transactions do not need an access token:

  • A basic value transfer, i.e. a transaction without calldata. It targets an externally-owned account rather than a registry contract, so there is no scope or policy to enforce. Its signature must still be recoverable.
  • A transaction sent to the Proxy Factory (Contracts Registry), i.e. a proxy deployment. The sender must hold the ProxyFactory:deployProxy policy in the Policies Registry, otherwise it is rejected with a -32600 JsonRpcError (Address <address&gt; is not allowed to deploy proxies.).

Any other eth_sendRawTransaction requires a Bearer access token (the Bearer scheme is matched case-insensitively), and the contract it targets and the function it calls must be allowed by the token's scope (see the table above). A method that is neither one of the read-only methods forwarded to Besu nor eth_sendRawTransaction is not available and gets a -32601 JsonRpcError (The method <method> does not exist / is not available.).

The HTTP status is 200 for every JSON-RPC response, errors included (see the JsonRpcError codes -32600, -32601, -32005, -32603 and -32000): an internal failure (-32603, Internal error) or an unavailable ledger node or dependency (-32000, Service Unavailable) is also returned with HTTP 200, and never as an HTTP 500 or 503. The only JSON-RPC response with a non-200 status is the -32700 parse error of a body that is not valid JSON when the Content-Type is not a JSON one (HTTP 400, see below).

The request body is limited to 512 KiB by default (HTTP 413 beyond that) and must be sent as application/json (HTTP 415 for a content type the server cannot parse). A body sent as application/json that is not valid JSON is rejected before reaching the JSON-RPC layer, with an HTTP 400 Problem Details response rather than a -32700 JsonRpcError.

Request​

Responses​

JSON-RPC Response. A request with no id is a notification: it is processed, but per JSON-RPC 2.0 receives no response at all — this is HTTP 200 with an empty body. In a batch, notification entries are simply omitted from the response array.