Implement a second client to accompany @web3api/client-js. This will prove that Web3APIs are in fact cross-platform.

[Retroactively created issue]

Most of the logic for Web3API is inside of a single class. The logic should be modularized out into discrete components which are leveraged as needed. This will reduce tech debt, code smell, and the time it takes for future iterations. Code will also be easier to test and maintain, making it easier to add on future features.

The proposed structure:

• Client: This is the dev/user entry point into using Web3API's
• URI Resolvers: This is what resolves a query URI into an actual Web3API
• Web3API Definitions: This is a cache of data required to create an instance of a Web3API for usage.
• Web3API: This is an actual Web3API, which can be queried by a user.

The end user will never interact with anything but the Client

Create an automated test harness for Web3API implementations (clients & WASM runtimes). The idea is to be able to automatically:

• Verify a client (host) supports all required Web3 WASM host interfaces (IPFS, ETH, etc).
• Verify a new WASM runtime works with all clients.

Create a user story for how:

• A developer would extend an existing Web3API with their own additions.
• A protocol would define their Web3API allowing for a specific set of extensions.

Examples:

• DAOstack supports Voting Machine & Scheme extensions
• Aragon supports App extensions
• Yearn supports Strategy extensions
• Zerion supports RewardsProgram extensions

Option 1:

api:
  schema:
    file: ./src/schema.graphql
  mutation:
    language: wasm/assemblyscript
    file: ./src/mutation/index.ts
  query:
    language: wasm/assemblyscript
    file: ./src/query/index.ts

Option 2:

api:
  schemas:
    - file: ./src/mutation/schema.graphql
    - file: ./src/query/schema.graphql
  mutation:
    language: wasm/assemblyscript
    file: ./src/mutation/index.ts
  query:
    language: wasm/assemblyscript
    file: ./src/query/index.ts

In order to enable more features, I propose we move beyond GraphQL. We have flexibility here because we control the query resolution process.

Feature List:

Request Modules

a.k.a. custom root types

schema {
  cool: Cool
}

