IPC API

The IPC API allows users to create Unix domain sockets for blockchains to publish to. When the blockchain accepts a vertex/block it will publish it to a socket and the decisions contained inside will be published to another.

A node will only expose this API if it is started with config flag api-ipcs-enabled=true.

This API set is for a specific node, it is unavailable on the public server.

IPC Message Format#

Socket messages consist of a 64bit integer in BigEndian format followed by that many bytes.

Example:

Sending:
    [0x41, 0x76, 0x61, 0x78]
Writes to the socket:
    [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x04, 0x41, 0x76, 0x61, 0x78]

IPC Socket URL Format#

The names of the sockets are of the form <network_id>-<chain_id>-<event_type> where <event_type> is either consensus or decisions. The consensus socket receives vertices and blocks and while the decisions socket receives individual transactions.

Format#

This API uses the json 2.0 RPC format.

Endpoint#

/ext/ipcs

Methods#

`ipcs.publishBlockchain`#

Signature:

ipcs.publishBlockchain({blockchainID: string}) -> {consensusURL: string, decisionsURL: string}

blockchainID is the blockchain that will publish accepted vertices.
consensusURL is the path of the Unix domain socket the vertices are published to.
decisionsURL is the path of the Unix domain socket the transactions are published to.

Example Call:

curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "ipcs.publishBlockchain",
    "params":{
        "blockchainID":"11111111111111111111111111111111LpoYY"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/ipcs

Example Response:

{
  "jsonrpc": "2.0",
  "result": {
    "decisionsURL": "/tmp/1-11111111111111111111111111111111LpoYY-consensus",
    "consensusURL": "/tmp/1-11111111111111111111111111111111LpoYY-decisions"
  },
  "id": 1
}

`ipcs.unpublishBlockchain`#

Deregister a blockchain so that it no longer publishes to a Unix domain socket.