Skip to main content

Ledger

ebsi ledger call <method> [params]
ebsi ledger block <blockNumberOrTag>
ebsi ledger tx <hash>
ebsi ledger read <registry> <function> <args-json>
ebsi ledger write <registry> <function> <args-json>
ebsi ledger batch <source>
ebsi ledger write-batch <file>

Interacts with the EBSI Besu node through the Ledger service JSON-RPC proxy.

ledger call, block and tx​

ebsi ledger call eth_blockNumber
ebsi ledger call eth_getBalance '["0xabc...", "latest"]'
ebsi ledger block latest
ebsi ledger tx 0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b

call sends any JSON-RPC request (option --id <n>, default 1). block and tx are shorthands for eth_getBlockByNumber and eth_getTransactionByHash.

ledger read​

Encodes a call to a view or pure function of a registry and resolves it with eth_call. It needs no wallet or token. It returns the outputs as an array. The --to <address> option works as in ledger write: when omitted, the address comes from the environment variable of the registry.

ebsi ledger read timestamp getTimestamp '["0xtimestampId"]' --to 0xContractAddress

ledger write​

Encodes a call to a registry function, signs an Ethereum transaction and submits it through the Ledger service.

ArgumentDescription
registryTarget registry, see the table below
functionSmart contract function, for example insertDidDocument
args-jsonFunction arguments as a JSON array string
OptionDescription
--to <address>Contract address. Defaults to the environment variable of the registry
--token <jwt>Bearer access token
--auto-tokenMint a token with the VP flow instead of using an existing one
--scope <scope>Scope for --auto-token. Defaults to the scope of the registry and function, targeted at the --to address
--vc <file>VC file for scopes that need one, with --auto-token
--gas-limit <value>Advanced. Manual gas limit. By default estimated with eth_estimateGas, plus 20%
--gas-price <value>Advanced. Manual gas price, which forces a legacy transaction

If gas estimation fails (for example because the call would revert), the command fails before signing anything.

RegistryDefault scopeAddress environment variable
did-registrydid-registry:writeDID_REGISTRY_CONTRACT_ADDRESS
issuers-registryissuers-registry:writeISSUERS_REGISTRY_CONTRACT_ADDRESS
policies-registrypolicies-registry:writePOLICIES_REGISTRY_CONTRACT_ADDRESS
schemas-registryschemas-registry:writeSCHEMAS_REGISTRY_CONTRACT_ADDRESS
timestamptimestamp:writeTIMESTAMP_CONTRACT_ADDRESS
track-and-tracetrack-and-trace:writeTRACK_AND_TRACE_CONTRACT_ADDRESS

Some functions need another scope. With --auto-token and no --scope, the CLI picks it automatically:

  • did-registry insertDidDocument needs did-registry:invite.
  • track-and-trace authoriseDid needs track-and-trace:authorise, and createDocument and commitCreateDocument need track-and-trace:create.
# Add a controller, minting the token automatically
export DID_REGISTRY_CONTRACT_ADDRESS=0xContractAddress
export EBSI_ES256K_PRIVATE_KEY=0x...
ebsi ledger write did-registry addController \
'["did:ebsi:z123", "did:ebsi:zNewController"]' \
--auto-token

ledger batch​

Sends a raw JSON-RPC batch request (at most 1024 requests, of which at most 100 eth_sendRawTransaction) under one Authorization header.

ebsi ledger batch ./batch.json
echo '[{"id": 1, "method": "eth_blockNumber"}]' | ebsi ledger batch -

<source> is a JSON file containing an array of { "method", "params", "id" } objects, or - to read it from stdin. params defaults to [], and an entry without an id is a notification that gets no response.

ledger write-batch​

Signs several registry writes from one wallet, under one access token, and submits them as a single batch with sequential nonces. It returns transaction hashes, so use ledger tx <hash> to check their status.

[
{
"registry": "did-registry",
"function": "addController",
"args": ["did:ebsi:z123", "did:ebsi:zNewController"],
"to": "0xDidContractAddress"
},
{
"registry": "issuers-registry",
"function": "addIssuerProxy",
"args": ["did:ebsi:z123", "{\"prefix\":\"https://status.example.org/lists\",\"headers\":{},\"testSuffix\":\"/1\"}"],
"to": "0xIssuersContractAddress"
}
]
ebsi --es256k-key 0x... ledger write-batch ./writes.json --auto-token

It takes the same options as ledger write. to is optional per entry. --gas-limit and --gas-price apply to every entry. With --auto-token and no --scope, the CLI mints one multi-scope token covering every registry of the batch, which only works when all the default scopes are combinable. Two functions use a scope that can't be combined with others: did-registry insertDidDocument (did-registry:invite) and track-and-trace authoriseDid (track-and-trace:authorise). A batch containing either of them can't use --auto-token without an explicit --scope, so send it as a single ledger write or pass a --token that covers it.