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

This API is being released as part of an upcoming version.

The upcoming version is not backward compatible with the current stable version. 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 
/track-and-trace/v2/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​

authoriseDid​

Requires an access token with tnt_authorise scope.

Call to build an unsigned transaction to authorise a DID to create documents.

Parameters:

  • from: Ethereum address of the signer
  • senderDid: DID of the signer. Must be a did:ebsi DID (UTF-8)
  • authorisedDid: DID to authorise. Must be a did:ebsi DID (UTF-8) registered in the DID Registry.
  • whiteList: Boolean to define if the DID is authorized or unauthorized

createDocument​

Requires an access token with tnt_create scope.

Call to build an unsigned transaction to create a new Document.

By default, it records the timestamp of the blockchain, but it's possible to define a different timestamp with its respective proof.

Parameters:

  • from: Ethereum address of the signer
  • documentHash: Document hash
  • documentMetadata: Document metadata as hex string
  • didEbsiCreator: DID of the document creator. Must be a did:ebsi DID (UTF-8)
  • timestamp (optional): Timestamp as hex string. By default it uses takes the timestamp from the blockchain
  • timestampProof (optional): Timestamp proof as hex string. It must be defined when "timestamp" is defined

removeDocument​

Requires an access token with tnt_write scope.

Call to build an unsigned transaction to remove a document and all related resources.

Parameters:

  • from: Ethereum address of the signer
  • documentHash: Document hash to remove

grantAccess​

Requires an access token with tnt_write scope.

Call to build an unsigned transaction to grant a permission for a DID in a specific document.

"write" grant requires the transaction signer to be creator of the Document, or signer must have "delegate" permission in the Document. "delegate" grant requires the transaction signer to be creator of the Document.

Parameters:

  • from: Ethereum address of the signer
  • documentHash: Document hash
  • grantedByAccount: Entity that grants the permission. If the entity uses the did:ebsi method, grantedByAccount must be the UTF-8 DID encoded in hexadecimal. If the entity uses the did:key method, grantedByAccount must be the secp256k1 uncompressed public key (64 bytes or 65 bytes with 04 prefix) encoded in hexadecimal.
  • subjectAccount: Entity that receives the permission. If the entity uses the did:ebsi method, subjectAccount must be the UTF-8 DID encoded in hexadecimal. If the entity uses the did:key method, subjectAccount must be the secp256k1 uncompressed public key (64 bytes or 65 bytes with 04 prefix) encoded in hexadecimal.
  • grantedByAccType: DID method of grantedByAccount. Use 0 for did:ebsi or 1 for did:key.
  • subjectAccType: DID method of subjectAccount. Use 0 for did:ebsi or 1 for did:key.
  • permission: Type of the permission to grant. Use 0 for "delegate" or 1 for "write"

revokeAccess​

Requires an access token with tnt_write scope.

Call to build an unsigned transaction to revoke a permission from a DID in a specific Document.

Keep in mind that whenever the document's creator private key is lost, then there is no possibility to revoke access for this creator's documents anymore.

Parameters:

  • from: Ethereum address of the signer
  • documentHash: Document hash
  • revokedByAccount: Entity that revokes the permission. If the entity uses the did:ebsi method, revokedByAccount must be the UTF-8 DID encoded in hexadecimal. If the entity uses the did:key method, revokedByAccount must be the secp256k1 uncompressed public key (64 bytes or 65 bytes with 04 prefix) encoded in hexadecimal.
  • subjectAccount: Entity whose permission is revoked. If the entity uses the did:ebsi method, subjectAccount must be the UTF-8 DID encoded in hexadecimal. If the entity uses the did:key method, subjectAccount must be the secp256k1 uncompressed public key (64 bytes or 65 bytes with 04 prefix) encoded in hexadecimal.
  • permission: Type of the permission to revoke. Use 0 for "delegate" or 1 for "write"

writeEvent​

Requires an access token with tnt_write scope.

Call to build an unsigned transaction to write an event into a specific document.

By default, it records the timestamp of the blockchain, but it's possible to define a different timestamp with its respective proof.

Parameters:

  • from: Ethereum address of the signer
  • eventParams: Event parameters. JSON with the following fields:
    • documentHash: Document hash (hex string)
    • externalHash: External hash (string)
    • sender: Entity that sends the event. If the entity uses the did:ebsi method, sender must be the UTF-8 DID encoded in hexadecimal. If the entity uses the did:key method, sender must be the secp256k1 uncompressed public key (64 bytes or 65 bytes with 04 prefix) encoded in hexadecimal.
    • origin: Origin (string)
    • metadata: Metadata (string)
  • timestamp (optional): Timestamp as hex string. By default it uses takes the timestamp from the blockchain
  • timestampProof (optional): Timestamp proof as hex string. It must be defined when "timestamp" is defined

sendSignedTransaction​

Requires an access token with tnt_authorise, tnt_create or tnt_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.

Note that the REST endpoints may not return the latest data immediately after the transaction is included in a block. The Graph has to process the block event and to update its database before returning the latest data. This can take a couple of seconds after the block is mined.

    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...