Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
287 lines (178 sloc) 11.5 KB
id title sidebar_label hide_title
aragonjs-ref-app
aragonAPI - App
App
true

App

Install

npm install --save @aragon/client

Import

ES6

import AragonApp, { providers } from '@aragon/client'

ES5 (CommonJS)

const AragonApp = require('@aragon/client').default
const providers = require('@aragon/client').providers

API Reference

AragonApp

This class is used to communicate with the wrapper in which the app is run.

Every method in this class sends an RPC message to the wrapper.

The app communicates with the wrapper using a messaging provider. The default provider uses the MessageChannel PostMessage API, but you may specify another provider to use (see the exported providers to learn more about them). You will most likely want to use the WindowMessage provider in your frontend.

To send an intent to the wrapper (i.e. invoke a method on your smart contract), simply call it on the instance of this class as if it was a JavaScript function.

For example, to execute the increment function in your app's smart contract:

const app = new AragonApp()

// Sends an intent to the wrapper that we wish to invoke `increment` on our app's smart contract
app.increment(1).subscribe(
  (txHash) => console.log(`Success! Incremented in tx ${txHash}`),
  (err) => console.log(`Could not increment: ${err}`)
)

The intent function returns an RxJS observable that emits the hash of the transaction that was sent.

You can also pass an optional object after all the required function arguments to specify some values that will be sent in the transaction. They are the same values that can be passed to web3.eth.sendTransaction() and can be checked in this web3.js document.

app.increment(1, { gas: 200000, gasPrice: 80000000 })

Some caveats to customizing transaction parameters:

  • from, to, data: will be ignored as aragon.js will calculate those.
  • gas: If the intent cannot be performed directly (needs to be forwarded), the gas amount will be interpreted as the minimum amount of gas to send in the transaction. Because forwarding performs a heavier transaction gas-wise, if the gas estimation done by aragon.js results in more gas than provided in the parameter, the estimated gas will prevail.

Parameters

  • provider Object A provider used to send and receive messages to and from the wrapper. See providers. (optional, default MessagePortMessage)

Examples

import AragonApp, { providers } from '@aragon/client'

// The default provider should be used in background scripts
const backgroundScriptOfApp = new AragonApp()

// The WindowMessage provider should be used for front-ends
const frontendOfApp = new AragonApp(
  new providers.WindowMessage(window.parent)
)

accounts

Get an array of the accounts the user currently controls over time.

Returns Observable An RxJS observable that emits an array of account addresses every time a change is detected.

network

Get the network the app is connected to over time.

Returns Observable An RxJS observable that emits an object with the connected network's id and type every time the network changes.

identify

Set the app identifier.

This identifier is used to distinguish multiple instances of your app, so choose something that provides additional context to the app instance.

Examples include: the name of a token that the app manages, the type of content that a TCR is curating, the name of a group etc.

Parameters

  • identifier string The identifier of the app.

Examples

app.identify('Customer counter')
// or
app.identify('Employee counter')

Returns void

events

Listens for events on your app's smart contract from the last unhandled block.

Returns Observable An RxJS observable that emits Web3 events.

external

Creates a handle to interact with an external contract (i.e. a contract that is not your app's smart contract, such as a token).

Parameters

Examples

const token = app.external(tokenAddress, tokenJsonInterface)

// Retrieve the symbol of the token
token.symbol().subscribe(symbol => console.log(`The token symbol is ${symbol}`))

// Retrieve the token balance of an account
token.balanceOf(someAccountAddress).subscribe(balance => console.log(`The balance of the account is ${balance}`))

Returns Object An external smart contract handle. Calling any function on this object will send a call to the smart contract and return an RxJS observable that emits the value of the call.

cache

Set a value in the application cache.

Parameters

  • key string The cache key to set a value for
  • value string The value to persist in the cache

Returns string This method passes through value

state

Observe the cached application state over time.

This method is also used to share state between the background script and front-end of your application.

Returns Observable An RxJS observable that emits the application state every time it changes. The type of the emitted values is application specific.

store

Listens for events, passes them through reducer, caches the resulting state and re-emits that state for easy chaining.

This is in fact sugar on top of state, events and cache.

The reducer takes the signature (state, event) à la Redux. Note that it must always return a state, even if it is unaltered by the event.

Also note that the initial state is always null, not undefined, because of JSONRPC limitations.

Optionally takes an array of other Observables to merge with this app's events; for example you might use an external contract's Web3 events.

Parameters

  • reducer Function A function that reduces events to a state. This can return a Promise that resolves to a new state.
  • events Array<Observable>? An optional array of Observables to merge in with the internal events observable (optional, default [empty()])

Examples

// A simple reducer for a counter app

const state$ = app.store((state, event) => {
  // Initial state is always null
  if (state === null) state = 0

  switch (event.event) {
    case 'Increment':
      state++
      return state
    case 'Decrement':
      state--
      return state
  }

  // We must always return a state, even if unaltered
  return state
})
// A reducer that also reduces events from an external smart contract

const token = app.external(tokenAddress, tokenJsonInterface)

const state$ = app.store(
  (state, event) => {
    // ...
  },
  [token.events()]
)

Returns Observable An RxJS observable that emits the application state every time it changes. The type of the emitted values is application specific.

call

Perform a read-only call on the app's smart contract.

Parameters

  • method string The name of the method to call.
  • params ...any An optional variadic number of parameters. The last parameter can be the call options (optional). See the web3.js doc for more details.

Returns Observable An RxJS observable that emits the result of the call.

notify

NOTE: This call is not currently handled by the wrapper

Send a notification.

Parameters

  • title string The title of the notification.
  • body string The body of the notification.
  • context Object An optional context that will be sent back to the app if the notification is clicked. (optional, default {})
  • date Date An optional date that specifies when the notification originally occured. (optional, default newDate())

Returns void

context

NOTE: The wrapper does not currently send contexts to apps

Listen for app contexts.

An app context is an application specific message that the wrapper can send to the app.

For example, if a notification or a shortcut is clicked, the context attached to either of those will be sent to the app.

App contexts can be used to display specific views in your app or anything else you might find interesting.

Returns Observable An RxJS observable that emits app contexts as they are received.-

describeScript

Decodes an EVM callscript and tries to describe the transaction path that the script encodes.

Parameters

  • script string The EVM callscript to describe

Returns Observable An RxJS observable that emits the described transaction path. The emitted transaction path is an array of objects, where each item has a destination, data and description key.