module Cool @read @write {
  beNice(
    a: String!
    b: Uint256
}

...

Create a module system for different Web3API compiler functionalities (WASM, Schema, Subgraph, etc).

Modules can query other modules just like an application queries modules:

query({
  uri: "latest.ethereum.web3api.dev",
  query: `mutation { sendTransaction(
    address: "0x...",
    method: "foo(uint256,address)",
    args: [55, 0x...]
    ) { tx { hash } }
  }`
})

And in the client it can filter for these domains and choose to send them to local modules if it has some. This way we don't need to implement it in WASM, and can instead use a module in the client language to do these requests.

When building or loading a new project, we must validate that the manifest accurately describes all parts of the project.

Related: #17

Ensure the following scenarios can be detected and properly reported:

• Schema import namespace collisions
• Type name collisions (post import + namespacing)
• Unrecognized directives
• Incorrect directive usage
• Import directive must be on Schema or Mutation type
• No underscores in user defined type names

Tooling that has access to the file-system and network should be written in TS and run using Deno to help improve security for the users of the tools.

Make each network's integration a module that Web3API modules can require, and client's can supply. Look to WASI for inspiration.

Create a CLI command for generate API docs.

When using a Web3API module, the client should be able to introspect what type of serialization format it expects. Hopefully this shouldn't have to be used, but it might be the case that in the future the preferred serialization format may change (msgpack currently), and the client will have to translate from the caller's format to the target's format. For example, msgpack => RLP

DAO Spec

• Aragon DAO
• Has the "Token Request" app, which allows an outside investor to send funds, and receive the DAO's token (voting rights) in return.
• Has a non-transferable DAO token (can be made transferable in the future).
• Voting Config: 7 day time period, minimum quorum 10%, pass threshold 60%
• Governing the params (DAO governed JSON file?)

DAO Params

• Investment Multiplier: 1.0 to start
• Work Multiplier: 1.0 to start
• Burn Rate: $5k / Month

Roll-out Plan

Test everything on Rinkeby

1. Deployment
   DAO -> 100k credit to admin

2. dOrg Seed Funding
   dOrg -> 15k$
   DAO -> 15k credit

3. Worker Payouts (Spreadsheet W/ Claims)
   DAO -> $5k + 5k credits to worker A, B, C, D, etc

4. Remove Admin
   DAO -> -100k credit from admin

query/schema.graphql

type SimpleStorage @extension("subgraph") {
  id: ID!
  lastSetBy: Bytes
  setBy: [Bytes!]!
}

This will allow us to create Ethereum, IPFS, and other P2P modules as Web3APIs.

• Networking
• Crypto

I was writing a query like:

await api.query({
        query:
        gql`mutation callView($address: String!, $method: String!, $args: [String!]!) {
            callView(address: $address, method: $method, args: $args)
        }`,
        variables: {
            "address": storageAddress,
            "method": "function get() public view returns (uint256)",
            "args": []
        }
    });

and I was getting an empty object back.

The problem was that the callView method is not a mutation but a query in the schema. As a user I would've expected an error if I try to query/mutate on a method that isn't in the schema.

The code that fixed this issue was switching mutation to query:

await api.query({
        query:
        gql`query callView($address: String!, $method: String!, $args: [String!]!) {
            callView(address: $address, method: $method, args: $args)
        }`,
        variables: {
            "address": storageAddress,
            "method": "function get() public view returns (uint256)",
            "args": []
        }
    });

Run validation over all build files (schema, wasm modules, manifest).

Document all message passing protocols at play within the client. For example:

WASI has created a WASM interface definition markup language that allows you to describe portable interface definitions using WASM Interface Types. You can see WASI's Witx interfaces here: https://github.com/WebAssembly/WASI/tree/master/phases/snapshot/witx

and learn more about why Witx is necessary here: https://youtu.be/LCA9NnH7DxE

It's not currently clear to me if AssemblyScript supports WASM Interface Types, more available here: https://github.com/AssemblyScript/working-group/issues/13

I think the goal of "making the Web3API WASM interface runtime agnostic" can be achieved without the above... all TBD.

Option 1:

api:
  schema:
    file: ./src/mutation/schema.graphql
  schemas:
    - file: ./src/mutation/schema.graphql
    - file: ./src/query/schema.graphql
  mutation:
    language: wasm/assemblyscript
    file: ./src/mutation/index.ts
  query:
    language: wasm/assemblyscript
    file: ./src/query/index.ts

Option 2:

apis:
  - namespace: "cool-storage"
    schemas:
      - file: ./src/mutation/schema.graphql
      - file: ./src/query/schema.graphql
    mutation:
      language: wasm/assemblyscript
      file: ./src/mutation/index.ts
    query:
      language: wasm/assemblyscript
      file: ./src/query/index.ts
  - namespace: "sub-storage"
    schemas:
      - file: ./src/mutation/schema.graphql
      - file: ./src/query/schema.graphql
    mutation:
      language: wasm/assemblyscript
      file: ./src/mutation/index.ts
    query:
      language: wasm/assemblyscript
      file: ./src/query/index.ts

Define a way to version-link the various architectural components: Client(s), Manifest, WASM Interface, CLI

For each network connection (Ethereum, IPFS, etc), allow the user to set permissions on each connection, and also override those network options on a per-API basis. For example, give Ethereum full permissions, but for "protocol Foo" give it only read permissions.

In order to enforce this, when instantiating a new Web3API module we'll need to check what permissions that module requires. If they can't be satisfied, we'll have to throw an exception. Being able to query modules for their required permissions is useful so that we can ask the user before-hand if they consent.

Some psuedo code:

const ipfs = new IPFS({
  access: IPFSAccess.ReadAndWrite | IPFSAccess.Pin,
  provider: "..."
})

const api = new Web3API({
  uri: "api.protocol.eth",
  connections: {
    ipfs
  },
  access: {
    ipfs: IPFSAccess.Read
  }
})

Ex: asking a user if they want to re-submit a failed transaction.

Create a user story for how developers would depend upon an external Web3API and use its functionality inside of a new Web3API. For example:

• 1inch depends on Uniswap
• Exchange depends on 0x
• 1Hive depends on Aragon

NOTE: This is an optional feature. Specifying an API w/o a namespace should still work, and the root path should be assumed.

Manifest Change:

apis:
  - namespace: "foo"
    schema:
      - file: ./src/foo/schema.graphql
    mutation:
      language: wasm/assemblyscript
      file: ./src/foo/mutation/index.ts
    query:
      language: wasm/assemblyscript
      file: ./src/foo/query/index.ts
  - namespace: "bar"
    schemas:
      - file: ./src/bar/mutation/schema.graphql
      - file: ./src/bar/query/schema.graphql
    mutation:
      language: wasm/assemblyscript
      file: ./src/bar/mutation/index.ts
    query:
      language: wasm/assemblyscript
      file: ./src/bar/query/index.ts

Client Change:

client.query({
  uri: "example.eth/foo"
  query: gql`
    mutation {
      setData(
        address: "0x123..."
        value: 5
      )
    }`
})

Develop a better standard around asynchronous host imports.

Cesar (@cbrzn) created this document walking through some things: https://docs.google.com/document/d/1M09dmkP5j5dubb4vtM8WMWxoO8JMEaE1-IHYZ83fWUc/edit

Develop a better story around:

• Determining the host interfaces the module depends on (web3_eth..., web3_ipfs..., etc).
• Giving the module runner privileges as to what interfaces can be used. For example, if you're running a query, all web3_eth... signing capabilities should be shut off.

Questions:

• Should a single query or mutation be able to access multiple networks simultaneously?
• How would switching between them work? A call from within WASM to switch the host-env's context?

Create a clear tech spec for:

1. Web3API Packages (Manifest, Schemas, Modules)
2. Web3API Clients (Initialization, Querying)

And the WASM + GraphQL interface standards that bind the two.

Right now in the JSON Schema, we are sharing types between some fields (i.e: Query and Mutation) that are being repeated, this needs to be fixed

In some cases it may be easier for developers to create a Web3API that is actually in JavaScript instead of WASM. As far as the user is concerned, it is interacted with the same way that any other Web3API is, however in the backend, JavaScript code is actually ran instead.

Since runtime code execution is not allowed, the JavaScript Web3API's must be defined on build, and not during the runtime. This means that the end-user will have to configure which JavaScript Web3API's are allowed to be used. This can be done by linking a specific URI to a JavaScript Web3API.

Support lazy loading & upfront loading, allowing apps to choose when an API's assets are fetched and loaded.

Useful for things like JSON, EthAddress, QmHash, URL, and others.

New base types could be introduced in a Web3API's schema, and its validator could be defined in WASM. The serializer for args would utilize the validator.

Use a configurable logger across all projects. For JS projects, checkout ethers' logger they've created: https://github.com/ethers-io/ethers.js/blob/master/packages/logger/src.ts/index.ts

• Build Command
• CodeGen Command
• Create Command
• Query Command
• Test-Env Command
• No Command Given
• Help Option (all commands)

When developing the node / network interface for wasm modules, create a way for middlewares to be inserted as well. This will allow projects like Pocket Network to develop said middlewares and send requests to supported networks (Ethereum, Cosmos, Polkadot, etc) to a Pocket network node.

Make it clear how schemas inherit one another. Maybe leave it up to the user to add an include statement to do so, and all 3 schemas are isolated from one-another? Or is it best to go the monolith route...? Optimize for simplicity and flexibility, ensuring there aren't strange error cases that can come up from partial updates (etc).

Enable the built version of @web3api/client-js to be embedded into an application using a <script ...> tag.

When building a protocol, verify that the graphql function & argument types match the WASM module's types for that function.

Create a host interface for logging, allowing client modules to:

• log info, warnings, errors
• start / end of a long running processes
• total & current step for sequential step processes (1 ..., 2 ..., 3 ..., etc)

Support REST queries in addition to GraphQL. Some examples...

Schema:

type Query {
  getSomething(arg: String!): String!
}

type Mutation {
  setSomething(arg: String!): String!
}

type Entity @entity {
  id: ID!
  value: String!
}

w3://protocol.eth/query/getSomething?arg=foo
w3://protocol.eth/mutation/setSomething?arg=foo
w3://protocol.eth/entity/0xID

Proposing a standard for enabling scenarios like:

• mobile app deep linking
• browser external website linking

from within Web3APIs.

Follow what's done for WASI, for example, passing all strings as pointers + length. To validate the interfaces is agnostic, try creating a Web3API WASM module in Rust or another language.

Support multiple async queries in a single query.

Create a heap manager to handle the two way marshaling of types. The following cases must be supported for all WASM High Level Types (HLTs):

• WASM <-> Host
• Host <-> WASM
• Host <-> WASM <-> Host

Create tooling to enable standardization of the Web3API manifest schema. This tooling should include:

• sanitization (https://github.com/paazmaya/yaml-validator)
• versioning
• version migrations (https://levelup.gitconnected.com/an-approach-to-javascript-object-schema-migration-ae1bd9f0ce78)
• type safe usage (https://github.com/bcherny/json-schema-to-typescript)