Skip to main content

JSON RPC

warning

🚧 This section is under construction and not final yet.

Here is a short wishlist of JSON-RPC methods:

Method NameDescriptionResponse FormatJSON Response SupportJAM Codec Response SupportPaginatable
jam_getBlockByHashLooks up block by block hash or header hash and returns Block.JSON or Codec
jam_getWorkPackageByHashLooks up WorkPackage by WorkPackageHash and returns WorkPackage.JSON or Codec
jam_getWorkReportByHashLooks up WorkReport by WorkReportHash and returns WorkReport.JSON or Codec
jam_getServiceGiven a service ID, returns the "info" of the service.JSON or JAM Codec
jam_getServiceCodeGiven a service ID, returns the code hash and code of the service. Optional parameters return the history of code.JSON or JAM Codec
jam_getServicePreimageGiven a service ID, returns a_p, the preimage raw bytes.JSON or JAM Codec
jam_getServiceLookupGiven a service ID, returns a_l, all the hash and length.JSON or JAM Codec
jam_getServiceStorageReturns a full range of keys and values of the service.JSON or JAM Codec
jam_getStateReturns C1-C15, and if a service ID is provided, returns the full range of service keys in the state.JSON or JAM Codec
jam_submitWorkPackageSubmits a work package for processing.JSON or JAM Codec

Request JSON Response

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" \
--data '{"jsonrpc":"2.0","method":"jam_getBlockByHash","params":["0x1234abcd..."],"id":1}' \
http://localhost:8545

Response will be contained in the result object's data attribute:

{
"jsonrpc": "2.0",
"id": 1,
"result": {
"data": ...method-specific object/array here...
}
}

Request JAM Codec Response:

curl -X POST -H "Content-Type: application/json" -H "Accept: application/octet-stream" \
--data '{"jsonrpc":"2.0","method":"jam_getBlockByHash","params":["0x1234abcd..."],"id":1}' \
http://localhost:8545

Response will be binary data.

Pagination

Pagination details are TBD.

Example curl calls

jam_getBlockByHash

Looks up block by block hash or header hash and returns Block in JSON or codec form

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"jam_getBlockByHash","params":["0x1234abcd..."],"id":1}' http://localhost:8545

jam_getWorkPackageByHash

Looks up WorkPackage by WorkPackageHash and returns WorkPackage in JSON or codec form

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"jam_getWorkPackageByHash","params":["0x5678efgh..."],"id":2}' http://localhost:8545

jam_getWorkReportByHash (similar to CE 136: Work-report request)

Looks up WorkReport by WorkReportHash and returns WorkReport in JSON or codec form

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"jam_getWorkReportByHash","params":["0x9abcijkl..."],"id":3}' http://localhost:8545

jam_getService

Given a service id, returns the "info" of the service

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"jam_getService","params":["42"],"id":4}'  http://localhost:8545

jam_getServiceCode

Given a service id, returns the codehash and code of the service. Optional parameters returns the history of code

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"jam_getServiceCode","params":["42"],"id":5}'  http://localhost:8545

jam_getServicePreimage

Given a service id, returns a_p, the preimage raw bytes.

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"jam_getServicePreimage","params":["42"],"id":6}' http://localhost:8545

jam_getServiceLookup

Given a service id, returns a_l all the hash, len

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"jam_getServiceLookup","params":["42"],"id":7}' http://localhost:8545

jam_getServiceStorage

Given a serviceID, returns a full range of keys and values of the service in asa_s.

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"jam_getServiceStorage","params":["42"],"id":8}' http://localhost:8545

jam_getState (similar to CE 129)

Given a startKey, endKey combination, returns the full range of keys in the range in the state in JSON or codec form. If a service ID is provided, the keys and values will be filtered by the service ID.

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"jam_getState","params":["0x0000...", "0xFFFF.."],"id":9}' http://localhost:8545

To query with a service ID:

curl -X POST -H "Content-Type: application/json"  --data '{"jsonrpc":"2.0","method":"jam_getState","params":["0x0000...", "0xFFFF..", "42"],"id":10}' http://localhost:8545

jam_submitWorkPackage (similar to JAMNP - CE 133)

Given a core index and work package posted in JSON or codec form, maps to the same as CE133

To post a work package in JSON, supply the core as the first input and work package as the second input following the codec format here:

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"jam_submitWorkPackage","params":[1, {"authorization": "0x0102030405",...}],"id":11}' http://localhost:8545

To post a work package in raw JAM codec form, supply the core as the first input and work package as a second input as a 0x-prefixed hex represtenation of the JAM codec :

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"jam_submitWorkPackage","params":[1, "0x1234567..." }],"id":11}' http://localhost:8545

Other RPC methods

To support a full JAM Services explorer, here are additional methods that would be desirable to support, in no particular order:

  • jam_getImportSegment -- see GP Section 14.3
  • jam_getHistoricalLookup -- see GP Section 9.5
  • jam_getValidatorStatistics - see GP section 13
  • jam_getBeefyRoot - see GP section 18
  • jam_getAuthorizationsPool - see GP Section 8
  • jam_getAuthorizationQueue - see GP Section 8
  • jam_getDisputes - see GP Section 10
  • jam_getBlessedServices - see GP Section 9.4
  • jam_getAccumulationQueue - see GP Section 12
  • jam_getAccumulationHistory - see GP Section 12

If you have additional suggestions, or would like to document these, submit a PR!