Skip to main content
European CommissionEBSI European Blockchain
Get Help
Select the Environment you want to work withEnvironment:
warning icon

A new version of this API is now available.

EBSI will stop supporting this maintenance version in the upcoming months. You can find the details of the upcoming release and affected endpoints in the change log. Please contact eu-ebsi@ec.europa.eu if this upcoming release might cause a high impact on either an ongoing development or a piloting demonstration.

JSON-RPC API

Last updated on 
POST 
/did-registry/v4/jsonrpc

The JSON-RPC API provides methods assisting the construction of blockchain transactions and interaction with the ledger, i.e. write operation on ledger.

Request​

Bodyrequired

The body follows the JSON-RPC 2.0 specification.

It requires the following fields:

  • jsonrpc: must be exactly "2.0"
  • method: method to be invoked
  • params: method parameters
  • id: identifier established by the client

API Methods​

insertDidDocument​

Requires an access token with didr_invite or didr_write scope.

Call to build an unsigned transaction to insert a new DID document.

Parameters:

  • from: Ethereum address of the signer
  • did: DID to insert. It must be for a legal entity (DID v1)
  • baseDocument: JSON string containing the @context of the DID document
  • vMethodId: Verification method ID. Recommended: thumbprint of the public key JWK.
  • publicKey: Public key for secp256k1 in uncompressed format prefixed with "0x04"
  • isSecp256k1: It must be true
  • notBefore: capability invocation is valid from this time
  • notAfter: expiration of the capability invocation

updateBaseDocument​

Requires an access token with didr_write scope.

Call to build an unsigned transaction to update the base document of an existing DID.

Parameters:

  • from: Ethereum address of the signer
  • did: Existing DID
  • baseDocument: JSON string containing the @context of the DID document

addController​

Requires an access token with didr_write scope.

Call to build an unsigned transaction to add a new controller to an existing DID document.

Parameters:

  • from: Ethereum address of the signer
  • did: Existing DID
  • controller: DID of the new controller

revokeController​

Requires an access token with didr_write scope.

Call to build an unsigned transaction to revoke a controller from a DID document.

Parameters:

  • from: Ethereum address of the signer
  • did: Existing DID
  • controller: DID of controller to revoke

addVerificationMethod​

Requires an access token with didr_write scope.

Call to build an unsigned transaction to add a verification method.

The verification method will only appear in the DID document after adding a verification relationship.

Parameters:

  • from: Ethereum address of the signer
  • did: Existing DID
  • vMethodId: New verification method ID. Recommended: thumbprint of the public key JWK.
  • isSecp256k1: Boolean defining if the public key is for secp256k1 curve or not
  • publicKey: Public key as hex string. For an ES256K key, it must be in uncompressed format prefixed with "0x04". For other algorithms, it must be the JWK transformed to string and then to hex format.

addVerificationRelationship​

Requires an access token with didr_write scope.

Call to build an unsigned transaction to add a verification relationship.

Parameters:

  • from: Ethereum address of the signer
  • did: Existing DID
  • name: Name of the verification relationship
  • vMethodId: Reference to the verification method
  • notBefore: Verification relationship is valid from this time
  • notAfter: Expiration of the verification relationship

revokeVerificationMethod​

Requires an access token with didr_write scope.

Call to build an unsigned transaction to revoke a verification method.

Parameters:

  • from: Ethereum address of the signer
  • did: Existing DID
  • vMethodId: Reference to the verification method
  • notAfter: Date on which the revocation takes effect. It must be in the past

expireVerificationMethod​

Requires an access token with didr_write scope.

Call to build an unsigned transaction to expire a verification method.

Parameters:

  • from: Ethereum address of the signer
  • did: Existing DID
  • vMethodId: Reference to the verification method
  • notAfter: New expiration date. It must be in the future

rollVerificationMethod​

Requires an access token with didr_write scope.

Call to build an unsigned transaction to roll a verification method.

Parameters:

  • from: Ethereum address of the signer
  • did: Existing DID
  • vMethodId: New verification method ID. Recommended: thumbprint of the public key JWK.
  • isSecp256k1: Boolean defining if the public key is for secp256k1 curve or not
  • publicKey: Public key as hex string. For an ES256K key, it must be in uncompressed format prefixed with "0x04". For other algorithms, it must be the JWK transformed to string and then to hex format.
  • notBefore: Verification relationship is valid from this time
  • notAfter: Expiration of the verification relationship
  • oldVMethodId: Old verification method id that will be rolled
  • duration: Duration of the period of transition. During this period both verification methods will be valid.

sendSignedTransaction​

Requires an access token with didr_invite or didr_write scope.

Sends a signed transaction to the blockchain and returns the hash of the transaction.

Warning: the transaction is not immediately processed. Make sure to check that the transaction has been successfully included in a block before moving on.

You can get the receipt of the transaction by calling the eth_getTransactionReceipt method of Ledger API's Besu endpoint.

Receipts for pending transactions are not available, therefore you will have to wait until the transaction has been processed — usually a few seconds. We recommend you to poll the eth_getTransactionReceipt method until the receipt is available.

Once the receipt is available, you can check the status field to know if the transaction succeeded (0x1) or failed (0x0). If the transaction failed, the revertReason field will give you insights about the reason for the failure. You can learn more about the format of the revert reason in Besu's documentation.

    jsonrpc stringrequired

    Must be exactly "2.0"

    method stringrequired

    Method that needs to be invoked

    params object[]required

    Array of parameters

    id integerrequired

    Identifier established by the client

Responses​

Response

Schema
    jsonrpc string

    Must be exactly "2.0"

    id integer

    Same identifier established by the client in the call

    result object

    Result of the call

    oneOf
    string
Loading...