Aragon website • Developer Portal • Join our Developer Community • Contribute
Aragon OSx SDK
Welcome to the Aragon OSx SDK!
The Aragon OSx SDK enables you to interact with the Aragon OSx product using pure JavaScript (with Typescript support).
Whether you're a developer building a custom DAO or your own dApp, the Aragon OSx SDK is your gateway to Aragon OSx' functionality. The Aragon OSx protocol is a secure and modular DAO framework for building custom organizations on-chain.
Within this repository, you will find the following JS packages available already on NPM for install:
- Client: The package you'll be mostly interacting with. It is the package containing all functions querying the Aragon OSx subgraph to fetch information about DAOs and call on certain plugins to perform actions.
- IPFS: This package provides a wrapper to send requests to an IPFS Cluster using the IPFS API. It supports standard requests as well as streamed requests, and is used under the hood to send requests by the other packages.
- Common: This package provides the general purpose
components to use across the entire Aragon SDK like the shared
interfaces
,constants
, etc.
Quick Start
The Aragon OSx SDK is Javascript agnostic, which means you can use it with any Javascript framework, including popular ones like NodeJS, Deno, React, Vite, or Vue. The examples in this README are written using NodeJS.
1. Initialize a new project
If you do not already have a project to work with, create a new one with npm (or your package manager of choice).
npm init
That will generate a package.json file for you to start running your Javascript project. Optionally you can also enable typescript.
npx tsc --init
2. Install the Aragon OSx SDK
Install the SDK and the ethers package. Note Aragon SDK uses ethers version5. Although version 6 may work, we suggest using the same version5 for compatibility:
npm install @aragon/sdk-client @ethers@5
3. Create an entry file
Create a new file index.ts
(or index.js
) and import ethers and the SDK. This
is where we will setup the SDK and call its functions.
import { Wallet } from "ethers";
import { Client, Context, ContextParams } from "@aragon/sdk-client";
const main = async () => {
// This is where we will config the SDK in our next step
};
main()
.then(() => process.exit(0))
.catch((error) => {
console.log(error);
process.exit(1);
});
4. Configure the SDK
In order to set up the configuration for the Aragon SDK, we want to create a "context" variable which will give us access to the web3 provider and signer handling the SDK transactions. In this example, we are using a random wallet since we are not sending any transactions. However this should ideally be the connected wallet.
const contextParams: ContextParams = {
network: "mainnet",
web3Providers: "https://rpc.ankr.com/eth",
signer: Wallet.createRandom(),
// Optional, but without it the client will not be able to resolve IPFS content
ipfsNodes: [
{
url: "https://testing-ipfs-0.aragon.network/api/v0",
headers: { "X-API-KEY": "b477RhECf8s8sdM7XrkLBs2wHc4kCMwpbcFC55Kt" },
},
],
};
const context: Context = new Context(contextParams);
Next thing you'll want to do is set up the general purpose Client
so you can
call on the general purpose SDK functions. These are things like getDaos
,
getDaoBalances
, etc. This client is used to interact with any DAO on the
network you're connected to.
const client: Client = new Client(context);
5. Using the SDK
In order to test our SDK set up works, we will try fetching information a multisig DAO.
console.log(await client.methods.getDao("aa.dao.eth"));
Our final code should look like this:
import { Wallet } from "ethers";
import { Client, Context } from "@aragon/sdk-client";
const main = async () => {
const contextParams: ContextParams = {
network: "mainnet",
web3Providers: "https://rpc.ankr.com/eth",
signer: Wallet.createRandom(),
// Optional, but without it the client will not be able to resolve IPFS content
ipfsNodes: [
{
url: "https://testing-ipfs-0.aragon.network/api/v0",
headers: { "X-API-KEY": "b477RhECf8s8sdM7XrkLBs2wHc4kCMwpbcFC55Kt" },
},
],
};
const context: Context = new Context(contextParams);
const client: Client = new Client(context);
console.log(await client.methods.getDao("aa.dao.eth"));
};
main()
.then(() => process.exit(0))
.catch((error) => {
console.log(error);
process.exit(1);
});
In order to run the program and get the information details on the aa.dao.eth DAO, go to the terminal and run:
node index.ts
{
address: '0xec10f0f223e52f2d939c7372b62ef2f55173282f',
ensDomain: 'aa.dao.eth',
metadata: {
name: 'AA Multisig',
description: 'This is Aragon Association budget vault on the new aragonOSx stack. ',
avatar: 'ipfs://QmT8PDLFQDWaAUoKw4BYziWQNVKChJY3CGi5eNpECi7ufD',
links: [ [Object] ]
},
creationDate: 2023-06-07T07:41:23.000Z,
plugins: [
{
instanceAddress: '0xa2dee0b38d2cfadeb52f2b5a738b5ea7e037dce9',
id: 'multisig.plugin.dao.eth',
release: 1,
build: 1
}
]
}
For additional information on the SDK capabilities, make sure you check out Aragon's Developer Portal for more information.
Available scripts
yarn build
- Compiles all the modules, respecting their internal dependencies
yarn clean
- Removes the existing artifacts
yarn lint
- Checks the current code for inconsistencies
yarn test
- Runs the test suite on all modules
Development
Run yarn build
to compile the individual packages. Run yarn test
on them.
Automatic publishing
With labels
To automatically publish the new version on pull request merge, the relevant labels:
Label Name | Component getting published | NPM package name |
---|---|---|
client-release | modules/client/ |
@aragon/sdk-client |
ipfs-release | modules/ipfs/ |
@aragon/sdk-ipfs |
common-release | modules/common/ |
@aragon/sdk-common |
With tags
To publish a new version of a subpackage create a new git tag following this
schema:
VERSION-LANGUAGE-PACKAGE_FOLDER_NAME
- Example to publish a new version of the javascript client module:
0.0.1-javascript-client
. - To publish an alpha version just put
-alpha
behind the semver:0.0.1-alpha-javascript-client
Important:
Do not run 2 workflows at the same time, otherwise we could encounter a race condition in the git repo which could lead to a failure of the automatic changelog and package.json update
Security
If you believe you've found a security issue, we encourage you to notify us. We welcome working with you to resolve the issue promptly.
Security Contact Email: sirt@aragon.org
Please do not use the issue tracker for security issues.