Smilo
Github Github Switch to Dark Mode Switch to Light Mode
Languages

Interface Details

All interfaces can be set to run over HTTP, GRPC or HTTP-over-Unix-Sockets.

gRPC for inter-node communication (Deprecated)

We currently have an implementation of gRPC for peer node communication as experiment API. This is not enabled on Smilo yet, but between Blackbox nodes they can be enabled by adding in a couple of properties in the configuration file as child elements of serverConfig.

  • grpcPort - when this value is specified, Blackbox node will start a gRPC server listening on this port. The normal port value would still be used for starting REST server.

  • communicationType - possible values are REST, GRPC. Default value is REST.

Please note that communication between Smilo and Blackbox are still via unix socket. This communication flag provides additional options for Blackbox peer-to-peer communication. If gRPC is the option specified, please ensure the peers urls are provided with the appropriate ports.

!!! info gRPC as a protocol for peer-to-peer communication will be removed from Blackbox version 0.10.2

Blackbox to Blackbox - Public API

Blackbox nodes communicate with each other for:

  • Node/network discovery
  • Sending/Receiving encrypted payloads

The following endpoints are advertised on this interface:

  • /version
  • /upcheck
  • /push
  • /resend
  • /partyinfo
  • /partyinfo/validate

Third Party - Public API

Blackbox nodes communicate with third parties for:

  • storing encrypted payloads for external applications

The following endpoints are advertised on this interface:

  • /version
  • /upcheck
  • /storeraw
  • /keys
  • /partyinfo/keys

Smilo to Blackbox - Private API

Smilo uses this API to:

  • Check if the local Blackbox node is running
  • Send and receive details of private transactions

The following endpoints are advertised on this interface:

  • /version
  • /upcheck
  • /sendraw
  • /send
  • /receiveraw
  • /receive
  • /storeraw
  • /sendsignedtx
  • /transaction/{key}/isSender
  • /transaction/{key}/participants

Admin API

Admins should use this API to:

  • Access information about the Blackbox node
  • Make changes to the configuration of the Blackbox node

The following endpoints are advertised on this API:

  • /peers - Add to, and retrieve from, the Blackbox node's peers list

API Details

version - Get Blackbox version

  • Returns the version of Blackbox that is running.

upcheck - Check Blackbox node is running

  • Returns the text "I'm up!"

push - Push transactions between nodes

  • Persist encrypted payload received from another node.

resend - Resend transaction

  • Resend all transactions for given key or given hash/recipient.

partyinfo - Retrieve details of known nodes

  • GET: Request public keys/url of all known peer nodes.
  • POST: accepts a stream that contains the caller node's network information, and returns a merged copy with the callee node's network information

partyinfo/validate - Validates a node possesses a key

  • Will request a node to decrypt a transaction in order to prove that it has access to the private part of its advertised public key.

sendraw - Send transaction bytestring

  • Send transaction payload bytestring from Smilo to Blackbox node. Blackbox sends the transaction hash in the response back.

send - Send transaction bytestring

  • Similar to sendraw however request payload is in json format. Please see our Swagger documentation for object model.

storeraw - Store transaction bytestring

  • Store transaction bytestring from a third party to Blackbox node. Blackbox sends the transaction hash in the response back.

sendsignedtx - Distribute signed transaction payload

  • Send transaction payload identified by hash (returned by storeraw) from Smilo to Blackbox node. Blackbox sends the transaction hash in the response back.

receiveraw - Receive transaction bytestring

  • Receive decrypted bytestring of the transaction payload from Blackbox to Smilo for transactions it is party to.

receive - Receive transaction bytestring

  • Similar to receiveraw however request payload is in json format. Please see our Swagger documentation for object model.

delete - Delete a transaction

  • Delete hashed encrypted payload stored in Blackbox nodes.

/transaction/{key}/isSender - Determine if a node is the sender

  • Tell if the local enclave is the sender of a particular transaction (by checking if the sender public key is part of the nodes enclave)

/transaction/{key}/participants - Retrieve participants

  • Retrieve transaction participants directly from the database (a recipient will have no participants)

For more interactions with the API see the Swagger documentation.