Skip to content

Websocket API Reference

Jump to bottom Edit New page
Yilun Zhang edited this page Aug 2, 2018 · 5 revisions

Websocket API Reference

Here are some APIs to communicate with blockchain.

Contents

  1. usage
  2. error codes
  3. APIs
  4. notice

Details

1. usage

A typical Web request format and a typical response format could be as following:

--> {
		"Action": "getblock",
		"height": 1
	}
<-- {
		"Action":"getblock",
		"Error":0,
		"Desc":"SUCCESS",
		"Result": {"hash":"5f85d1286801c2f1129a02b0b19a3312f8113aaa073b5987346c59e27a12bdc6","header":...},
		"Version":"1.0.0"
	}

The syntax '-->' indicates data sent to Server, and '<--' indicates data sent to Client. If there was an error invoking the method, the following response will be sent:

--> {
		"Action": "getblock",
		"height": -1,
	}
<-- {
		"Action":"getblock",
		"Error":44004,
		"Desc":"UNKNOWN HASH",
		"Result": null,
		"Version":"1.0.0"
	}

2. error codes

code message description
0 "SUCCESS" -
41001 "SESSION EXPIRED" -
41002 "SERVICE CEILING" -
41003 "ILLEGAL DATAFORMAT" -
42001 "INVALID METHOD" -
42002 "INVALID PARAMS" -
42003 "VERIFY TOKEN ERROR" -
43001 "INVALID TRANSACTION" -
43002 "INVALID ASSET" -
43003 "INVALID BLOCK" -
43004 "INVALID HASH" -
43005 "INVALID VERSION" -
44001 "UNKNOWN TRANSACTION" -
44002 "UNKNOWN ASSET" -
44003 "UNKNOWN BLOCK" -
44004 "UNKNOWN HASH" -
45001 "INTERNAL ERROR" -
47001 "SMARTCODE EXEC ERROR" -

3. APIs

  • getlatestblockheight

Get the height of current block.

--> {
		"Action": "getlatestblockheight"
	}
<-- {
		"Action":"getlatestblockheight",
		"Error":0,
		"Desc":"SUCCESS",
		"Result":660,
		"Version":"1.0.0"
	}

  • getblock

Get the block information by height or hash.

--> {
		"Action": "getblock",
		"height": 1
	}
<-- {
		"Action":"getblock",
		"Error":0,
		"Desc":"SUCCESS",
		"Result": {"hash":"5f85d1286801c2f1129a02b0b19a3312f8113aaa073b5987346c59e27a12bdc6","header":...},
		"Version":"1.0.0"
	}

or


--> {
		"Action": "getblock",
		"hash": "5f85d1286801c2f1129a02b0b19a3312f8113aaa073b5987346c59e27a12bdc6"
	}
<-- {
		"Action":"getblock",
		"Error":0,
		"Desc":"SUCCESS",
		"Result": {"hash":"5f85d1286801c2f1129a02b0b19a3312f8113aaa073b5987346c59e27a12bdc6","header":...},
		"Version":"1.0.0"
	}

  • getconnectioncount

Get the connection amount to this node.

--> {
		"Action": "getconnectioncount"
	}
<-- {
		"Action":"getconnectioncount",
		"Error":0,
		"Desc":"SUCCESS",
		"Result":3,
		"Version":"1.0.0"
	}

  • gettransaction

Get a transaction by hash.

--> {
		"Action":  "gettransaction",
		"hash":"327bb43c2e40ccb2f83011d35602829872ab190171b79047397d000eddda18a9",
	}
<-- {
		"Action":"gettransaction",
		"Error":0,
		"Desc":"SUCCESS",
		"Result": {"hash": "327bb43c2e40ccb2f83011d35602829872ab190171b79047397d000eddda18a9", "inputs":...},
		"Version":"1.0.0"
	}

  • heartbeat

heart beat.

--> {
		"Action":  "heartbeat"
	}
<-- {
		"Action":"heartbeat",
		"Error":0,
		"Desc":"SUCCESS",
		"Result":"5a232d0c-79ea-11e8-a7f5-6a00030e74b0",
		"Version":"1.0.0"
	}

  • getsessioncount

Get session amount of websocket.

--> {
		"Action":  "getsessioncount",
		"Addr":    "127.0.0.1:30002"
	}
<-- {
		"Action":"getsessioncount",
		"Error":0,
		"Desc":"SUCCESS",
		"Result":1,
		"Version":"1.0.0"
	}

  • setClient

Register a client. Note that a client should call getwsaddr to get the node it should register with. If a client tries to register with other nodes, an error will be returned.

--> {
		"Action":  "setClient",
		"Addr":    "anything.pubkey"
	}
<-- {
		"Action": "setClient",
		"Error": 0,
		"Desc": "SUCCESS",
		"Result": nil,
		"Version": "1.0.0"
	}

  • sendPacket

Send a packet to destination NKN client. Destination NKN address should be a client NKN address in the form of "identifier.pubkey". Signature can be an empty string for now, but will need to be a valid signature of packet signed by client private key.

--> {
		"Action":  "sendPacket",
		"Dest":    "destination client nkn address",
		"Payload":    "hello world",
		"Signature":    "",
	}
<-- {
		"Action": "sendPacket",
		"Error": 0,
		"Desc": "SUCCESS",
		"Result": nil,
		"Version": "1.0.0"
	}

  • receivePacket

Push a packet to client. Digest can be ignored for now, but will need to be signed using client private key in the future.

<-- {
		"Action": "receivePacket",
		"Src": "source client NKN address",
		"Payload": "hello world",
		"Digest": "fe5731ccaa605877306f4fde82c8b2d39f78fa22ff33f87bb818ffddbad7dd64",
	}

  • updateSigChainBlockHash

Push latest block hash to client. Clients will need this in the future when sending packets.

<-- {
		"Action":"updateSigChainBlockHash",
		"Error":0,
		"Desc":"SUCCESS",
		"Result":"fe5731ccaa605877306f4fde82c8b2d39f78fa22ff33f87bb818ffddbad7dd64",
		"Version":"1.0.0"
	}
NKN Labs
Clone this wiki locally