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.
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 | addIssuerProxy, removeIssuerProxy, setAttributeData, setAttributeMetadata, updateIssuerProxy |
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 |
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.
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.
Request
Responses
- 200
- 400
- 405
- 406
- 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.
JSON-RPC Error
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.
Internal Server Error