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:
| Scope | Registry | Allowed functions |
|---|---|---|
openid did-registry:invite | DID Registry | insertDidDocument |
openid did-registry:write | DID Registry | addController, addVerificationMethod, addVerificationRelationship, expireVerificationMethod, revokeController, revokeVerificationMethod, rollVerificationMethod, updateBaseDocument |
openid issuers-registry:invite | Issuers Registry | setAttributeData |
openid issuers-registry:write | Issuers Registry | addIssuerProxy, removeIssuerProxy, setAttributeData, setAttributeMetadata, updateIssuerProxy |
openid policies-registry:write | Policies Registry | activatePolicy, deactivatePolicy, deleteUserAttributes, insertPolicy, insertUserAttributes, updatePolicy |
openid schemas-registry:write | Schemas Registry | insertSchema, updateMetadata, updateSchema |
openid timestamp:write | Timestamp | appendRecordVersionHashes, commitTimestampHashes, detachRecordVersionHash, insertHashAlgorithm, insertRecordOwner, insertRecordVersionInfo, revokeRecordOwner, timestampHashes, timestampRecordHashes, timestampRecordVersionHashes, timestampVersionHashes, updateHashAlgorithm |
openid track-and-trace:authorise | Track and Trace | authoriseDid |
openid track-and-trace:create | Track and Trace | commitCreateDocument, createDocument |
openid track-and-trace:write | Track and Trace | grantAccess, removeDocument, revokeAccess, writeEvent |
openid ledger:invoke | Trusted Contracts | Any 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:deployProxypolicy in the Policies Registry, otherwise it is rejected with a-32600JsonRpcError(Address <address> 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
- 200
- 400
- 405
- 406
- 413
- 415
- 500
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.
Bad Request. Either a JSON-RPC -32700 parse error (application/json), for a body
that cannot be parsed as JSON and was not already rejected by the HTTP layer (for
example when the Content-Type is not a JSON one), or a Problem Details response
(application/problem+json) for a body sent as application/json that is not valid
JSON.
Method Not Allowed. Returned for any documented path invoked with an HTTP method it doesn't support.
Response Headers
Comma-separated list of HTTP methods supported by this path.
GET, HEADNot Acceptable. Returned when the request's Accept header matches none of the content
types this operation can produce. The detail lists them: Only '<type>' content type supported when the operation produces a single one, Only '<type>' or '<type>' content types supported when it produces several.
Payload Too Large. The request body exceeds the limit of this endpoint (512 KiB by default). Returned as Problem Details, not as a JSON-RPC error.
Unsupported Media Type. The Content-Type of the request is one the server cannot
parse. Returned as Problem Details, not as a JSON-RPC error.
Internal Server Error