Merge pull request #285 from oasislabs/armani/docs

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                    |

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 <https://github.com/oasislabs/oasis-rs>`_
+These examples assume an `oasis-rs <https://github.com/oasislabs/oasis-rs>`_
 service is being used.
 
 Set the gateway

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:

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 **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.
+   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.
+
 .. _rpc-options:
 
 RpcOptions
@@ -100,6 +118,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.

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
+<script src="https://cdn.oasiscloud.io/oasis-client-latest/client/index.browser.umd.js"
+  charset="utf-8"
+  type="text/javascript">
+</script>
+```
+
+## 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',
+});
+```

packages/common/README.md

@@ -0,0 +1,5 @@
+# @oasislabs/common
+
+Common utilities for Oasis packages.
+
+See the main [README](/README.md).

packages/confidential/README.md

@@ -0,0 +1,5 @@
+# @oasislabs/confidential
+
+Confidential utilities for Oasis packages.
+
+See the main [README](/README.md).

packages/gateway/README.md

@@ -0,0 +1,5 @@
+# @oasislabs/gateway
+
+Gateway client backend.
+
+See the main [README](/README.md).

packages/service/README.md

@@ -0,0 +1,5 @@
+# @oasislabs/service
+
+Service api generation.
+
+See the main [README](/README.md).

packages/test/README.md

@@ -0,0 +1,5 @@
+# @oasislabs/test
+
+Shared test utilities for Oasis packages.
+
+See the main [README](/README.md).

packages/web3/README.md

@@ -0,0 +1,5 @@
+# @oasislabs/web3
+
+Web3 JSON RPC version of an Oasis Gateway.
+
+See the main [README](/README.md).