subspace/README.md

137 lines
5.5 KiB
Markdown
Raw Normal View History

2019-10-01 19:11:53 +00:00
Subspace
2019-09-02 19:01:59 +00:00
===
## Overview
2019-10-03 02:23:27 +00:00
Subspace 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 observables.
Subspace also takes care of syncing under the hood, saving & loading the state in a local db.
2019-09-02 19:01:59 +00:00
### Documentation
2019-10-03 02:09:11 +00:00
https://status-im.github.io/subspace-docs/
2019-09-02 20:31:54 +00:00
### Install
2019-10-01 19:11:53 +00:00
Subspace can be used in browser, node and native script environments. You can install it through `npm` or `yarn`:
2019-09-02 19:01:59 +00:00
```
2019-10-03 02:09:11 +00:00
npm install --save @status-im/subspace
2019-09-02 19:01:59 +00:00
```
### Usage
2019-09-02 19:01:59 +00:00
#### Import into a dApp
2019-09-02 19:01:59 +00:00
```js
2019-09-02 20:31:54 +00:00
// ESM (might require babel / browserify)
2019-10-03 02:09:11 +00:00
import Subspace from '@status-im/subspace';
2019-09-02 20:31:54 +00:00
// CommonJS
2019-10-03 02:09:11 +00:00
const Subspace = require('@status-im/subspace');
2019-09-02 19:01:59 +00:00
```
2019-09-02 20:31:54 +00:00
2019-09-02 19:01:59 +00:00
### Initializing the library
2019-10-03 02:09:11 +00:00
To interact with the EVM, Subspace requires web3.js and a valid websockets provider.
2019-09-02 19:01:59 +00:00
```js
2019-10-01 19:11:53 +00:00
const subspace = new Subspace(web3.currentProvider);
2019-09-27 20:04:01 +00:00
await subspace.init();
2019-09-02 19:01:59 +00:00
```
2019-10-01 19:11:53 +00:00
In addition to the provider, `Subspace` also accepts an `options` object with settings that can change its behavior:
- `dbFilename` - Name of the database where the information will be stored (default 'subspace.db')
2019-09-02 19:01:59 +00:00
- `callInterval` - Interval of time in milliseconds to query a contract/address to determine changes in state or balance (default: obtain data every block).
2019-10-03 02:09:11 +00:00
- `refreshLastNBlocks` - Ignores last N blocks (from current block), stored in the local db and refresh them via a web3 subscription. Useful for possible reorgs (default: 12)
2019-09-02 19:01:59 +00:00
### API
2019-09-02 19:01:59 +00:00
2019-09-02 20:31:54 +00:00
#### `trackProperty(contractObject, functionName [, functionArgs] [, callOptions])`
Reacts to contract state changes by specifying the view function and arguments to call and query the contract.
2019-09-02 19:01:59 +00:00
```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.
2019-09-02 19:16:48 +00:00
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
2019-09-27 20:04:01 +00:00
subspace.trackProperty(contractObject, functionName, functionArgs, callOptions)
2019-09-02 19:01:59 +00:00
.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).
2019-09-02 20:31:54 +00:00
#### `trackEvent(contractObject, eventName [, options])`
Reacts to contract events and obtain its returned values.
2019-09-02 19:01:59 +00:00
```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.
2019-09-02 19:16:48 +00:00
const options = { filter: { }, fromBlock: 1 }; // options used to query the events. Optional
2019-09-27 20:04:01 +00:00
subspace.trackEvent(contractObject, eventName, options)
.subscribe(eventData => console.dir);
2019-09-02 19:01:59 +00:00
```
2019-09-02 20:31:54 +00:00
#### `trackBalance(address [, tokenAddress])`
2019-10-03 02:09:11 +00:00
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.
2019-09-02 19:01:59 +00:00
```js
// Tracking ETH balance
const address = "0x0001020304050607080900010203040506070809";
2019-09-02 19:16:48 +00:00
2019-09-27 20:04:01 +00:00
subspace
2019-09-02 19:01:59 +00:00
.trackBalance(address)
.subscribe((balance) => {
console.log("ETH balance is ", balance)
});
```
```js
// Tracking ERC20 balance
const address = "0x0001020304050607080900010203040506070809";
const tokenAddress = "0x744d70fdbe2ba4cf95131626614a1763df805b9e"; // SNT Address
2019-09-27 20:04:01 +00:00
subspace.trackBalance(address, tokenAddress)
.subscribe((balance) => {
console.log("Token balance is ", balance)
});
2019-09-02 19:01:59 +00:00
```
#### Subscriptions
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.
2019-09-02 19:01:59 +00:00
Subscriptions can be disposed by executing the method `unsubscribe()` liberating the resource held by it:
```js
2019-09-27 20:04:01 +00:00
const subscription = subspace.trackBalance(address, tokenAddress).subscribe(value => { /* Do something */ });
2019-09-02 19:01:59 +00:00
// ...
subscription.unsubscribe();
```
#### Cleanup
2019-10-03 02:09:11 +00:00
If Subspace is not needed anymore, you need can invoke close() to dispose and perform the cleanup necessary to remove the internal subscriptions and interval timers created by Subspace during its normal execution, thus avoiding any potential memory leak.
2019-09-02 19:01:59 +00:00
```
2019-10-03 02:09:11 +00:00
subspace.close();
2019-09-02 19:01:59 +00:00
```
## Contribution
Thank you for considering to help out with the source code! We welcome contributions from anyone on the internet, and are grateful for even the smallest of fixes!
2019-10-01 19:11:53 +00:00
If you'd like to contribute to Subspace, please fork, fix, commit and send a pull request for the maintainers to review and merge into the main code base. If you wish to submit more complex changes though, please check up with the core devs first on #embark-status channel to ensure those changes are in line with the general philosophy of the project and/or get some early feedback which can make both your efforts much lighter as well as our review and merge procedures quick and simple.
2019-09-02 19:01:59 +00:00
2019-10-03 02:09:11 +00:00
### To build:
2019-10-01 19:03:14 +00:00
* `yarn`
* `yarn build`
```js
2019-10-01 19:28:47 +00:00
const Subspace = require('./dist/node.js');
2019-10-01 19:03:14 +00:00
```
2019-09-02 19:01:59 +00:00
2019-10-03 02:09:11 +00:00
The browser version can be found at `dist/browser.js`. You can also check the examples in `test/`.
2019-09-02 19:01:59 +00:00
## License
2019-10-03 02:23:27 +00:00
MIT