latest
Getting started
Introduction
Aragon Connect is a suite of tools that allow you to easily supercharge apps and websites by integrating them with an Aragon organization. It provides a unified interface for fetching data, subscribing to updates, and generating transactions in the context of Aragon organizations. By default, it balances performance with decentralization, but can be extended and configured to strongly prefer one over the other (if you learn how to do both--let us know!). It is compatible with web and Node.js environments.
This guide assumes that you are familiar with the way Aragon organizations work. If that’s not the case, we invite you to get up to charge with the Aragon Basics guide.
What does it look like?
This is how to connect to an organization and list its apps:
1
import connect from '@aragon/connect'
2
3
// Initiates the connection to an organization
4
const org = await connect('example.aragonid.eth', 'thegraph')
5
6
// Fetch the apps belonging to this organization
7
const apps = await org.apps()
8
9
apps.forEach(console.log)
Copied!
Connectors
The idea of connectors is central to Aragon Connect. A connector is an abstraction over a data source.
Aragon Connect allows for injecting any type of connector, and includes two by default:
- Ethereum (WIP): fetch data from an Ethereum node directly.
A connector can be of two types: organization or app, to fetch data from one or the other. The main package of Aragon Connect only provides organization connectors: app connectors need to be imported separately.
Packages
Aragon Connect consists of a few parts:
@aragon/connect: this is the main library. It provides the main features to connect and interact with organizations, and includes the basic organization connectors.@aragon/connect-finance: an app connector for fetching data from the Finance app.@aragon/connect-voting: an app connector for fetching data from the Voting app.@aragon/connect-tokens: an app connector for fetching data from the Tokens app.- Additional app connectors published by individual app authors
A few other packages are also published, but they are only needed to author or extend connectors and not to use the library.
Installation
1
yarn add @aragon/connect
Copied!
You can now import it:
1
import connect from '@aragon/connect'
Copied!
If you want to interact with the Finance, Voting or the Tokens app, you should also install their respective connectors:
1
yarn add @aragon/connect-finance
2
yarn add @aragon/connect-voting
3
yarn add @aragon/connect-tokens
Copied!
Connecting to an organization
As seen above, connecting to an organization can be done by calling the
connect() function.It requires two parameters:
- The address of the organization, which can be any valid Ethereum address (
0x…) or ENS domain (….eth). - The connector you want to use.
1
const org = await connect('example.aragonid.eth', 'thegraph')
Copied!
Connecting to an alternative network
Aragon Connect connects to the Ethereum mainnet by default, but other networks are also available.
1
// Connect to the Rinkeby test network
2
const org = await connect('example.aragonid.eth', 'thegraph', { network: 4 })
Copied!
Fetching an app’s state
Apps can be obtained from an
Organization instance, but they only contain basic information. Alone, an App instance doesn’t provide the state of the app: you need an app connector to achieve this.Let’s see how to retrieve all the votes from a Voting app:
1
import connect from '@aragon/connect'
2
import connectVoting from '@aragon/connect-voting'
3
4
const org = await connect('example.aragonid.eth', 'thegraph')
5
6
// Connect the Voting app using the corresponding connector:
7
const voting = connectVoting(org.app('voting'))
8
9
// Fetch votes of the Voting app
10
const votes = await voting.votes()
Copied!
Subscribing to data updates
It is also possible to subscribe to receive data updates as they arrive.
For example, this is how it can be done for the list of apps:
1
import connect from '@aragon/connect'
2
3
const org = await connect('example.aragonid.eth', 'thegraph')
4
5
const handler = org.onApps((apps) => {
6
console.log('Apps updated:', apps)
7
})
Copied!
The returned handler can be used to stop receiving updates:
1
const handler = org.onApps((apps) => {
2
console.log('Apps updated:', apps)
3
})
4
5
// The callback will stop being called once `handler.unsubscribe()` is called
6
handler.unsubscribe()
Copied!
App connectors also support subscriptions in an identical way:
1
import connect from '@aragon/connect'
2
import connectVoting from '@aragon/connect-voting'
3
4
const org = await connect('example.aragonid.eth', 'thegraph')
5
const voting = connectVoting(org.app('voting'))
6
7
const handler = voting.onVotes((votes) => {
8
console.log('Votes updated:', votes)
9
})
10
11
// Stop receiving updates
12
handler.unsubscribe()
Copied!
Generating a transaction
Methods generating a transaction return an
TransactionIntent object, that can be used to generate the final transaction for a user to sign.Generating a transaction is done in three steps. First, call a method returning a
TransactionIntent object:1
const intent = org.appIntent(voting, 'vote', [votes[0].id, true, true])
Copied!
Then to retrieve the path you want, pass the account that will be signing the transaction. Aragon Connect will go through the permissions of the organization, and return the shortest path:
1
const path = await intent.paths(wallet.account)
Copied!
Finally, you can sign the different transactions associated to this path. Aragon Connect doesn’t handle any signing itself, but returns an object that is ready to use with the library of your choice: ethers.js, Web3.js, or even a JSON-RPC connection to an Ethereum node.
Going further
Now that you are familiar with the basics of Aragon Connect, you may want to explore the examples provided in the repository and the API documentation.
Last modified 8mo ago