subspace-docs/api.md

# API

## General

### `new Subspace(web3Provider [, options])`
Constructor. 

**Parameters**
1. `web3Provider` - `Object`: a valid web3 websockets provider.
2. `options` - `Object` (optional): Options used to initialize Subspace
	- `dbFilename` - `String` (optional): Name of the database where the information will be stored (default `'subspace.db'`)
	- `callInterval` - `Number` (optional): - Interval of time in milliseconds to query a contract/address to determine changes in state or balance (default: `undefined`. Obtains data every block).

### `init()`
Initializes **Subspace**

**Returns**
`Promise` that once it's resolved, will mean that **Subspace** is available to use

### `close()`
Dispose and perform the cleanup necessary to remove the internal subscriptions and interval timers created by **Subspace** during its normal execution.

### `contract(instance|{abi,address})`
Adds a `track` method to the web3 contract objects. You can obtain this functionality by passing a `web3.eth.Contract` instance, or the `abi` and `address` of your contract

**Returns**
`web3.eth.Contract` object enhanced with `.track()` functions for methods and events.

## Contract methods

### `myContract.events.MyEvent.track([options])`
Track a contract event.

**Parameters**
1. `options` - `Object` (optional): web3 filter options object to limit the number of events based on a block number range, or indexed filters
    - `filter` - `Object` (optional): Lets you filter events by indexed parameters, e.g. `{filter: {myNumber: [12,13]}}` means all events where `"myNumber"` is `12` or `13`.
    - `fromBlock` - `Number` (optional): The block number from which to get events on.
    - `toBlock` - `Number` (optional): The block number to get events up to (Defaults to `"latest"`)
    - `topics` - `Array` (optional): This allows you to manually set the topics for the event filter. If given the filter property and event signature, (`topic[0]`) will not be set automatically.

**Returns**
`RxJS Observable` which will stream the event `returnValues`.


### `myContract.methods.myMethod([param1[, ...]]).track([callOptions])`
Track a constant function / contract state variable on each block mined, or depending on the `callInterval` option used during **Subspace** initialization.

**Parameters**
1. `callOptions` - `Object` (optional): The options used for calling.
    - `from` - `String` (optional): The address the call “transaction” should be made from.
    - `gasPrice` - `String` (optional): The gas price in wei to use for this call “transaction”.
    - `gas` - `Number` (optional): The maximum gas provided for this call “transaction” (gas limit).

**Returns**
`RxJS Observable` which will stream the function / variable values. Data type will depend on the contract function invoked. 


### `myContract.trackBalance(address [, tokenAddress])`
Track a contract's balance changes for an address on each block mined, or depending on the `callInterval` option used during **Subspace** initialization.

**Parameters**
1. `address` - `String`: The address to get the balance of.
2. `tokenAddress` - `String` (optional): If you want to track the balance for an ERC20 contract, here you can specify the token address. Otherwise, Only ETH balances will be returned.

**Returns**
`RxJS Observable` which will stream a string containing the address balance.


## Low level API for data tracking

These are used in case you don't want to decorate your web3 contract objects, or if you want to track the balance for an specific address.

### `trackEvent(contractObject, eventName [, options])`
Track a contract event.

**Parameters**
1. `contractObject` - `web3.eth.Contract`: An already initialized contract object pointing to an address and containing a valid ABI.
2. `eventName` - `String`: The name of the event to subscribe.
3. `options` - `Object` (optional): web3 filter options object to limit the number of events based on a block number range, or indexed filters
    - `filter` - `Object` (optional): Lets you filter events by indexed parameters, e.g. `{filter: {myNumber: [12,13]}}` means all events where `"myNumber"` is `12` or `13`.
    - `fromBlock` - `Number` (optional): The block number from which to get events on.
    - `toBlock` - `Number` (optional): The block number to get events up to (Defaults to `"latest"`)
    - `topics` - `Array` (optional): This allows you to manually set the topics for the event filter. If given the filter property and event signature, (`topic[0]`) will not be set automatically.

**Returns**
`RxJS Observable` which will stream the event `returnValues`.

### `trackProperty(contractObject, functionName [, functionArgs] [, callOptions])`
Track a constant function / contract state variable on each block mined, or depending on the `callInterval` option used during **Subspace** initialization.

**Parameters**
1. `contractObject` - `web3.eth.Contract`: An already initialized contract object pointing to an address and containing a valid ABI.
2. `functionName` - `String`: Name of the function or variable whose values will be tracked.
3. `functionArgs` - `Array` (optional): Array of arguments that the tracked function receives
4. `callOptions` - `Object` (optional): The options used for calling.
    - `from` - `String` (optional): The address the call “transaction” should be made from.
    - `gasPrice` - `String` (optional): The gas price in wei to use for this call “transaction”.
    - `gas` - `Number` (optional): The maximum gas provided for this call “transaction” (gas limit).

**Returns**
`RxJS Observable` which will stream the function / variable values. Data type will depend on the contract function invoked. 

### `trackBalance(address [, tokenAddress])`
Track balance changes for an address on each block mined, or depending on the `callInterval` option used during **Subspace** initialization.

**Parameters**
1. `address` - `String`: The address to get the balance of.
2. `tokenAddress` - `String` (optional): If you want to track the balance for an ERC20 contract, here you can specify the token address. Otherwise, Only ETH balances will be returned.

**Returns**
`RxJS Observable` which will stream a string containing the address balance.