feat: initial commit

.vuepress/config.js

@@ -0,0 +1,29 @@
+module.exports = {
+  title: 'Phoenix',
+  description: 'Reactive ÐApp Development',
+  themeConfig: {
+    displayAllHeaders: true,
+    nav: [
+      { text: 'Getting Started', link: '/getting-started/' },
+      { text: 'API', link: '/api' },
+      { text: 'Integrations', link: '/integrations-overview' },
+      { text: 'Github', link: 'https://github.com/status-im/phoenix' },
+    ],
+    sidebar: [
+      '/',
+      '/how-it-works',
+      '/getting-started',
+      {
+        title: 'Integrations',
+        collapsable: false,
+        children: [
+          ['/integrations-overview', 'Overview'],
+          '/react',
+          '/redux',
+          '/redux-observables'
+        ]
+      },
+      '/api',
+    ]
+  },
+};

api.md

@@ -0,0 +1,14 @@
+# API
+
+## Data tracking methods
+
+### `trackProperty(contractObject, functionName [, functionArgs] [, callOptions])`
+TODO
+
+### `trackEvent(contractObject, eventName [, options])`
+TODO
+
+### `trackBalance(address [, tokenAddress])`
+TODO
+
+## Utilities

getting-started.md

@@ -0,0 +1,114 @@
+# Getting Started
+
+## Installation
+Phoenix can be used in browser, node and native script environments. To get started install Phoenix using `npm` or `yarn` by executing this command in your project directory:
+```bash
+# Using npm
+npm install --save phoenix  
+
+# Using yarn
+yarn add phoenix 
+```
+
+## Importing the library
+
+```js
+// ESM (might require babel / browserify)
+import Phoenix from 'phoenix';  
+
+// CommonJS
+const Phoenix = require('phoenix'); 
+```
+
+
+## Connecting to a web3 provider
+To interact with the EVM, Phoenix requires a valid websockets Web3 provider.
+
+```js
+const eventSyncer = new Phoenix(web3.currentProvider);
+eventSyncer.init();
+```
+
+In addition to the provider, `Phoenix` also accepts an `options` object with settings that can change its behavior:
+- `dbFilename` - Name of the database where the information will be stored (default 'phoenix.db')
+- `callInterval` - Interval of time in milliseconds to query a contract/address to determine changes in state or balance (default: obtain data every block).
+
+
+## Reacting to data
+Phoenix provides tracking functions for contract state, events and balances. These functions return RxJS Observables which you can subscribe to, and obtain and transform the observed data via operators.
+
+
+### Tracking a contract's state
+You can track changes to the contract state, by specifying the view function and arguments to call and query the contract. 
+```js
+const contractObject = ...; // A web3.eth.Contract object initialized with an address and ABI.
+const functionName = "..."; // string containing the name of the contract's constant/view function to track.
+const functionArgs = []; // array containing the arguments of the function to track. Optional
+const callOptions = {from: web3.eth.defaultAccount}; //  Options used for calling. Only `from`, `gas` and `gasPrice` are accepted. Optional
+eventSyncer.trackProperty(contractObject, functionName, functionArgs, callOptions)
+  .subscribe(value => console.dir)
+```
+This can be used as well to track public state variables, since they implicity create a view function when they're declared public. The `functionName` would be the same as the variable name, and `functionArgs` would have a value when the type is a `mapping` or `array` (since these require an index value to query them).
+
+
+
+### Tracking contract events
+You can track events and react to their returned values.
+```js
+const contractObject = ...; // A web3.eth.Contract object initialized with an address and ABI.
+const eventName = "..."; // string containing the name of the event to track.
+const options = { filter: { }, fromBlock: 1 }; // options used to query the events. Optional
+
+eventSyncer.trackEvent(contractObject, eventName, options)
+  .subscribe(eventData => console.dir);
+```
+
+
+
+### Tracking balances of addresses
+You can also track changes in both ETH and ERC20 token balances for each mined block or time interval depending on the `callInterval` configured. Balances are returned as a string containing the vaue in wei.
+
+```js
+// Tracking ETH balance
+const address = "0x0001020304050607080900010203040506070809";
+
+eventSyncer
+  .trackBalance(address)
+  .subscribe((balance) => {
+    console.log("ETH balance is ", balance)
+  });
+```
+
+```js
+// Tracking ERC20 balance
+const address = "0x0001020304050607080900010203040506070809";
+const tokenAddress = "0x744d70fdbe2ba4cf95131626614a1763df805b9e"; // SNT Address
+
+eventSyncer.trackBalance(address, tokenAddress)
+  .subscribe((balance) => {
+    console.log("Token balance is ", balance)
+  });
+```
+
+
+
+## Subscriptions
+You may have noticed that each tracking function has a `.subscribe()`. Subscriptions are triggered each time an observable emits a new value. These subscription receive a callback that must have a parameter which represents the value received from the observable;  and they return a subscription.
+
+Subscriptions can be disposed by executing the method `unsubscribe()` liberating the resource held by it:
+
+```js
+const subscription = eventSyncer.trackBalance(address, tokenAddress).subscribe(value => { /* Do something */ });
+
+// ...
+
+subscription.unsubscribe();
+```
+
+## Cleanup
+If Phoenix `eventSyncer` is not needed anymore, you need to invoke `clean()` to dispose and perform the cleanup necessary to remove the internal subscriptions and interval timers created by Phoenix during its normal execution.  Any subscription created via the tracking methods must be unsubscribed manually (in the current version).
+
+```
+eventSyncer.clean();
+```
+

