kosu.js: implement a go-kosu JSONRPC client (the NodeClient)

[hrharder]

Use .ts file filter to hide lots of auto-generated markdown diffs.

Overview

Adds the NodeClient class to kosu.js, a JSONRPC/WebSocket for the Kosu RPC-API.

Supports all endpoints of the Kosu JSONRPC (as of #224).

Class: NodeClient

A simple JSONRPC/WebSocket client for the go-kosu JSONRPC-API. Supports the
full Kosu JSONRPC, including subscriptions.

It is built on the web3 WebSocketProvider
JSONRPC client, through a more desirable fork provided by 0x.
As such, it can be configured with the same options supported by the underlying
client.

It must be initialized with the URL of a go-kosu node serving the JSONRPC
over WebSocket.

View the Kosu RPC documentation here.

Hierarchy

• NodeClient

Index

Constructors

• constructor

Properties

• NODE_ID_HASH_OFFSET
• PUBLIC_KEY_LENGTH

Methods

• addOrders
• latestHeight
• numberPosters
• queryPoster
• queryValidator
• remainingLimit
• roundInfo
• subscribeToBlocks
• subscribeToOrders
• subscribeToRebalances
• totalOrders
• unsubscribe
• validators
• publicKeyToNodeId

Object literals

• DEFAULT_OPTIONS

Constructors

constructor

+ new NodeClient(url: string, options?: WebsocketProviderOptions): NodeClient

Defined in NodeClient.ts:69

Create a new NodeClient (node) via a connection to a Kosu node serving
the Kosu JSONRPC/WebSocket.

example

// create a node client (with a request/connection timeout of 1s)
const node = new NodeClient("wss://localhost:14342", { timeout: 1000 });

Parameters:

Name	Type	Description
url	string	Full URL to the Kosu node's WebSocket JSONRPC endpoint.
options?	WebsocketProviderOptions	Options to provide the underlying WebSocketProvider.

Returns: NodeClient

Properties

Static NODE_ID_HASH_OFFSET

▪ NODE_ID_HASH_OFFSET: number = 20

Defined in NodeClient.ts:37

Kosu validator node IDs are the first 20 bytes of the SHA-256 hash of the
public key.

---

Static PUBLIC_KEY_LENGTH

▪ PUBLIC_KEY_LENGTH: number = 32

Defined in NodeClient.ts:31

Kosu validator public key's are 32 bytes long.

Methods

addOrders

▸ addOrders(...orders: any[]): Promise<OrderValidationResult[]>

Defined in NodeClient.ts:101

See kosu_addOrders.

Submit poster-signed orders to the Kosu node to be subsequently proposed
to the network. In order for them to be accepted, they must have signatures
from valid posters who have bonded Kosu tokens.

See the posterRegistry.registerTokens() method to bond KOSU.

Parameters:

Name	Type	Description
...orders	any[]	Orders to submit to the node as subsequent arguments.

Returns: Promise<OrderValidationResult[]>

Validation results from the Kosu node, and/or the transaction
ID's of the accepted orders.

---

latestHeight

▸ latestHeight(): Promise<number>

Defined in NodeClient.ts:112

See kosu_latestHeight.

Get the height of the most recently committed and finalized Kosu block.

Returns: Promise<number>

The most recent Kosu block number.

---

numberPosters

▸ numberPosters(): Promise<number>

Defined in NodeClient.ts:123

See kosu_numberPosters.

Get the total number registered posters from the Kosu node.

Returns: Promise<number>

The total number of poster accounts the node is tracking.

---

queryPoster

▸ queryPoster(address: string): Promise<Poster>

Defined in NodeClient.ts:135

See kosu_queryPoster.

Get finalized (committed into current state) balance and order limit data
about a specified poster account.

Parameters:

Name	Type
address	string

Returns: Promise<Poster>

Balance and order limit data for the specified poster account.

---

queryValidator

▸ queryValidator(nodeId: string): Promise<Validator>

Defined in NodeClient.ts:152

See kosu_queryValidator.

Get finalized (committed into current state) information about a Kosu
validator node, identified by their node ID (also called Tendermint
address).

See NodeClient.publicKeyToNodeId() to converting a validator's encoded
public key to it's node ID.

Parameters:

Name	Type
nodeId	string

Returns: Promise<Validator>

Information about the requested validator (see Validator).

---

remainingLimit

▸ remainingLimit(): Promise<number>

Defined in NodeClient.ts:169

See kosu_remainingLimit.

Get the total number of orders that may be posted this period. It is
equal to the sum of the unutilized bandwidth allocation for each poster
account for the current rebalance period.

Returns: Promise<number>

The unutilized order bandwidth for the current period.

---

roundInfo

▸ roundInfo(): Promise<RoundInfo>

Defined in NodeClient.ts:181

See kosu_roundInfo.

Get the current rebalance period number, starting Ethereum block, ending
Ethereum block, and the maximum number of orders for the period.

Returns: Promise<RoundInfo>

Information about the current rebalance period.

---

subscribeToBlocks

▸ subscribeToBlocks(cb: function): Promise<string>

Defined in NodeClient.ts:237

Read about Kosu subscriptions here.

See kosu_subscribe for topic newBlocks.

Subscribe to new block events, and be updated with the full Tendermint block
after each successful commit.

Parameters:

▪ cb: function

A callback function to handle new rebalance information.

▸ (block: any): void

Parameters:

Name	Type
block	any

Returns: Promise<string>

A UUID that can be used to cancel the new subscription (see node.unsubscribe()).

---

subscribeToOrders

▸ subscribeToOrders(cb: function): Promise<string>

Defined in NodeClient.ts:222

Read about Kosu subscriptions here.

See kosu_subscribe for topic newOrders.

Subscribe to order transaction events, and be udpdated with an array of new
orders each time they are included in a Kosu block.

Parameters:

▪ cb: function

A callback function to handle each array of new orders.

▸ (order: any): void

Parameters:

Name	Type
order	any

Returns: Promise<string>

A UUID that can be used to cancel the new subscription (see node.unsubscribe()).

---

subscribeToRebalances

▸ subscribeToRebalances(cb: function): Promise<string>

Defined in NodeClient.ts:252

Read about Kosu subscriptions here.

See kosu_subscribe for topic newRebalances.

Subscribe to rebalance events, and be updated with each new rebalance round
information (starting block, ending block, etc.).

Parameters:

▪ cb: function

A callback function to handle new rebalance information.

▸ (roundInfo: RoundInfo): void

Parameters:

Name	Type
roundInfo	RoundInfo

Returns: Promise<string>

A UUID that can be used to cancel the new subscription (see node.unsubscribe()).

---

totalOrders

▸ totalOrders(): Promise<number>

Defined in NodeClient.ts:194

See kosu_totalOrders.

Get the total number of orders that have been processed by the network
since genesis.

Returns: Promise<number>

The total number of orders posted since network genesis.

---

unsubscribe

▸ unsubscribe(subscriptionId: string): Promise<void>

Defined in NodeClient.ts:261

Cancel an active subscription.

Parameters:

Name	Type	Description
subscriptionId	string	The UUID of the subscription to cancel.

Returns: Promise<void>

---

validators

▸ validators(): Promise<Validator[]>

Defined in NodeClient.ts:206

See kosu_validators.

Get finalized (committed into current state) information about the current
full validator set. Returns the full set (not paginated).

Returns: Promise<Validator[]>

Information about all active Kosu validators (see Validator).

---

Static publicKeyToNodeId

▸ publicKeyToNodeId(publicKey: string): string

Defined in NodeClient.ts:50

Convert a Kosu/Tendermint public key to the corresponding node ID.

The node ID is the first 20 bytes of the SHA-256 hash of the public key.

Parameters:

Name	Type	Description
publicKey	string	Base64-encoded validator public key.

Returns: string

The node ID (tendermint "address") for that public key.

Object literals

Static DEFAULT_OPTIONS

▪ DEFAULT_OPTIONS: object

Defined in NodeClient.ts:26

The default options specify a connection timeout of 3s, all other defaults
are inherited from WebsocketProviderOptions.

timeout

• timeout: number = 3000

Defined in NodeClient.ts:26

[Freydal]

The only issue I saw was storing the balance in an integer.