diff --git a/packages/kosu-docs/docs/.vuepress/config.js b/packages/kosu-docs/docs/.vuepress/config.js index 757ccc749..ea1a18cf8 100644 --- a/packages/kosu-docs/docs/.vuepress/config.js +++ b/packages/kosu-docs/docs/.vuepress/config.js @@ -44,7 +44,7 @@ module.exports = { ], }, { - title: "Kosu.js", + title: "Kosu Contract Helpers", collapsable: true, food: "2.svg", children: [ @@ -52,7 +52,6 @@ module.exports = { "./kosu-contract-helpers/classes/kosu", "./kosu-contract-helpers/classes/kosutoken", "./kosu-contract-helpers/classes/eventemitter", - "./kosu-contract-helpers/classes/nodeclient", "./kosu-contract-helpers/classes/ordergateway", "./kosu-contract-helpers/classes/orderhelper", "./kosu-contract-helpers/classes/posterregistry", @@ -62,7 +61,7 @@ module.exports = { ], }, { - title: "Kosu system contracts", + title: "Kosu System Contracts", collapsable: true, food: "3.svg", children: [ @@ -89,6 +88,42 @@ module.exports = { food: "5.svg", children: ["./kosu-genesis-cli/", "./kosu-genesis-cli/globals"], }, + { + title: "Kosu Node Client", + collapsable: true, + food: "6.svg", + children: ["./kosu-node-client/", "./kosu-node-client/classes/nodeclient"], + }, + { + title: "Kosu Migrations", + collapsable: true, + food: "7.svg", + children: ["./kosu-migrations/"], + }, + { + title: "Kosu Deployed Addresses", + collapsable: true, + food: "8.svg", + children: ["./kosu-deployed-addresses/", "./kosu-deployed-addresses/globals"], + }, + { + title: "Kosu.js", + collapsable: true, + food: "9.svg", + children: ["./kosu.js/"], + }, + { + title: "Order Server", + collapsable: true, + food: "10.svg", + children: ["./order-server/"], + }, + { + title: "Development Images", + collapsable: true, + food: "11.svg", + children: ["./dev-images/"], + }, ], }, }; diff --git a/packages/kosu-docs/docs/dev-images/README.md b/packages/kosu-docs/docs/dev-images/README.md new file mode 100644 index 000000000..8e963b2fa --- /dev/null +++ b/packages/kosu-docs/docs/dev-images/README.md @@ -0,0 +1,24 @@ +# `@kosu/dev-images` + +Development and CI docker images and supporting scripts for the Kosu project. + +All images defined in this repository are publicly available, and hosted by Google Container Registry. Images can be pulled with: + +```bash +$ docker pull gcr.io/kosu-io/$IMAGE_NAME +``` + +## General images + +Convenient images for development within the Kosu-monorepo. Can be used as drop-in replacements for the images they inherit from (shown in parenthesis). + +- `gcr.io/kosu-io/node-lts` (`node:lts`): Custom Node.js image with all necessary binaries needed to build `kosu-monorepo` pre-installed. Drop-in replacement for `node:lts` image. + +## CI Images + +Docker images used for [Kosu's continuous-integration](https://ci.kosu.io) suite are defined in the [`./ci`](./ci) folder. We use [DroneCI](https://drone.io) and the `ci` images are used to run tests for various Kosu packages. + +The current CI images defined in `dev-images` are listed below. + +- `gcr.io/kosu-io/go-kosu-ci`: Custom `golang` image used to run `go-kosu` CI tests. +- `gcr.io/kosu-io/node-ci`: Custom Node.js (Debian-based) image used for the Kosu contract system CI suite and JS libraries (includes `kosu-monorepo` source build into image). diff --git a/packages/kosu-docs/docs/kosu-deployed-addresses/README.md b/packages/kosu-docs/docs/kosu-deployed-addresses/README.md new file mode 100644 index 000000000..e4fe2abca --- /dev/null +++ b/packages/kosu-docs/docs/kosu-deployed-addresses/README.md @@ -0,0 +1,58 @@ +> **[Kosu Deployed Addresses](README.md)** + +[Globals](globals.md) / + +# Kosu Deployed Addresses + +This repository exposes the deployed addresses of the Kosu protocol contract system. + +### Ropsten + +- **Network ID:** 3 +- **ETHNET URL:** `https://ropsten.infura.io` + +| Contract Name | Last Deploy Date | Deployed Address | +| ------------------------------------------------------------------------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| [OrderGateway](../kosu-system-contracts/contracts/external/OrderGateway.sol) | 09/12/19 | [0xe3c53988b77c2b3fd2b847719743bdb6e1e66843](https://ropsten.etherscan.io/address/0xe3c53988b77c2b3fd2b847719743bdb6e1e66843) | +| [AuthorizedAddresses](../kosu-system-contracts/contracts/access_control/AuthorizedAddresses.sol) | 09/12/19 | [0x93b79200cd23841371024427c39c5e4cd19957c9](https://ropsten.etherscan.io/address/0x93b79200cd23841371024427c39c5e4cd19957c9) | +| [EventEmitter](../kosu-system-contracts/contracts/event/EventEmitter.sol) | 09/12/19 | [0xd55dfe66deccbfdcd462098c6bda59666fd9dafe](https://ropsten.etherscan.io/address/0xd55dfe66deccbfdcd462098c6bda59666fd9dafe) | +| [KosuToken](../kosu-system-contracts/contracts/lib/KosuToken.sol) | 09/12/19 | [0x47f3bbc35acd3f8c5b2b8948c39f23f3c6e21f5a](https://ropsten.etherscan.io/address/0x47f3bbc35acd3f8c5b2b8948c39f23f3c6e21f5a) | +| [Treasury](../kosu-system-contracts/contracts/treasury/Treasury.sol) | 09/12/19 | [0x3a1d181217a5dad549d398a1c17490daecdda3b4](https://ropsten.etherscan.io/address/0x3a1d181217a5dad549d398a1c17490daecdda3b4) | +| [Voting](../kosu-system-contracts/contracts/voting/Voting.sol) | 09/12/19 | [0x2442336571bb044f8793fcdff0d46f65d278e376](https://ropsten.etherscan.io/address/0x2442336571bb044f8793fcdff0d46f65d278e376) | +| [PosterRegistry](../kosu-system-contracts/contracts/poster/PosterRegistry.sol) | 09/12/19 | [0x510733f64b49a502c75e57c9f63bd8c9f49b542c](https://ropsten.etherscan.io/address/0x510733f64b49a502c75e57c9f63bd8c9f49b542c) | +| [ValidatorRegistry](../kosu-system-contracts/contracts/validator/ValidatorRegistry.sol) | 09/12/19 | [0xf12a3c3728d86fcbe02d34a5dbf4bb3c7dd90351](https://ropsten.etherscan.io/address/0xf12a3c3728d86fcbe02d34a5dbf4bb3c7dd90351) | +| [ZeroExV2SubContract](../kosu-system-contracts/contracts/sub-contracts/ZeroExV2SubContract.sol) | 09/12/19 | [0xb395b261f8256c91c143ef3f74c014def1de1f39](https://ropsten.etherscan.io/address/0xb395b261f8256c91c143ef3f74c014def1de1f39) | + +### Kosu Dev PoA + +- **Network ID:** 6174 +- **ETHNET URL:** `https://ethnet.zaidan.io/kosu` + +| Contract Name | Last Deploy Date | Deployed Address | +| ------------------------------------------------------------------------------------------------ | ---------------- | ------------------------------------------ | +| [OrderGateway](../kosu-system-contracts/contracts/external/OrderGateway.sol) | 09/17/19 | 0xb8fda6341f80cbae987ab5cd00dce502097e3152 | +| [AuthorizedAddresses](../kosu-system-contracts/contracts/access_control/AuthorizedAddresses.sol) | 09/17/19 | 0xe473109cb41c773fd2fe01e83c6e51356f9585d6 | +| [EventEmitter](../kosu-system-contracts/contracts/event/EventEmitter.sol) | 09/17/19 | 0x2f3afeff0914f33769cdfbf3fcf870c33b26c311 | +| [KosuToken](../kosu-system-contracts/contracts/lib/KosuToken.sol) | 09/17/19 | 0xcc868306d6188b2b12757a7c3926042b4d3c4e29 | +| [Treasury](../kosu-system-contracts/contracts/treasury/Treasury.sol) | 09/17/19 | 0x46572f9082dd2429c2c138fa9483a67d4f29d423 | +| [Voting](../kosu-system-contracts/contracts/voting/Voting.sol) | 09/17/19 | 0x5d60c93d8b48682cd387c8be7e9461b67ecfbea1 | +| [PosterRegistry](../kosu-system-contracts/contracts/poster/PosterRegistry.sol) | 09/17/19 | 0x7e6534b8205713246e91a14b462d2dbcac3ede17 | +| [ValidatorRegistry](../kosu-system-contracts/contracts/validator/ValidatorRegistry.sol) | 09/17/19 | 0x301bb008f2a8a3cae9918743fe43428551392773 | +| [ZeroExV2SubContract](../kosu-system-contracts/contracts/sub-contracts/ZeroExV2SubContract.sol) | 09/17/19 | 0x0265e7d1b094787cb13174e18a1cefc41279a6c9 | + +### Kosu CI Test + +- **Network ID:** 6175 +- **ETHNET URL:** `http://kosu-geth:8545` + +| Contract Name | Last Deploy Date | Deployed Address | +| ------------------------------------------------------------------------------------------------ | ---------------- | ------------------------------------------ | +| [OrderGateway](../kosu-system-contracts/contracts/external/OrderGateway.sol) | 09/17/19 | 0xb8fda6341f80cbae987ab5cd00dce502097e3152 | +| [AuthorizedAddresses](../kosu-system-contracts/contracts/access_control/AuthorizedAddresses.sol) | 09/17/19 | 0xe473109cb41c773fd2fe01e83c6e51356f9585d6 | +| [EventEmitter](../kosu-system-contracts/contracts/event/EventEmitter.sol) | 09/17/19 | 0x2f3afeff0914f33769cdfbf3fcf870c33b26c311 | +| [KosuToken](../kosu-system-contracts/contracts/lib/KosuToken.sol) | 09/17/19 | 0xcc868306d6188b2b12757a7c3926042b4d3c4e29 | +| [Treasury](../kosu-system-contracts/contracts/treasury/Treasury.sol) | 09/17/19 | 0x46572f9082dd2429c2c138fa9483a67d4f29d423 | +| [Voting](../kosu-system-contracts/contracts/voting/Voting.sol) | 09/17/19 | 0x5d60c93d8b48682cd387c8be7e9461b67ecfbea1 | +| [PosterRegistry](../kosu-system-contracts/contracts/poster/PosterRegistry.sol) | 09/17/19 | 0x7e6534b8205713246e91a14b462d2dbcac3ede17 | +| [ValidatorRegistry](../kosu-system-contracts/contracts/validator/ValidatorRegistry.sol) | 09/17/19 | 0x301bb008f2a8a3cae9918743fe43428551392773 | +| [ZeroExV2SubContract](../kosu-system-contracts/contracts/sub-contracts/ZeroExV2SubContract.sol) | 09/17/19 | 0x0265e7d1b094787cb13174e18a1cefc41279a6c9 | \ No newline at end of file diff --git a/packages/kosu-docs/docs/kosu-deployed-addresses/globals.md b/packages/kosu-docs/docs/kosu-deployed-addresses/globals.md new file mode 100644 index 000000000..e5f304610 --- /dev/null +++ b/packages/kosu-docs/docs/kosu-deployed-addresses/globals.md @@ -0,0 +1,52 @@ +> **[Kosu Deployed Addresses](README.md)** + +[Globals](globals.md) / + +# Kosu Deployed Addresses + +## Index + +### Functions + +* [getAddressesForNetwork](globals.md#const-getaddressesfornetwork) +* [getReceiptsForNetwork](globals.md#const-getreceiptsfornetwork) + +## Functions + +### `Const` getAddressesForNetwork + +▸ **getAddressesForNetwork**(`networkId`: number | string): *`KosuAddresses`* + +*Defined in [index.ts:20](https://github.com/ParadigmFoundation/kosu-monorepo/blob/b1686609/packages/kosu-deployed-addresses/src/index.ts#L20)* + +Get the deployment addresses for a desired network by id. + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`networkId` | number \| string | Ethereum network id. | + +**Returns:** *`KosuAddresses`* + +The addresses for the Kosu contracts. + +___ + +### `Const` getReceiptsForNetwork + +▸ **getReceiptsForNetwork**(`networkId`: number | string): *`KosuDeploymentReceipts`* + +*Defined in [index.ts:10](https://github.com/ParadigmFoundation/kosu-monorepo/blob/b1686609/packages/kosu-deployed-addresses/src/index.ts#L10)* + +Get the deployment receipts for a desired network by id. + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`networkId` | number \| string | Ethereum network id. | + +**Returns:** *`KosuDeploymentReceipts`* + +The deployment receipts for the Kosu contracts. \ No newline at end of file diff --git a/packages/kosu-docs/docs/kosu-migrations/README.md b/packages/kosu-docs/docs/kosu-migrations/README.md new file mode 100644 index 000000000..1fff13263 --- /dev/null +++ b/packages/kosu-docs/docs/kosu-migrations/README.md @@ -0,0 +1,81 @@ +# Kosu Migrations + +This repository contains the migrations necessary to initialize the Kosu contract system. + +These contracts are **under active development and may change extensively at any time**. + +## kosu-migrate cli utility + +The `kosu-migrate` utility is included as a binary to the packages. + +``` +Options: + --version Show version number [boolean] + --rpc-url Full RPC url [string] [default: "http://localhost:8545"] + --force-fresh Ensure the deploying address has no previous network + transactions [boolean] + --bond-tokens, -b Bond tokens for available addresses [boolean] + --rpc-bond Bond tokens for all available unlocked addresses in the + provided rpc-url [boolean] + --bond-only Skip migrations and bond tokens [boolean] + --ether-to-bond, -e Value in ether to bond for all available addresses + (addresses with insufficient balance are skipped) + [number] [default: 60] + -h, --help Show help [boolean] + +``` + +## Deployed addresses + +Below are the deployed addresses for the core Kosu protocol contract system on the Ropsten test network, as well as an internal test network. + +### Ropsten + +- **Network ID:** 3 +- **ETHNET URL:** `https://ropsten.infura.io` + +| Contract Name | Last Deploy Date | Deployed Address | +| ------------------------------------------------------------------------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| [OrderGateway](../kosu-system-contracts/contracts/external/OrderGateway.sol) | 09/12/19 | [0xe3c53988b77c2b3fd2b847719743bdb6e1e66843](https://ropsten.etherscan.io/address/0xe3c53988b77c2b3fd2b847719743bdb6e1e66843) | +| [AuthorizedAddresses](../kosu-system-contracts/contracts/access_control/AuthorizedAddresses.sol) | 09/12/19 | [0x93b79200cd23841371024427c39c5e4cd19957c9](https://ropsten.etherscan.io/address/0x93b79200cd23841371024427c39c5e4cd19957c9) | +| [EventEmitter](../kosu-system-contracts/contracts/event/EventEmitter.sol) | 09/12/19 | [0xd55dfe66deccbfdcd462098c6bda59666fd9dafe](https://ropsten.etherscan.io/address/0xd55dfe66deccbfdcd462098c6bda59666fd9dafe) | +| [KosuToken](../kosu-system-contracts/contracts/lib/KosuToken.sol) | 09/12/19 | [0x47f3bbc35acd3f8c5b2b8948c39f23f3c6e21f5a](https://ropsten.etherscan.io/address/0x47f3bbc35acd3f8c5b2b8948c39f23f3c6e21f5a) | +| [Treasury](../kosu-system-contracts/contracts/treasury/Treasury.sol) | 09/12/19 | [0x3a1d181217a5dad549d398a1c17490daecdda3b4](https://ropsten.etherscan.io/address/0x3a1d181217a5dad549d398a1c17490daecdda3b4) | +| [Voting](../kosu-system-contracts/contracts/voting/Voting.sol) | 09/12/19 | [0x2442336571bb044f8793fcdff0d46f65d278e376](https://ropsten.etherscan.io/address/0x2442336571bb044f8793fcdff0d46f65d278e376) | +| [PosterRegistry](../kosu-system-contracts/contracts/poster/PosterRegistry.sol) | 09/12/19 | [0x510733f64b49a502c75e57c9f63bd8c9f49b542c](https://ropsten.etherscan.io/address/0x510733f64b49a502c75e57c9f63bd8c9f49b542c) | +| [ValidatorRegistry](../kosu-system-contracts/contracts/validator/ValidatorRegistry.sol) | 09/12/19 | [0xf12a3c3728d86fcbe02d34a5dbf4bb3c7dd90351](https://ropsten.etherscan.io/address/0xf12a3c3728d86fcbe02d34a5dbf4bb3c7dd90351) | +| [ZeroExV2SubContract](../kosu-system-contracts/contracts/sub-contracts/ZeroExV2SubContract.sol) | 09/12/19 | [0xb395b261f8256c91c143ef3f74c014def1de1f39](https://ropsten.etherscan.io/address/0xb395b261f8256c91c143ef3f74c014def1de1f39) | + +### Kosu Dev PoA + +- **Network ID:** 6174 +- **ETHNET URL:** `https://ethnet.zaidan.io/kosu` + +| Contract Name | Last Deploy Date | Deployed Address | +| ------------------------------------------------------------------------------------------------ | ---------------- | ------------------------------------------ | +| [OrderGateway](../kosu-system-contracts/contracts/external/OrderGateway.sol) | 09/17/19 | 0xb8fda6341f80cbae987ab5cd00dce502097e3152 | +| [AuthorizedAddresses](../kosu-system-contracts/contracts/access_control/AuthorizedAddresses.sol) | 09/17/19 | 0xe473109cb41c773fd2fe01e83c6e51356f9585d6 | +| [EventEmitter](../kosu-system-contracts/contracts/event/EventEmitter.sol) | 09/17/19 | 0x2f3afeff0914f33769cdfbf3fcf870c33b26c311 | +| [KosuToken](../kosu-system-contracts/contracts/lib/KosuToken.sol) | 09/17/19 | 0xcc868306d6188b2b12757a7c3926042b4d3c4e29 | +| [Treasury](../kosu-system-contracts/contracts/treasury/Treasury.sol) | 09/17/19 | 0x46572f9082dd2429c2c138fa9483a67d4f29d423 | +| [Voting](../kosu-system-contracts/contracts/voting/Voting.sol) | 09/17/19 | 0x5d60c93d8b48682cd387c8be7e9461b67ecfbea1 | +| [PosterRegistry](../kosu-system-contracts/contracts/poster/PosterRegistry.sol) | 09/17/19 | 0x7e6534b8205713246e91a14b462d2dbcac3ede17 | +| [ValidatorRegistry](../kosu-system-contracts/contracts/validator/ValidatorRegistry.sol) | 09/17/19 | 0x301bb008f2a8a3cae9918743fe43428551392773 | +| [ZeroExV2SubContract](../kosu-system-contracts/contracts/sub-contracts/ZeroExV2SubContract.sol) | 09/17/19 | 0x0265e7d1b094787cb13174e18a1cefc41279a6c9 | + +### Kosu CI Test + +- **Network ID:** 6175 +- **ETHNET URL:** `http://kosu-geth:8545` + +| Contract Name | Last Deploy Date | Deployed Address | +| ------------------------------------------------------------------------------------------------ | ---------------- | ------------------------------------------ | +| [OrderGateway](../kosu-system-contracts/contracts/external/OrderGateway.sol) | 09/17/19 | 0xb8fda6341f80cbae987ab5cd00dce502097e3152 | +| [AuthorizedAddresses](../kosu-system-contracts/contracts/access_control/AuthorizedAddresses.sol) | 09/17/19 | 0xe473109cb41c773fd2fe01e83c6e51356f9585d6 | +| [EventEmitter](../kosu-system-contracts/contracts/event/EventEmitter.sol) | 09/17/19 | 0x2f3afeff0914f33769cdfbf3fcf870c33b26c311 | +| [KosuToken](../kosu-system-contracts/contracts/lib/KosuToken.sol) | 09/17/19 | 0xcc868306d6188b2b12757a7c3926042b4d3c4e29 | +| [Treasury](../kosu-system-contracts/contracts/treasury/Treasury.sol) | 09/17/19 | 0x46572f9082dd2429c2c138fa9483a67d4f29d423 | +| [Voting](../kosu-system-contracts/contracts/voting/Voting.sol) | 09/17/19 | 0x5d60c93d8b48682cd387c8be7e9461b67ecfbea1 | +| [PosterRegistry](../kosu-system-contracts/contracts/poster/PosterRegistry.sol) | 09/17/19 | 0x7e6534b8205713246e91a14b462d2dbcac3ede17 | +| [ValidatorRegistry](../kosu-system-contracts/contracts/validator/ValidatorRegistry.sol) | 09/17/19 | 0x301bb008f2a8a3cae9918743fe43428551392773 | +| [ZeroExV2SubContract](../kosu-system-contracts/contracts/sub-contracts/ZeroExV2SubContract.sol) | 09/17/19 | 0x0265e7d1b094787cb13174e18a1cefc41279a6c9 | diff --git a/packages/kosu-docs/docs/kosu-node-client/README.md b/packages/kosu-docs/docs/kosu-node-client/README.md new file mode 100644 index 000000000..242b10b6f --- /dev/null +++ b/packages/kosu-docs/docs/kosu-node-client/README.md @@ -0,0 +1,72 @@ +> **[node-client](README.md)** + +[Globals](globals.md) / + +# Node Client + +A TypeScript/JavaScript library for interacting with the Kosu order relay network. + +**View [the documentation here.](https://github.com/ParadigmFoundation/kosu-monorepo/blob/master/packages/node-client/docs/)** + +## Installation + +The Node Client can be installed into your project through `yarn` or `npm`, and can be passed through `webpack` or `browserify` for usage in the browser. + +### Install + +**Yarn:** + +``` +yarn add @kosu/node-client +``` + +**NPM:** + +``` +npm install --save @kosu/node-client +``` + +### Import + +Kosu and its exported classes can be imported directly into TypeScript or JavaScript projects. + +**TypeScript (and ES6+):** + +```typescript +// top-level Kosu class +import { NodeClient } from "@kosu/node-client"; +``` + +**JavaScript (CommonJS):** + +```javascript +const { NodeClient } = require("@kosu/node-client"); +``` + +## Development + +``` +@todo: add contribution guidelines summary and link +``` + +### Linting + +The TypeScript source can be linted with: + +``` +yarn lint +``` + +### Building + +Build the TypeScript source to distributable JavaScript (CommonJS) as well as source mappings and typing files with: + +``` +yarn build +``` + +## License + +Open-source software, [MIT licensed.](https://github.com/ParadigmFoundation/kosu-monorepo/blob/master/LICENSE) + +Copyright (c) 2019 Paradigm Labs, corp. diff --git a/packages/kosu-docs/docs/kosu-node-client/classes/nodeclient.md b/packages/kosu-docs/docs/kosu-node-client/classes/nodeclient.md new file mode 100644 index 000000000..8a9e5dc07 --- /dev/null +++ b/packages/kosu-docs/docs/kosu-node-client/classes/nodeclient.md @@ -0,0 +1,436 @@ +> **[node-client](../README.md)** + +[Globals](../globals.md) / [NodeClient](nodeclient.md) / + +# 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](https://www.npmjs.com/package/web3) `WebSocketProvider` +JSONRPC client, through a more desirable fork provided by [0x.](https://0x.org) +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.](https://docs.kosu.io/go-kosu/kosu_rpc.html) + +## Hierarchy + +- **NodeClient** + +## Index + +### Constructors + +- [constructor](nodeclient.md#constructor) + +### Properties + +- [NODE_ID_HASH_OFFSET](nodeclient.md#static-node_id_hash_offset) +- [PUBLIC_KEY_LENGTH](nodeclient.md#static-public_key_length) + +### Methods + +- [addOrders](nodeclient.md#addorders) +- [latestHeight](nodeclient.md#latestheight) +- [numberPosters](nodeclient.md#numberposters) +- [queryPoster](nodeclient.md#queryposter) +- [queryValidator](nodeclient.md#queryvalidator) +- [remainingLimit](nodeclient.md#remaininglimit) +- [roundInfo](nodeclient.md#roundinfo) +- [subscribeToBlocks](nodeclient.md#subscribetoblocks) +- [subscribeToOrders](nodeclient.md#subscribetoorders) +- [subscribeToRebalances](nodeclient.md#subscribetorebalances) +- [totalOrders](nodeclient.md#totalorders) +- [unsubscribe](nodeclient.md#unsubscribe) +- [validators](nodeclient.md#validators) +- [publicKeyToNodeId](nodeclient.md#static-publickeytonodeid) + +### Object literals + +- [DEFAULT_OPTIONS](nodeclient.md#static-default_options) + +## Constructors + +### constructor + +\+ **new NodeClient**(`url`: string, `options?`: `WebsocketProviderOptions`): _[NodeClient](nodeclient.md)_ + +Defined in NodeClient.ts:70 + +Create a new NodeClient (`node`) via a connection to a Kosu node serving +the Kosu JSONRPC/WebSocket. + +**`example`** + +```typescript +// 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](nodeclient.md)_ + +## Properties + +### `Static` NODE_ID_HASH_OFFSET + +▪ **NODE_ID_HASH_OFFSET**: _number_ = 20 + +Defined in NodeClient.ts:39 + +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:33 + +Kosu validator public key's are 32 bytes long. + +## Methods + +### addOrders + +▸ **addOrders**(...`orders`: any[]): _`Promise`_ + +Defined in NodeClient.ts:102 + +See [`kosu_addOrders`.](https://docs.kosu.io/go-kosu/kosu_rpc.html#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`_ + +Validation results from the Kosu node, and/or the transaction +ID's of the accepted orders. + +--- + +### latestHeight + +▸ **latestHeight**(): _`Promise`_ + +Defined in NodeClient.ts:113 + +See [`kosu_latestHeight`.](https://docs.kosu.io/go-kosu/kosu_rpc.html#latestheight) + +Get the height of the most recently committed and finalized Kosu block. + +**Returns:** _`Promise`_ + +The most recent Kosu block number. + +--- + +### numberPosters + +▸ **numberPosters**(): _`Promise`_ + +Defined in NodeClient.ts:124 + +See [`kosu_numberPosters`.](https://docs.kosu.io/go-kosu/kosu_rpc.html#numberposters) + +Get the total number registered posters from the Kosu node. + +**Returns:** _`Promise`_ + +The total number of poster accounts the node is tracking. + +--- + +### queryPoster + +▸ **queryPoster**(`address`: string): _`Promise`_ + +Defined in NodeClient.ts:136 + +See [`kosu_queryPoster`.](https://docs.kosu.io/go-kosu/kosu_rpc.html#queryposter) + +Get finalized (committed into current state) balance and order limit data +about a specified poster account. + +**Parameters:** + +| Name | Type | +| --------- | ------ | +| `address` | string | + +**Returns:** _`Promise`_ + +Balance and order limit data for the specified poster account. + +--- + +### queryValidator + +▸ **queryValidator**(`nodeId`: string): _`Promise`_ + +Defined in NodeClient.ts:157 + +See [`kosu_queryValidator`.](https://docs.kosu.io/go-kosu/kosu_rpc.html#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`_ + +Information about the requested validator (see `Validator`). + +--- + +### remainingLimit + +▸ **remainingLimit**(): _`Promise`_ + +Defined in NodeClient.ts:174 + +See [`kosu_remainingLimit`.](https://docs.kosu.io/go-kosu/kosu_rpc.html#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`_ + +The unutilized order bandwidth for the current period. + +--- + +### roundInfo + +▸ **roundInfo**(): _`Promise`_ + +Defined in NodeClient.ts:186 + +See [`kosu_roundInfo`.](https://docs.kosu.io/go-kosu/kosu_rpc.html#roundinfo) + +Get the current rebalance period number, starting Ethereum block, ending +Ethereum block, and the maximum number of orders for the period. + +**Returns:** _`Promise`_ + +Information about the current rebalance period. + +--- + +### subscribeToBlocks + +▸ **subscribeToBlocks**(`cb`: function): _`Promise`_ + +Defined in NodeClient.ts:242 + +Read about Kosu subscriptions [here](https://docs.kosu.io/go-kosu/kosu_rpc.html#subscriptions). + +See [`kosu_subscribe` for topic `newBlocks`.](https://docs.kosu.io/go-kosu/kosu_rpc.html#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`_ + +A UUID that can be used to cancel the new subscription (see `node.unsubscribe()`). + +--- + +### subscribeToOrders + +▸ **subscribeToOrders**(`cb`: function): _`Promise`_ + +Defined in NodeClient.ts:227 + +Read about Kosu subscriptions [here](https://docs.kosu.io/go-kosu/kosu_rpc.html#subscriptions). + +See [`kosu_subscribe` for topic `newOrders`.](https://docs.kosu.io/go-kosu/kosu_rpc.html#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`_ + +A UUID that can be used to cancel the new subscription (see `node.unsubscribe()`). + +--- + +### subscribeToRebalances + +▸ **subscribeToRebalances**(`cb`: function): _`Promise`_ + +Defined in NodeClient.ts:257 + +Read about Kosu subscriptions [here](https://docs.kosu.io/go-kosu/kosu_rpc.html#subscriptions). + +See [`kosu_subscribe` for topic `newRebalances`.](https://docs.kosu.io/go-kosu/kosu_rpc.html#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`_ + +A UUID that can be used to cancel the new subscription (see `node.unsubscribe()`). + +--- + +### totalOrders + +▸ **totalOrders**(): _`Promise`_ + +Defined in NodeClient.ts:199 + +See [`kosu_totalOrders`.](https://docs.kosu.io/go-kosu/kosu_rpc.html#totalorders) + +Get the total number of orders that have been processed by the network +since genesis. + +**Returns:** _`Promise`_ + +The total number of orders posted since network genesis. + +--- + +### unsubscribe + +▸ **unsubscribe**(`subscriptionId`: string): _`Promise`_ + +Defined in NodeClient.ts:266 + +Cancel an active subscription. + +**Parameters:** + +| Name | Type | Description | +| ---------------- | ------ | --------------------------------------- | +| `subscriptionId` | string | The UUID of the subscription to cancel. | + +**Returns:** _`Promise`_ + +--- + +### validators + +▸ **validators**(): _`Promise`_ + +Defined in NodeClient.ts:211 + +See [`kosu_validators`.](https://docs.kosu.io/go-kosu/kosu_rpc.html#validators) + +Get finalized (committed into current state) information about the current +full validator set. Returns the full set (not paginated). + +**Returns:** _`Promise`_ + +Information about all active Kosu validators (see `Validator`). + +--- + +### `Static` publicKeyToNodeId + +▸ **publicKeyToNodeId**(`publicKey`: string): _string_ + +Defined in NodeClient.ts:52 + +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:28 + +The default options specify a connection timeout of 3s, all other defaults +are inherited from `WebsocketProviderOptions`. + +### timeout + +• **timeout**: _number_ = 3000 + +Defined in NodeClient.ts:28 diff --git a/packages/kosu-docs/docs/kosu-node-client/globals.md b/packages/kosu-docs/docs/kosu-node-client/globals.md new file mode 100644 index 000000000..59c791071 --- /dev/null +++ b/packages/kosu-docs/docs/kosu-node-client/globals.md @@ -0,0 +1,11 @@ +> **[node-client](README.md)** + +[Globals](globals.md) / + +# node-client + +## Index + +### Classes + +- [NodeClient](classes/nodeclient.md) diff --git a/packages/kosu-docs/docs/kosu.js/README.md b/packages/kosu-docs/docs/kosu.js/README.md new file mode 100644 index 000000000..ac683cf01 --- /dev/null +++ b/packages/kosu-docs/docs/kosu.js/README.md @@ -0,0 +1,99 @@ +# Kosu.js + +A TypeScript/JavaScript library congregating and exporting kosu packages. + +## Installation + +Kosu.js can be installed into your project through `yarn` or `npm`, and can be passed through `webpack` or `browserify` for usage in the browser. + +### Install + +**Yarn:** + +``` +yarn add @kosu/kosu.js +``` + +**NPM:** + +``` +npm install --save @kosu/kosu.js +``` + +### Import + +Exported classes can be imported directly into TypeScript or JavaScript projects. + +**TypeScript (and ES6+):** + +```typescript +// top-level Kosu class +import { Kosu } from "@kosu/kosu.js"; + +// directly access exported classes/utilities +import { + // contract wrapper classes + KosuToken, + OrderGateway, + PosterRegistry, + Treasury, + ValidatorRegistry, + Voting, + + // utils/classes and constants + OrderSerializer, + OrderHelper, + Signature, + toBytes32, + NULL_ADDRESS, +} from "@kosu/kosu.js"; +``` + +**JavaScript (CommonJS):** + +```javascript +const { Kosu } = require("@kosu/kosu.js"); + +const { + KosuToken, + OrderGateway, + PosterRegistry, + Treasury, + ValidatorRegistry, + Voting, + + OrderSerializer, + OrderHelper, + Signature, + toBytes32, + NULL_ADDRESS, +} = require("@kosu/kosu.js"); +``` + +## Development + +``` +@todo: add contribution guidelines summary and link +``` + +### Linting + +The TypeScript source can be linted with: + +``` +yarn lint +``` + +### Building + +Build the TypeScript source to distributable JavaScript (CommonJS) as well as source mappings and typing files with: + +``` +yarn build +``` + +## License + +Open-source software, [MIT licensed.](https://github.com/ParadigmFoundation/kosu-monorepo/blob/master/LICENSE) + +Copyright (c) 2019 Paradigm Labs, corp. diff --git a/packages/kosu-docs/docs/order-server/README.md b/packages/kosu-docs/docs/order-server/README.md new file mode 100644 index 000000000..c4130a67b --- /dev/null +++ b/packages/kosu-docs/docs/order-server/README.md @@ -0,0 +1,193 @@ +# Tool: `order-server` + +The `order-server` is a simple order indexer for 0x orders relayed through the Kosu network, or a standalone Kosu node (see [`go-kosu`](../go-kosu)). + +## Overview + +The server opens a connection to a Kosu JSONRPC/WebSocket API server and subscribes to new order messages, filtering out non-0x orders. + +It adds all 0x orders to a MySQL database and provides a REST API (see below) for querying order's based on a currency pair, maker address, or a known order ID. + +## Usage + +Build, run, and deploy the `order-server`. + +### Testing + +Run in development with `docker-compose` and the supplied `docker-compose.yaml` file. Fill in the missing environment variables, and start with the following. + +```bash +docker-compose up --build -d +``` + +### Development + +Build the TypeScript source: + +```bash +yarn build +``` + +Start the API server and subscription connection (change environment variable as necessary): + +``` +KOSU_JSONRPC_URL=ws://localhost:14342 yarn start +``` + +### Production + +Load a Docker image built from the supplied `Dockerfile`, configure remote MySQL (or MariaDB) server, and start with `docker run` (must supply necessary environment variables with the `-e` or `--env=` flag). + +## API Reference + +Reference for the available methods from the `order-server` indexer. + +### GET `/search` + +Load and paginate an order-book snapshot of quotes rom the Kosu network by supplying a `baseAsset` address, `quoteAsset` address, and a `side` (bid/ask). + +The returned quote snapshots include `orderId` values which can be used to load the full executable order with the [`/order` method.](#order-by-id) + +#### Request format + +- **API Endpoint:** `/search` +- **Query Parameters:** + + | Name | Required | Default | Description | + | :----------: | :------: | :-----: | :------------------------------------------------------ | + | `baseAsset` | `true` | - | Base asset token address. | + | `quoteAsset` | `true` | - | Quote asset token address. | + | `side` | `true` | - | Specify to retrieve `bid` or `ask` orders for the pair. | + | `page` | `false` | `1` | The page number to retrieve (based on `perPage`). | + | `perPage` | `false` | `10` | The number of order stubs to load per page. | + +- **Example:** + ```bash + curl 'localhost:8000/search?baseAsset=0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2"eAsset=0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359&side=ask&perPage=2' + ``` + +#### Response format + +- **Headers:** + - Content-Type: `application/json` +- **Body:** + ```json + { + "side": "ask", + "quoteAssetAddress": "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2", + "baseAssetAddress": "0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359", + "page": 1, + "perPage": 2, + "quotes": [ + { + "price": "0.00000421", + "size": "534680005130000000", + "expiration": "1561496835", + "orderId": "0x012761a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b351bc33" + }, + { + "price": "216249200000000000", + "size": "53468000513000000000", + "expiration": "1561497137", + "orderId": "0x013842a3ed31b43c8780e905a260a35faefcc527be7516aa11c0256729b5b3518891" + } + ] + } + ``` +- **Notes:** + - Expiration times are UNIX timestamps (seconds). + - Prices and sizes (`price` and `size`) are in base units (wei) of the quote asset. + - Prices and order sizes should be converted to `BigNumbers` for storage/processing (for precision). + - The `orderId` for an quote can be used in the [`/order`](#order-by-id) method to get the full order. + +### GET `/order` + +Load a full 0x order object from the Kosu network, provided an `orderId` string. + +#### Request format + +- **API Endpoint:** `/order` +- **HTTP Method:** `GET` +- **Query Parameters:** + + | Name | Required | Default | Description | + | :--: | :------: | :-----: | :---------------------------------------------------- | + | `id` | `true` | - | The hex-encoded transaction ID of the order to fetch. | + +- **Example:** + ```bash + curl 'https://search.zaidan.io/api/v1/order?id=0x3b5d97f1a8d0eb833fe1954f87ec3e8099a1d012f5aac397c987b414060546af' + ``` + +#### Response format + +- **Headers:** + - Content-Type: `application/json` +- **Body:** + ```json + { + "id": "0x3b5d97f1a8d0eb833fe1954f87ec3e8099a1d012f5aac397c987b414060546af", + "order": { + "makerAddress": "0xa916b82ff122591cc88aac0d64ce30a8e3e16081", + "makerAssetAmount": "1000000000000000000", + "takerAssetAmount": "1000000000000000000", + "expirationTimeSeconds": "1559941224", + "makerAssetData": "0xf47261b0000000000000000000000000e41d2489571d322189246dafa5ebde1f4699f498", + "takerAssetData": "0xf47261b000000000000000000000000089d24a6b4ccb1b6faa2625fe562bdd9a23260359", + "makerFee": "0", + "takerFee": "0", + "salt": "45038821417800674048750115101428369947416636882675537172847246510449321143785", + "exchangeAddress": "0x4f833a24e1f95d70f028921e27040ca56e09ab0b", + "takerAddress": "0x0000000000000000000000000000000000000000", + "feeRecipientAddress": "0x0000000000000000000000000000000000000000", + "senderAddress": "0x0000000000000000000000000000000000000000", + "signature": "0x1cfab1d9c5df24fa0f74f274b4e0668735bfd9faf029448b6925b795f3a97ce75826bbdfdfaad7eb40692e239726dfc36d74e740e579cb561cd6a798ad92921c4202" + } + } + ``` + +### GET `/orders` + +Load all (or some) orders published by a given `makerAddress`. + +#### Request format + +- **API Endpoint:** `/orders` +- **HTTP Method:** `GET` +- **Query Parameters:** + + | Name | Required | Default | Description | + | :------------: | :------: | :-----: | :------------------------------------------- | + | `makerAddress` | `true` | - | The address of the 0x order's signing maker. | + | `limit` | `false` | `10` | The number of recent orders to fetch. | + +- **Example:** + ```bash + curl 'localhost:8000/orders?makerAddress=0x4f833a24e1f95d70f028921e27040ca56e09ab0b' + ``` + +#### Response format + +- **Headers:** + - Content-Type: `application/json` +- **Body:** + ```json + [ + { + "orderId": "0x8976d8e86f1500008976d8e86f15906a8976d8e86f15000040dc8b020190ab56", + "expiration": 1560371215 + }, + { + "orderId": "0x20610504010a2be428610504010000002861050401000000701231030100e3ca", + "expiration": 1560356165 + }, + { + "orderId": "0xb461050401000000701231030100000206e65d06205040100d46205040100e2b", + "expiration": 1560332518 + }, + { + "orderId": "0x0b3d075500bb7c51cfa6c746599a223b153d8379ff22ee95c338d8e5c02eff1a", + "expiration": 1560359948 + } + ] + ```