how-it-works.md

@@ -0,0 +1 @@
+# How it works?

integrations-overview.md

@@ -0,0 +1,3 @@
+# Integrations with other frameworks
+
+Phoenix does not force you to change the architecture of your dApps, making it easy to integrate in existing projects. In this section you can find some pointers on how to integrate Phoenix with various frontend frameworks

react.md

@@ -0,0 +1,43 @@
+# react
+The `observe` HOC is provided to enhance a presentational component to react to any phoenix event. This HOC subscribes/unsubscribes automatically to any observable it receives via `props`.
+
+```js
+/* global web3 */
+import React from "react";
+import ReactDOM from 'react-dom';
+import Phoenix from "phoenix";
+import {observe} from "phoenix/react";
+import SimpleStorageContract from "./SimpleStorageContract"; // web3.eth.Contract object
+
+
+const MyComponent = ({eventData}) => {
+  if(!eventData)
+    return <p>Loading...</p>;
+  
+  return <p>{eventData.someReturnedValue}</p>
+};
+
+const MyComponentObserver = observe(MyComponent); // MyComponent will now observe any observable props!
+
+
+class App extends React.Component {
+  state = {
+    myEventObservable: null
+  }
+
+  componentDidMount() {
+    const eventSyncer = new Phoenix(web3.currentProvider);
+    eventSyncer.init()
+      .then(
+        const myEventObservable = eventSyncer.trackEvent(SimpleStorageContract, "MyEvent", {}, fromBlock: 1 });
+        this.setState({ myEventObservable });
+      );
+  }
+
+  render() {
+    return <MyComponentObserver eventData={this.state.myEventObservable} />;
+  }
+}
+
+ReactDOM.render(<App />, document.getElementById('root'));
+```

readme.md

@@ -0,0 +1,19 @@
+---
+home: true
+actionText: Get Started
+actionLink: /getting-started/
+features:
+- title: Feature 1
+  details: Some text here
+- title: Feature 2
+  details: Some text here
+- title: Feature 3
+  details: Another text here
+footer: MIT Licensed
+---
+
+
+### Overview
+Phoenix is a framework agnostic JS library that embraces reactive programming with RxJS, by observing asynchronous changes in Smart Contracts, and providing methods to track and subscribe to events, changes to the state of contracts and address balances, and react to these changes and events via callbacks.
+
+

redux-observables.md

@@ -0,0 +1,29 @@
+# redux-observables
+Phoenix can be configured in epics created with [redux-observables](https://redux-observable.js.org/). It's recommended to compose these epics by using [mergeMap](https://www.learnrxjs.io/operators/transformation/mergemap.html) or [switchMap](https://www.learnrxjs.io/operators/transformation/switchmap.html) operators
+
+```js
+import {mergeMap, map} from 'rxjs/operators';
+
+const rootEpic = action$ =>
+  action$.pipe(
+    ofType("INIT"),  // Execute when the action type is 'INIT'
+    mergeMap(action =>
+      eventSyncer
+        .trackEvent(MyContract, "MyEventName", { filter: {}, fromBlock: 1})
+        .pipe(
+          map(eventData => myAction(eventData)) // Trigger redux action: MY_ACTION
+        )
+    )
+  );
+
+
+
+// Read more about epics here: https://redux-observable.js.org/docs/basics/Epics.html
+const rootReducer = (state = {}, action) => { /* TODO */ };
+
+const epicMiddleware = createEpicMiddleware();
+
+const store = createStore(rootReducer, applyMiddleware(epicMiddleware));
+
+epicMiddleware.run(rootEpic);
+```

redux.md

@@ -0,0 +1,18 @@
+# redux
+Observables can be used with `redux`. The subscription can dispatch actions using if it has access to the redux store:
+
+```js
+// This example assumes it has access redux store, and the reducer 
+// and middleware have been configured correctly, and phoenix has 
+// been initialized.
+
+const store = ... //
+
+const myAction = eventData => ({type: 'MY_ACTION', eventData});
+
+const myObservable = eventSyncer.trackEvent(SimpleStorageContract, "MyEvent", { filter: {}, fromBlock: 1});
+
+myObservable.subscribe(eventData => {
+  store.dispatch(myAction(eventData));
+});
+```