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 command-line argument api-ipcs-enabled=true.

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 verticies and blocks and while the decisions socket recives individual transactions.

Format

This API uses the json 2.0 RPC format.

Endpoint

/ext/ipcs

Methods

ipcs.publishBlockchain

Register a blockchain so it publishes accepted vertices to a Unix domain socket.

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.

Signature

ipcs.unpublishBlockchain({blockchainID: string}) -> {success: bool}
  • blockchainID is the blockchain that will no longer publish to a Unix domain socket.

Example Call

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

Example Response

{
    "jsonrpc":"2.0",
    "result":{
        "success":true
    },
    "id":1
}