ArConnect

ArConnect is a browser extension allowing Arweave wallet holders to interact with dApps securely and easily.

API

You can interact with basic ArConnect functionalities using arweave-js. To create a transaction, you just don't pass in the user's wallet instance:

const tx = await arweave.createTransaction({
  /* config */
});

Than, you can use ArConnect to add the users wallet to the transaction and sign it (as before, you don't pass in the user's wallet instance, that is done by ArConnect):

await arweave.transactions.sign(tx);

Done! Now you can post the transaction.

Events

ArConnect has some useful custom events.

`arweaveWalletLoaded`

Triggers when the ArConnect global object (window.arweaveWallet) is injected into the page. It can be useful when executing functions on page load.

window.addEventListener("arweaveWalletLoaded", () => {
  /** Handle ArConnect load event **/
});

`walletSwitch`

Triggers, when the user switches their wallet in the ArConnect extension popup.

window.addEventListener("walletSwitch", (e) => {
  const newAddress = e.detail.address;
  /** Handle wallet switch **/
});

Requires the ACCESS_ADDRESS and the ACCESS_ALL_ADDRESSES permissions.

Other supported functions

ArConnect supports much more with it's powerful API. These features are not integrated into arweave-js right now, but please let us know if you would like to see them added or not. You can access all of these using the global window.arweaveWallet object (window.arweaveWallet.getActiveAddress(), etc.).

All of these functions are asynchronous, so you will need to await them. If you are using Typescript, read this for type declarations.

`connect(permissions, appInfo?, gateway?)`

Connect to ArConnect and request permissions. This function can always be called again if you want to request more permissions for your site. See the available permissions here.

permissions: An array of permissions
appInfo: Optional information about your application (see the format)
gateway: Optional gateway configuration (see the format)

App info

{
  name?: string; // optional application name
  logo?: string; // optional application logo
}

Gateway config

{
  host: string;
  port: number;
  protocol: "http" | "https";
}

`disconnect()`

Disconnect from ArConnect. Removes all permissions from your site.

`getActiveAddress(): Promise<string>`

Get the currently used wallet's address in the extension.

returns: A wallet address

Requires the ACCESS_ADDRESS permission.

`getActivePublicKey(): Promise<string>`

Get the user's active public key, from their wallet

returns: The active public key

Requires the ACCESS_PUBLIC_KEY permission.

`getAllAddresses(): Promise<string[]>`

Get all addresses added to the ArConnect extension

returns: A list of the added wallets' addresses.

Requires the ACCESS_ALL_ADDRESSES permission.

`getWalletNames(): Promise<{ [addr: string]: string }>`

Get wallet names for addresses.

returns: An object with addresses and wallet names

Requires the ACCESS_ALL_ADDRESSES permission.

`sign(transaction, options?): Promise<Transaction>`

Sign a transaction. Raw version of what is used in the arweave-js API.

transaction: A valid Arweave transaction without a wallet keyfile added to it
options: Arweave signing options
returns: Signed transaction instance

Requires the SIGN_TRANSACTION permission.

Note: if you are trying to sign a larger chunk of data (5 MB <), make sure to notify the user to not switch / close browser tabs. Signing large datas takes longer and the browser won't send the chunks to the signer in the background.

`dispatch(transaction): Promise<DispatchResult>`

Dispatches (signs and sends) a transaction to the network, preferably by bundling it. Best for smaller interactions (< 120 Kbs).

transaction: A valid Arweave transaction without a wallet keyfile added to it
returns: Dispatch result (id and submit type)

Requires the DISPATCH permission.

`encrypt(data, options): Promise<Uint8Array>`

Encrypt a string with the user's wallet.

data: String to encrypt
options: Encrypt options
returns: Encrypted string

Requires the ENCRYPT permission.

Encryption options

{
  algorithm: string; // encryption algorithm
  hash: string; // encryption hash
  salt?: string; // optional salt
}

`decrypt(data, options): Promise<string>`

Decrypt a string encrypted with the user's wallet.

data: Uint8Array data to decrypt to a string
options: Decrypt options
returns: Decrypted string

Requires the DECRYPT permission.

`signature(data, options): Promise<Uint8Array>`

Get the signature for a data array.

data: Uint8Array data to get the signature for
options: Signature options
returns: Signature

Requires the SIGNATURE permission.

`getPermissions(): Promise<PermissionType[]>`

Get the permissions allowed for you site by the user.

returns: A list of permissions allowed for your dApp.

`getArweaveConfig(): Promise<ArweaveConfig>`

Get the user's custom Arweave config set in the extension

returns: Custom Arweave config

Requires the ACCESS_ARWEAVE_CONFIG permission.

Permissions

There are 8 permissions currently available. When calling connect, you need to specify at least one of them, commonly ACCESS_ADDRESS.

The permissions:

ACCESS_ADDRESS: Access the current address selected in ArConnect
ACCESS_PUBLIC_KEY Access the public key of the current address selected in ArConnect
ACCESS_ALL_ADDRESSES: Access all addresses added to ArConnect
SIGN_TRANSACTION: Sign a transaction
DISPATCH: Dispatch (sign and send) a transaction
ENCRYPT: Encrypt data with the user's keyfile
DECRYPT: Decrypt data with the user's keyfile
SIGNATURE Sign data with the user's keyfile
ACCESS_ARWEAVE_CONFIG: Access the user's custom Arweave config

Arweave config

The user can set a custom Arweave config in the extension. It implements the following format:

{
  host: string;
  port: number;
  protocol: "http" | "https";
}

Typescript types

To support ArConnect types, you can install the npm package arconnect, like this:

npm i -D arconnect

yarn add -D arconnect

To add the types to your project, you should either include the package in your tsconfig.json, or add the following to your env.d.ts file:

/// <reference types="arconnect" />

Type declarations can be found here.

Build project (Chrome, Firefox, Brave)

You can find the build guide here.

Contributing

Please read the Contributing guide.

License

Licensed under the MIT license.

marslab2022/ArConnect

ArConnect

API

Events

arweaveWalletLoaded

walletSwitch

Other supported functions

connect(permissions, appInfo?, gateway?)

App info

Gateway config

disconnect()

getActiveAddress(): Promise<string>

getActivePublicKey(): Promise<string>

getAllAddresses(): Promise<string[]>

getWalletNames(): Promise<{ [addr: string]: string }>

sign(transaction, options?): Promise<Transaction>

dispatch(transaction): Promise<DispatchResult>

encrypt(data, options): Promise<Uint8Array>