clean up documentation

Author: jellegerbrandy

CONTRIBUTING.md

@@ -1,17 +1,9 @@
-We're really glad you're reading this, because we need volunteer developers to help this project come to fruition. 👏
+If you want to contribute, you are very welcome to do so.
 
-## Instructions
+Any pull requests are welcome, any open issue is fair game, but if you want to be
+sure you are doing something useful, please contact one of the core devs.
 
-These steps will guide you through contributing to this project:
 
-- Fork the repo
-- Clone it and install dependencies
-
-		git clone https://github.com/YOUR-USERNAME/typescript-library-starter
-		npm install
-
-Keep in mind that after running `npm install` the git repo is reset. So a good way to cope with this is to have a copy of the folder to push the changes, and the other to try them.
-
-Make and commit your changes. Make sure the commands npm run build and npm run test:prod are working.
-
-Finally send a [GitHub Pull Request](https://github.com/alexjoverm/typescript-library-starter/compare?expand=1) with a clear list of what you've done (read more [about pull requests](https://help.github.com/articles/about-pull-requests/)). Make sure all of your commits are atomic (one feature per commit).
+To get started, read the documentation, and especially the docs on
+(overview)[./documentation/overview.md] and the docs for
+(developers)[./documentation/development.md]

README.md

@@ -1,12 +1,11 @@
+[![Build Status](https://travis-ci.com/daostack/client.svg?token=aXt9zApRNkfx8zDMypWx&branch=master)](https://travis-ci.com/daostack/client)
+
 # DAOstack Client
 
-The DAOStack Client  
-* A library to work with the DAOstack ecosystem
-* Convenience functions to interact with the DAOstack contracts: vote, stake and execute proposals
-* A frontend client library for the [DAOstack subgraph](https://github.com/daostack/subgraph) - search for daos, proposaals
-*
+The DAOStack Client is a nodejs library to work with the DAOstack ecosystem
+* Convenience functions to interact with the [DAOstack contracts](https://github.com/daostack/arc): create proposals, and vote and stake on them
+* A client library for the [DAOstack subgraph](https://github.com/daostack/subgraph) - search for daos, proposals
 
-[![Build Status](https://travis-ci.com/daostack/client.svg?token=aXt9zApRNkfx8zDMypWx&branch=master)](https://travis-ci.com/daostack/client)
 
 ## Usage
 
@@ -23,7 +22,7 @@ import Arc from '@daostack/client'
 const arc = new Arc({
   graphqlHttpProvider: "https://subgraph.daostack.io/subgraphs/name/v23",
   graphqlWsProvider: "wss://ws.subgraph.daostack.io/subgraphs/name/v23",
-  web3Provider: `wss://mainnet.infura.io/ws/v3/e0cdf3bfda9b468fa908aa6ab03d5ba2`,
+  web3Provider: `wss://mainnet.infura.io/ws/v3/${YOUR_TOKEN_HERE}`,
   ipfsProvider: {
     "host": "subgraph.daostack.io",
     "port": "443",
@@ -32,45 +31,11 @@ const arc = new Arc({
   }
 })
 // get a list of DAOs
-arc.daos()
-// before we can use the Arc instance to send transactions, we need to provide it
-// with information on where the contracts can be found
-// query the subgraph for the contract addresses, and use those
-const contractInfos = await arc.fetchContractInfos()
-arc.setContractInfo(contractInfos)
-
+arc.daos().subscribe(
+  (daos) => console.log(`Here are your DAOS: ${daos}`)
+)
 ```
 
 * [overview](./documentation/overview.md)
 * [development](./documentation/development.md)
-* [example](./documentation/example-session.md)
-* [troubleshooting](./documentation/troubleshooting.md)
-
-## Developing
-
-Get all services running:
-
-```sh
-docker-compose up graph-node
-```
-
-This command will start all the services that are needed for a test environment: a graph-node instance, ganache, IPFS and postgresql.
-
-
-To run the tests, run:
-```sh
-npm run test
-```
-
-After you are done, run:
-```
-docker-compose down
-```
-
-
-### Commands
-
-
- - `npm run build`: Generate bundles and typings, create docs
- - `npm run lint`: Lints code
- - `npm run test`: run all tests
+* [example](./documentation/demo.js) (run with `npm run demo`)

documentation/demo.js

@@ -0,0 +1,79 @@
+/**
+ * To run this example, you must
+ * 1. git checkout https://github.com/daostack/client
+ * 2. npmm install
+ * 3. npm run build
+ * 3. docker-compose up -d // this will
+ * 4. nodejs documentation/example.js
+ */
+// "Arc" is the main class that handles configuration and connections to various services
+
+async function main() {
+
+  console.log('hello!')
+
+  //  we import fromt he local build of the library (that was created with npm run build)
+  // but typically, one would do:  require('@daostack/client')
+  const { Arc } = require('../dist/lib/index.js')
+  // create an Arc instanc with settings to connect to the local docker images
+  const arc = new Arc({
+    graphqlHttpProvider: 'http://127.0.0.1:8000/subgraphs/name/daostack',
+    graphqlHttpMetaProvider: 'http://127.0.0.1:8000/subgraphs',
+    graphqlWsProvider: 'http://127.0.0.1:8001/subgraphs/name/daostack',
+    web3Provider: 'ws://127.0.0.1:8545',
+    ipfsProvider: '/ip4/127.0.0.1/tcp/5001',
+  })
+  // we must provice Arc with some contract information. We can either hardcode this, or
+  // get it from the subgraph
+  const contractInfos = await arc.fetchContractInfos()
+  arc.setContractInfos(contractInfos)
+
+  // we get the first returned item from the obervable
+  const { first } = require('rxjs/operators')
+  const daos = await arc.daos().first()
+
+  console.log(`Found ${daos.length} DAOs in ${arc.graphqlHttpProvider}`)
+
+
+  // or if you know the address, just create a new DAO object like this:
+  const dao = arc.dao(daos[0].id)
+
+  // get the DAO state (again, the "first()" object from the observable)
+  const daoState  = await dao.state().first()
+  // the state contains information such as the address, name or nativeToken of the DAO
+  console.log(`This DAO has name "${daoState.name}" and is deployed on ${daoState.address}`)
+
+  // to create a proposal, we must first find the address of the Scheme to create it in
+  const schemes = await dao.schemes({ where: { name: 'ContributionReward'}}).pipe(first()).toPromise()
+
+  if (schemes.length === 0) {
+    throw Error('Something went wrong - no ContrsbutsonReward scheme was registered with this DAO')
+  }
+  const schemeState = await schemes[0].state().pipe(first()).toPromise()
+  const schemeAddress = schemeState.address
+
+  console.log(`We'll create a ${schemeState.name} proposal at the scheme at ${schemeState.address}`)
+
+  // first construct a transaction
+  const tx = dao.createProposal({
+    title: 'Demo Proposal',
+    beneficiary: '0xffcf8fdee72ac11b5c542428b35eef5769c409f0',
+    ethReward: 300 * 10**18,
+    nativeTokenReward: 1,
+    periodLength: 0,
+    periods: 1,
+    reputationReward: 10000,
+    scheme: schemeState.address
+  })
+
+  // now send the transaction - when successful, it will return a Proposal instance
+  const minedTx = await tx.send()
+  //
+  const proposal = minedTx.result
+  console.log(`created a proposal with id ${proposal.id}`)
+  console.log(`..... bye!`)
+  process.exit(0)
+}
+
+main()
+  .catch((err) => { console.log(err); process.exit(0)})

documentation/development.md

@@ -1,31 +1,28 @@
 # Developing
 
-Get all services running:
+For development, it is useful to have local instances of Ganache (an ethereum node), IPFS (which is used to store data), an instance of The Graph with the DAOStack subgraph.
+The package is provided with convenient docker containers that provide  a  complete environment for testing and development:
 
+Get all services running:
 ```sh
-docker-compose up graph-node
+docker-compose up
 ```
 
 This command will build and start a graph instance, ganache, IPFS and postgresql.
 
-Before being able to use these services, you need to deploy the DAOStack contracts and configure the graph node to listen to changes.
-Open another terminal and run the following comand:
-```sh
-npm run setup-env
-```
 
 To run the tests, run:
-```sh
+```
 npm run test
 ```
 
-After you are done, run:
+You may also want to run the (demo.js)[./documentation/demo.js] file for some concrete examples of the usage of the library:
 ```
-docker-compose down
+npm run demo
 ```
-If you update the subgraph dependency in `package.json`, you must re-configure the graph node:
+After you are done, run:
 ```
-npm run setup-env
+docker-compose down
 ```
 
 ## Testing
@@ -38,3 +35,9 @@ Or watch:
 ```sh
 npm run test -- --watch
 ```
+
+### Commands
+
+ - `npm run build`: Generate bundles and typings, create docs
+ - `npm run lint`: Lints code
+ - `npm run test`: run all tests