Usage

important

You can either use the API in Offline mode or in Online mode. See the initialise page. For online mode, you can get the AVN_GATEWAY_URL here.

User Mode

This SDK can be used in 2 modes as defined in the SetupMode enum:

• Single user mode (default): In this mode, the SDK acts as a single account wallet.
• Multi user mode: In this mode, multiple users can use the same instance of the SDK to interact with the Avn gateway.
• Offline mode: In this mode, the sdk will not expose any api's to interact with the avn parachain. It will only expose the account utility methods.

To set one of these mode, pass in the following options when creating an instance of the SDK

import { AvnApi, SetupMode } from "avn-api";

// The AvN gateway endpoint:
const AVN_GATEWAY_URL = "https://...";

const singleUserSdk = new AvnApi(AVN_GATEWAY_URL, {
	setupMode: SetupMode.SingleUser,
}); // OR
const multiUserSdk = new AvnApi(AVN_GATEWAY_URL, {
	setupMode: SetupMode.MultiUser,
}); // OR
const offlineSdk = new AvnApi({ setupMode: SetupMode.Offline });

Signing

There are 2 options to choose from when configuring the signing behaviour of the SDK:

• Suri-based signer (default): In this mode, the user must set their SURI either via an environment variable or as part of the options (see Accounts below). This SURI will be used to sign messages such as AWT tokens or transactions. This is only applicable in single user mode.

• Remote signer: In this mode, the caller will set a function that will be called by the SDK when it requires a signature. The SDK will not have access to the signer's SURI. This option can be selected for single user and multi user modes. Here's a guide for Single user mode and for Multi user mode on how to use Remote Signing.

important

Remote signer can be used with both the SingleUser and MultiUser modes.
Suri-based signer can only be used with the SingleUser mode.

To set one of these mode, pass in the following options when creating an instance of the sdk

import { AvnApi, SigningMode } from "avn-api";

// The AvN gateway endpoint:
const AVN_GATEWAY_URL = "https://...";

const suriBasedSdk = new AvnApi(AVN_GATEWAY_URL, {
	signingMode: SigningMode.SuriBased,
}); // OR
const remoteSignerSdk = new AvnApi(AVN_GATEWAY_URL, {
	signingMode: SigningMode.RemoteSigner,
});

Nonce Caching

Part of the sdk functionality is to send transactions via the AvN gateway to the AvN parachain. These transactions require various nonces to be specified to ensure they are safe from replay attacks. This SDK supports 2 types of nonce caching:

• Local cache (default): this is an in-memory cache attached to the single instance of the sdk. This setup is not recommended if there are multiple instances of the SDK processing the same user requests. Example: a multi pod setup running multiple backends for the same frontend application.
• Remote cache: this allows the user to specify a remote cache via an INonceCacheProvider interface enabling multiple separate instances of the SDK to access the same nonce storage. If this mode is selected, a cacheProvider must be specified in the options. Please see this provider to get started on how to implement one.

important

There's a GUIDE HERE with an example test script on how to set up a remote cache.

To set one of these modes, pass in the following options when creating an instance of the SDK

import { AvnApi, NonceCacheType } from "avn-api";

// The AvN gateway endpoint:
const AVN_GATEWAY_URL = "https://...";

const localNonceCacheSdk = new AvnApi(AVN_GATEWAY_URL, {
	nonceCacheType: NonceCacheType.Local,
}); // OR

const remoteNonceCacheSdk = new AvnApi(AVN_GATEWAY_URL, {
	nonceCacheType: NonceCacheType.Remote,
	cacheProvider: testCacheProvider,
});

Log Level

Depending on how detailed you would like the logs, you can set the default log level to any of this options (info, debug, trace, error) using the format below:

options.defaultLogLevel = 'info'

Multi-Currency Payment

The AvN Gateway allows for the use of multiple tokens as payment, with the number of supported tokens being configurable. To select a specific token for payment, include its address in the SDK's options object. If no token is provided, the SDK will default to using the chain's native token.

When submitting a transaction directly to the AvN Gateway (without using this SDK), the token address is optional for split-fee transactions. For self-pay transactions, the token must be included in the PaymentSignature you generate.

To specify a token in the options object, use the following approach:

import { AvnApi, SigningMode } from "avn-api";

const sdk = new AvnApi({
	suri: "0x816...",
	relayer: relayer,
	paymentCurrencyToken: "0x123...",
});

Default Values

Now that we understand how the User Mode, Signing, and Nonce Caching can be set, it's important to know what the default values are if nothing is passed in.

// If no setup mode is defined, it defaults to singleUser mode.
options.setupMode = options.setupMode || SetupMode.SingleUser;

// If no setup mode is defined, it defaults to the suriBased signing mode.
options.signingMode = options.signingMode || SigningMode.SuriBased;

// If no Log level is defined, it defaults to the info mode.
options.defaultLogLevel = options.defaultLogLevel || "info";

if (!options.nonceCacheOptions) {
	options.nonceCacheOptions = {
		// If no nonce cache type is defined, it defaults to Local mode.
		nonceCacheType: NonceCacheType.Local,
	};
}