diff --git a/docs/advanced/app-connectors.md b/docs/advanced/app-connectors.md index d32d5be1..56c9c65c 100644 --- a/docs/advanced/app-connectors.md +++ b/docs/advanced/app-connectors.md @@ -10,13 +10,18 @@ The connectors are composed of a root project which implements a base connector ### The connector -The `src` folder contains a connector implementation for The Graph which uses `@aragon/connect-thegraph` to perform GraphQL queries, parse them, and present the result in the form of entity objects compatible with the `@aragon/connect` API. +We are using and recommend the following structure to implement app connectors. -Use `index.ts` to pick which entities and objects are exposed to other packages. +The `src` folder contains: -In `connector.ts`, add functions that the entities of your connector will use. For example, the `Vote` entity will call its `castsForVote(...): Promise` function. These functions all follow the same structure of \(1\) performing a query, \(2\) parsing the results of a query, and \(3\) wrapping and returning the results in the appropriate entity. +- `models` folder: objects compatible with the `@aragon/connect` API. This is what the consumers of your app connector are going to interact with. +- `thegraph` folder: a connector implementation for The Graph which uses `@aragon/connect-thegraph` to perform GraphQL queries, parse them and present the result in the form of models objects. This part is only used internally, and `connector.ts` contains the methods responsible to fetch the app data from The Graph. -Each of the steps described above is separated in the `entities`, `parsers`, and `queries` folders for clarity. +Use `index.ts` to pick which models and objects are exposed to other packages. + +Use `connect.ts` to create the connector logic [using `createAppConnector()`](#create-the-connector) from `'@aragon/connect-core'`. + +In `thegraph/connector.ts` (assuming your connector is using The Graph), add functions that the models of your connector will use. For example, the `Vote` model of `@aragon/connect-voting` [will call its `castsForVote(...): Promise` function](https://github.com/aragon/connect/blob/12dec7e5147220d29fb960bff01ff95e9ccca1bf/packages/connect-voting/src/models/Vote.ts#L39). These functions all follow the same structure of \(1\) performing a query, \(2\) parsing the results of a query, and \(3\) wrapping and returning the results in the appropriate model. Queries are defined using [`graphql-tag`](https://github.com/apollographql/graphql-tag), which allows using fragments. [Fragments](https://graphql.org/learn/queries/#fragments) are useful when your queries become complicated and you want to reuse "fragments" of queries. @@ -64,7 +69,7 @@ Following the same example, this is how the connector for the Voting app is impl ```js import { createAppConnector } from '@aragon/connect-core' -import Voting from './entities/Voting' +import Voting from './models/Voting' import VotingConnectorTheGraph, { subgraphUrlFromChainId, } from './thegraph/connector' @@ -77,7 +82,7 @@ export default createAppConnector( ) } - return new MyAppConnector( + return new Voting( new VotingConnectorTheGraph( config.subgraphUrl ?? subgraphUrlFromChainId(network.chainId), verbose @@ -88,9 +93,9 @@ export default createAppConnector( ) ``` -#### `createAppConnector\(callback\)` +#### createAppConnector\(callback\) -Here are the parameters passed to the `createAppConnector()` callback: +Parameters passed to the `createAppConnector()` callback: | Name | Type | Description | | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -102,7 +107,7 @@ Here are the parameters passed to the `createAppConnector()` callback: #### appConnect\(app, connector\) -The function returned by `createAppConnector()`, called by app authors, takes these parameters: +The function returned by `createAppConnector()`, called by app authors. It takes these parameters: | Name | Type | Description | | ----------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/api-reference/connect.md b/docs/api-reference/connect.md index 46ba8c39..b50d3753 100644 --- a/docs/api-reference/connect.md +++ b/docs/api-reference/connect.md @@ -15,17 +15,10 @@ Connects and returns an `Organization` for `location`. | `options.network` | [`Networkish`](./types.md#networkish) | The network to connect to. Defaults to `1`. | | returns | `Promise` | An `Organization` instance. | -### Errors - -| Type | Description | -| ---------------------- | ------------------------------------------------------ | -| `ConnectionError` | Gets thrown if the connection fails. | -| `OrganizationNotFound` | Gets thrown if the organization doesn’t seem to exist. | - ### Example ```javascript -import { connect } from '@aragon/connect' +import connect from '@aragon/connect' // Connections should get wrapped in a try / catch to capture connection errors try { diff --git a/docs/api-reference/transaction-intent.md b/docs/api-reference/transaction-intent.md index 8909f70f..71503fbb 100644 --- a/docs/api-reference/transaction-intent.md +++ b/docs/api-reference/transaction-intent.md @@ -20,7 +20,7 @@ This is an easier way to do `TransactionIntent.paths(account, options)[0].transa ### TransactionIntent\#paths\(account, options\) -Get all the possible transaction paths for a given address. This can be useful to let users pick between multiple paths. Otherwise, `TransactionIntent#transactions()` can be called directly. +Get the shortest transaction path for a given address. Note, `TransactionIntent#transactions()` can be called directly. | Name | Type | Description | | -------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------- | @@ -28,4 +28,4 @@ Get all the possible transaction paths for a given address. This can be useful t | `options` | `Object` | Options object. | | `options.as` | `String` | Address of an Aragon organization, or its agent app, through which the paths should get created. | | `options.path` | `String[]` | An array of address that conform a transaction path, it will be verified without calculating other paths. | -| returns | `Promise` | Array of all the possible transaction paths. | +| returns | `Promise` | Shortest transaction path for the intent. | diff --git a/docs/guides/connect-with-react.md b/docs/guides/connect-with-react.md index e205182c..ed8d5e5c 100644 --- a/docs/guides/connect-with-react.md +++ b/docs/guides/connect-with-react.md @@ -77,7 +77,7 @@ This component is required in order to use the provided hooks. | `connector` | `Connector` or `[String, Object]` or `String` | Accepts a `Connector` instance, and either a string or a tuple for embedded connectors and their config. | | `options` | `Object` | The optional configuration object. | | `options.ethereum` | `EthereumProvider` | An [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) compatible object. | -| `options.network` | [`Networkish`](./types.md#networkish) | The network to connect to. Defaults to `1`. | +| `options.network` | [`Networkish`](../api-reference/types.md#networkish) | The network to connect to. Defaults to `1`. | ### useOrganization() diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index 21ed7b67..7633a64d 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -11,7 +11,7 @@ This guide assumes that you are familiar with the way Aragon organizations work. This is how to connect to an organization and list its apps: ```javascript -import { connect } from '@aragon/connect' +import connect from '@aragon/connect' // Initiates the connection to an organization const org = await connect('example.aragonid.eth', 'thegraph') @@ -38,6 +38,7 @@ A connector can be of two types: **organization** or **app**, to fetch data from 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 @@ -58,9 +59,10 @@ You can now import it: import connect from '@aragon/connect' ``` -If you want to interact with the Voting or the Tokens app, you should also install their respective connectors: +If you want to interact with the Finance, Voting or the Tokens app, you should also install their respective connectors: ```text +yarn add @aragon/connect-finance yarn add @aragon/connect-voting yarn add @aragon/connect-tokens ``` @@ -121,7 +123,7 @@ 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: ```javascript -import { connect } from '@aragon/connect' +import connect from '@aragon/connect' const org = await connect('example.aragonid.eth', 'thegraph') @@ -168,11 +170,10 @@ Generating a transaction is done in three steps. First, call a method returning const intent = await org.appIntent(voting, 'vote', [votes[0].id, true, true]) ``` -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 all possible paths: +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: ```javascript -// The first path is the shortest -const [path] = intent.paths(wallet.account) +const path = intent.paths(wallet.account) ``` 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](https://docs.ethers.io/v5/), [Web3.js](https://web3js.readthedocs.io/en/1.0/), or even a [JSON-RPC connection to an Ethereum node](https://eips.ethereum.org/EIPS/eip-1474).