From 2f52a4b8c5686bee4f0717bb88804d0f63e97b4b Mon Sep 17 00:00:00 2001 From: Armani Ferrante Date: Wed, 11 Sep 2019 13:19:34 -0700 Subject: [PATCH 1/4] docs: camelCase method generation --- docs/service.rst | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/service.rst b/docs/service.rst index ea9bb867..0d184679 100644 --- a/docs/service.rst +++ b/docs/service.rst @@ -73,13 +73,31 @@ For example, // Connects to the remote service. const service = await Service.at(address); + // Service specific rpc parameter. + const argument = 'this is an argument to a Service rpc'; + + // RpcOptions. + const options = { gasLimit: '0xe79732' }; + // Makes an rpc request to `myMethod` and returns the result. - const returnValue = await service.myMethod(); + const returnValue = await service.myMethod(argument, options); + +.. note:: + + The client will ensure all Service api methods are camelCase, as is idiomatic JavaScript, + even if your on-chain service uses snake_case, as is idiomatic Rust. The positional arguments for a given rpc should be passed directly into the method. -In addition, one can specify the ``RpcOptions`` if desired. Note that these options +In addition, one can specify ``RpcOptions``. When used, these options must be the last argument given to a method. +.. important:: Confidential Services + + When making RPCs to confidential services, one **must** specify the ``gasLimit`` option. + Confidential state one can only be accessed by staked committee members in the Oasis protocol + accepted by the Key Manager. As a result, the client can't infer a gas limit by estimating + gas at a gateway. + .. _rpc-options: RpcOptions From 6dfc851cb539178a0c149aee33b492a5157d1f3a Mon Sep 17 00:00:00 2001 From: Armani Ferrante Date: Wed, 11 Sep 2019 13:35:03 -0700 Subject: [PATCH 2/4] docs: Finality w.r.t. rpcs and events --- docs/service.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/service.rst b/docs/service.rst index 0d184679..794b1571 100644 --- a/docs/service.rst +++ b/docs/service.rst @@ -98,6 +98,8 @@ must be the last argument given to a method. accepted by the Key Manager. As a result, the client can't infer a gas limit by estimating gas at a gateway. +A Service's method call returns only after the transaction has been finalized by the Oasis network. + .. _rpc-options: RpcOptions @@ -118,6 +120,8 @@ To listen to events emitted by the service, use the ``addEventListener`` method. console.log('Received the event, ' event); }); +An event is emitted only after the block containing it has been finalized by the Oasis network. + Parameters ---------- 1. ``event`` - ``String``: The name of the event. From cbe9769e052d81bac4969ab39aed28f0c23fbfb1 Mon Sep 17 00:00:00 2001 From: Armani Ferrante Date: Wed, 11 Sep 2019 13:41:27 -0700 Subject: [PATCH 3/4] docs: oasis.gateways.Gateway warning --- docs/gateways.rst | 6 ++++++ docs/service.rst | 8 +++----- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/gateways.rst b/docs/gateways.rst index e12f1d5a..079ad259 100644 --- a/docs/gateways.rst +++ b/docs/gateways.rst @@ -21,6 +21,7 @@ Gateway =============================================== ``oasis.gateways.Gateway`` provides an implementation of ``OasisGateway`` that communicates with a developer-gateway. + It currently only supports HTTP. .. code-block:: javascript @@ -32,6 +33,11 @@ Parameters 1. ``url`` - ``String``: The url of the gateway. 2. ``httpHeaders`` - ``Object``: The http headers to use for authentiication with the gateway. For example, :code:`{ headers: new Map([['X-OASIS-INSECURE-AUTH', 'VALUE']]) }`. +.. warning:: + + The ``oasis.gateways.Gateway`` server is not yet readily availiable in public Oasis infrastructure. + For now, it's recommended to use ``oasis.gateways.Web3Gateway``. + --------------------------------------------------------------------------- .. _ethereum-gateway: diff --git a/docs/service.rst b/docs/service.rst index 794b1571..143f989b 100644 --- a/docs/service.rst +++ b/docs/service.rst @@ -88,15 +88,13 @@ For example, even if your on-chain service uses snake_case, as is idiomatic Rust. The positional arguments for a given rpc should be passed directly into the method. -In addition, one can specify ``RpcOptions``. When used, these options +In addition, one can **optionally** specify ``RpcOptions``. When used, these options must be the last argument given to a method. .. important:: Confidential Services - When making RPCs to confidential services, one **must** specify the ``gasLimit`` option. - Confidential state one can only be accessed by staked committee members in the Oasis protocol - accepted by the Key Manager. As a result, the client can't infer a gas limit by estimating - gas at a gateway. + When making RPCs to **confidential** services, one **must** specify the ``gasLimit`` option. + The client can't estimiate the gas limit when state is confidential. A Service's method call returns only after the transaction has been finalized by the Oasis network. From c24ae795d90485f613426de27722de94af404b83 Mon Sep 17 00:00:00 2001 From: Armani Ferrante Date: Wed, 11 Sep 2019 14:32:41 -0700 Subject: [PATCH 4/4] Update README.md --- README.md | 17 +++- docs/examples.rst | 2 +- packages/client/README.md | 137 ++++++++++++++++++++++++++++++++ packages/common/README.md | 5 ++ packages/confidential/README.md | 5 ++ packages/gateway/README.md | 5 ++ packages/service/README.md | 5 ++ packages/test/README.md | 5 ++ packages/web3/README.md | 5 ++ 9 files changed, 184 insertions(+), 2 deletions(-) create mode 100644 packages/client/README.md create mode 100644 packages/common/README.md create mode 100644 packages/confidential/README.md create mode 100644 packages/gateway/README.md create mode 100644 packages/service/README.md create mode 100644 packages/test/README.md create mode 100644 packages/web3/README.md diff --git a/README.md b/README.md index 3909f86b..1b3bb9c8 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,28 @@ [![Gitter chat](https://badges.gitter.im/Oasis-official/Lobby.svg)](https://gitter.im/Oasis-official/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![docs](https://readthedocs.com/projects/oasis-labs-oasis-client/badge/?version=latest)](https://oasis-labs-oasis-client.readthedocs-hosted.com/en/latest/) -See the [documentation](https://oasis-labs-oasis-client.readthedocs-hosted.com/en/latest/) +See the [documentation](https://oasis-labs-oasis-client.readthedocs-hosted.com/en/latest/). ## Packages +### The Client + +For most use cases, it's recommended to use the main `@oasislabs/client` package +for all your Oasis client needs, for which there is extensive documentation. + | Package | Version | Description | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | | [`@oasislabs/client`](/packages/client) | [![npm](https://img.shields.io/npm/v/@oasislabs/client.svg)](https://www.npmjs.com/package/@oasislabs/client) | Client SDK for interacting with services on Oasis | + +### Internal Packages + +However, if you only need a subset of the client's features, you can take what +you need directly from the underlying packages. Together these packages compose +the client. Standalone documentation is not provided so it's recommended to use +these only if you know what you're doing. + +| Package | Version | Description | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | | [`@oasislabs/gateway`](/packages/gateway) | [![npm](https://img.shields.io/npm/v/@oasislabs/gateway.svg)](https://www.npmjs.com/package/@oasislabs/gateway) | Oasis Gateway implementation used as the client backend | | [`@oasislabs/service`](/packages/service) | [![npm](https://img.shields.io/npm/v/@oasislabs/service.svg)](https://www.npmjs.com/package/@oasislabs/service) | Connects to and deploys IDL defined services | | [`@oasislabs/confidential`](/packages/confidential) | [![npm](https://img.shields.io/npm/v/@oasislabs/confidential.svg)](https://www.npmjs.com/package/@oasislabs/confidential) | Primitives for confidentiality | diff --git a/docs/examples.rst b/docs/examples.rst index 213e23c9..5baef970 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -5,7 +5,7 @@ Examples .. include:: links.rst Here we walk through a workflow demonstrating the core apis provided by the client. -These examples assume an `oasis-rs docs `_ +These examples assume an `oasis-rs `_ service is being used. Set the gateway diff --git a/packages/client/README.md b/packages/client/README.md new file mode 100644 index 00000000..ebd9e378 --- /dev/null +++ b/packages/client/README.md @@ -0,0 +1,137 @@ +# @oasislabs/client + +`@oasislabs/client` is the main package for oasis.js, composing together all +related workspace packages to create a single bundle available in both JavaScript +and TypeScript. + +If you're new to Oasis, start [here](https://docs.oasis.dev/). + +For a complete introduction to the client, see the [documentation](https://oasis-labs-oasis-client.readthedocs-hosted.com/en/latest/). + +## Installation + +### Node.js + +``` +npm install @oasislabs/client +``` + +### Browser + +The Oasis CDN hosts the latest version of the library. It can be included in your HTML as follows: + +```html + +``` + +## Quickstart + +Let's walk through a workflow demonstrating the core apis provided by the client. +These examples assume an [oasis-rs](https://github.com/oasislabs/oasis-rs). +service is being used. + +### Set the gateway + +First, one must select a gateway, for example, the [Oasis Gateway](https://github.com/oasislabs/developer-gateway). + +```javascript +const oasis = require('@oasislabs/client'); + +// Create a gateway at the given url. +const gateway = new oasis.gateways.Gateway('https://gateway.devnet.oasiscloud.io') + +// Connect the library to the gateway. +oasis.setGateway(gateway); +``` + +### Deploy + +After connecting, one can deploy a new service. + +```javascript +// Service bytecode read directly from a .wasm file compiled with `oasis build`. +const bytecode = require('fs').readFileSync('/path/to/target/service/my-service.wasm'); + +// Service constructor args. +const arg = "this is an argument"; + +// Deploy it through the connected gateway. +const service = await oasis.deploy(arg, { + bytecode, +}); +``` + +### Service + +Alternatively, one can connect to a previously deployed Service. + +```javascript +// On-chain address of the service (dummy address used here);. +const address = '0x288e7e1cc60962f40d4d782950470e3705c5acf4'; + +// Connect to the service. +const service = await oasis.Service.at(address); +``` + +### RPC + +Once you've connected to a service, either by deploying or by connecting to an +existing service, one can execute function calls on that service. + +To make an rpc to a service + +```javascript + +const returnValue = await service.myMethod(); +``` + +### Event Listeners + +In addition to rpcs, one can register event listeners. + +```javascript +service.addEventListener('MyEvent', (event) => { + // do something... +}); +``` + +### Wallets and Web3 Gateways + +In the examples above, we've used a Gateway to pay for and sign transactions. +This is useful when you want the client to operate without a wallet, but sometimes you +want more control. In such cases, it's suggested to use a wallet and web3 gateway which +will allow the client to sign and send raw transactions. + +```javascript +const oasis = require('@oasislabs/client'); + +// Wallet private key. +const privateKey = '0x1ad288d73cd2fff6ecf0a5bf167f59e9944559cd70f66cb70170702a0b4f3bd5'; + +// Wallet for signing and paying for transactions. +const wallet = new oasis.Wallet(privateKey); + +// Etheruem gateway responsible for signing transactions. +const gateway = new oasis.gateways.Web3Gateway('wss://web3.devnet.oasiscloud.io/ws', wallet); + +// Configure the gateway to use. +oasis.setGateway(gateway); +``` + +### Web3 Options + +When using a wallet and web3 gateway, one can also specify the options for the transaction. +This is especially useful when working with confidential services, because the gasLimit *must* +be explicitly supplied (estimate gas isn't provided for confidential services). + +Note that the web3 options must always be the *last* argument given to +an rpc method, after all rpc specific arguments. + +```javascript +service.myMethod({ + gasLimit: '0xf00000', +}); +``` diff --git a/packages/common/README.md b/packages/common/README.md new file mode 100644 index 00000000..3ba08e49 --- /dev/null +++ b/packages/common/README.md @@ -0,0 +1,5 @@ +# @oasislabs/common + +Common utilities for Oasis packages. + +See the main [README](/README.md). diff --git a/packages/confidential/README.md b/packages/confidential/README.md new file mode 100644 index 00000000..98bca909 --- /dev/null +++ b/packages/confidential/README.md @@ -0,0 +1,5 @@ +# @oasislabs/confidential + +Confidential utilities for Oasis packages. + +See the main [README](/README.md). diff --git a/packages/gateway/README.md b/packages/gateway/README.md new file mode 100644 index 00000000..3528d3c3 --- /dev/null +++ b/packages/gateway/README.md @@ -0,0 +1,5 @@ +# @oasislabs/gateway + +Gateway client backend. + +See the main [README](/README.md). diff --git a/packages/service/README.md b/packages/service/README.md new file mode 100644 index 00000000..06fdd5d0 --- /dev/null +++ b/packages/service/README.md @@ -0,0 +1,5 @@ +# @oasislabs/service + +Service api generation. + +See the main [README](/README.md). diff --git a/packages/test/README.md b/packages/test/README.md new file mode 100644 index 00000000..8fcaa9bc --- /dev/null +++ b/packages/test/README.md @@ -0,0 +1,5 @@ +# @oasislabs/test + +Shared test utilities for Oasis packages. + +See the main [README](/README.md). diff --git a/packages/web3/README.md b/packages/web3/README.md new file mode 100644 index 00000000..39ea5517 --- /dev/null +++ b/packages/web3/README.md @@ -0,0 +1,5 @@ +# @oasislabs/web3 + +Web3 JSON RPC version of an Oasis Gateway. + +See the main [README](/README.md).