firstfan / arconnect

🦔 Secure wallet management for Arweave

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, algorithm): Promise<Uint8Array>

Encrypt data with the user's wallet. This is an implementation of the webcrypto encrypt API.

• data: BufferSource to encrypt
• algorithm: Encrypt algorithm
  
• returns: Encrypted data

Requires the ENCRYPT permission.

decrypt(data, options): Promise<string>

Decrypt data with the user's wallet. This is an implementation of the webcrypto decrypt API.

• data: BufferSource data to decrypt
• algorithm: Decrypt algorithm
  
• returns: Decrypted data

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.

addToken(id, type?, gateway?)

Add a token to the user's wallet (ArConnect). The token will show up in ArConnect assets / collectibles.

Note: You do not need to be connected in order to add a token

• id: ID of the token to add
• type: Optional token type (asset or collectible)
• gateway: Optional gateway to fetch the token from (see the format)

Warning: If the gateway is defined, ArConnect will not use the default Warp Mainnet Gateway, but the custom one. This might slow down evaluation!

isTokenAdded(id)

Check if a token has been added to the user's wallet (ArConnect).

• id: ID of the token to add
  
• returns: Boolean value indicating if the token has been added or not.

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

or

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.