# Wanchain connectors

# HTTP provider

HTTP provider uses HTTP and HTTPS protocol for communication with the Wanchain node. It is used mostly for querying and mutating data but does not support subscriptions.

# Installation

We recommend you employ the asset ledger module as an NPM package in your application.

$ npm i --save @0xcert/wanchain-http-provider

On our official GitHub repository, we also host a compiled and minimized JavaScript file that you can directly include in your website. Please refer to the API section to learn more about asset ledger.

# HttpProvider(options)

A class providing communication with the Wanchain blockchain using the HTTP/HTTPS protocol.

Arguments

Usage

import { HttpProvider } from '@0xcert/wanchain-http-provider';

const provider = new HttpProvider({
    accountId: '0x...',
    url: 'https://connection-to-wanchain-rpc-node/',
});

# assetLedgerSource

A class instance variable holding a string which represents the URL to the compiled ERC-721-related smart contract definition file. This file is used when deploying new asset ledgers to the network.

# buildGatewayConfig(networkKind)

A function that returns the current gateway config based on the deployed gateway smart contracts. Note that config will change based on release versions. If you do not want the smart contract addresses to update automatically, you should not use this function.

# gatewayConfig

A class instance variable holding a GatewayConfig which represents the configuration for Gateway smart contracts.

Arguments

# getAvailableAccounts()

An asynchronous class instance function which returns currently available Wanchain wallet addresses.

Result:

A list of strings representing Wanchain account IDs.

Example:

// perform query
const accountIds = await provider.getAvailableAccounts();

# getInstance(options)

A static class function which returns a new instance of the HttpProvider class (alias for new HttpProvider).

Arguments

See the class constructor for details.

Usage

import { HttpProvider } from '@0xcert/wanchain-http-provider';

// create provider instance
const provider = HttpProvider.getInstance();

# getNetworkVersion()

An asynchronous class instance function which returns the Wanchain network version (e.g., 1 for Wanchain Mainnet).

Result:

A string representing the Wanchain network version.

Example:

// perform query
const version = await provider.getNetworkVersion();

# isCurrentAccount(accountId)

A synchronous class instance function which returns true when the provided accountId matches the currently set account ID.

Arguments:

Result:

A boolean which tells whether the accountId matches the currently set account ID.

Example:

// wanchain wallet address
const walletId = '0x...';

// perform query
const matches = provider.isCurrentAccount(walletId);

# isSupported()

A synchronous class instance function which returns true when the provider is supported by the environment.

Result:

A boolean which tells whether the provider can be used.

Example:

// perform query
const isSupported = provider.isSupported();

# isUnsafeRecipientId(ledgerId)

A synchronous class instance function which returns true when the provided ledgerId is listed among unsafe recipient IDs on the provider.

Arguments:

Result:

A boolean which tells whether the id is an unsafe recipient.

Example:

// unsafe recipient address
const unsafeId = '0x...';

// perform query
const isUnsafe = provider.isUnsafeRecipientId(unsafeId);

See also:

unsafeRecipientIds

# log(message)

A synchronous class instance function which logs message to console if verbose mode is active, otherwise it does nothing.

Example:

provider.log('message');

# mutationTimeout

A class instance variable holding an integer number of milliseconds after which a mutation times out.

# on(event, handler);

A synchronous class instance function which attaches a new event handler.

Arguments:

Result:

An instance of the same provider class.

Example:

import { ProviderEvent } from '@0xcert/wanchain-http-provider';

provider.on(ProviderEvent.ACCOUNT_CHANGE, (accountId) => {
  console.log('Account has changed', accountId);
});

See also:

once (event, handler), off (event, handler)

# once(event, handler);

A synchronous class instance function which attaches a new event handler. The event is automatically removed once the first event is emitted.

Arguments:

Result:

An instance of the same provider class.

Example:

import { ProviderEvent } from '@0xcert/wanchain-http-provider';

provider.on(ProviderEvent.ACCOUNT_CHANGE, (accountId) => {
  console.log('Account has changed', accountId);
});

See also:

on (event, handler), off (event, handler)

# off(event, handler)

A synchronous class instance function which removes an existing event handler.

Arguments:

Result:

An instance of the same provider class.

Example:

import { ProviderEvent } from '@0xcert/wanchain-http-provider';

provider.off(ProviderEvent.NETWORK_CHANGE);

See also:

on (event, handler), once (event, handler)

# requiredConfirmations

A class instance variable holding a string which represents the number of confirmations needed for mutations to be considered confirmed. It defaults to 1.

# retryGasPriceMultiplier

A class instance variable holding a number representing a multiplier of the current gas price when performing a retry action on mutation.

# sandbox

A class instance variable holding a boolean indicating whether you are in sandbox mode. Sandbox mode means you don't make an actual mutation to the blockchain, but you only check whether a mutation would succeed or not.

# sign(message)

An asynchronous class instance function which signs a message using signMethod set in provider.

Arguments:

Result:

A string representing the signature.

Example:

const signature = await provider.sign('test');

# signMethod

A class instance variable holding a string which holds a type of signature that will be used (e.g., when creating claims).

# unsafeRecipientIds

A class instance variable holding a string which represents smart contract addresses that do not support safe ERC-721 transfers.

# valueLedgerSource

A class instance variable holding a string which represents the URL to the compiled ERC-20-related smart contract definition file. This file is used when deploying new value ledgers to the network.

# verbose

A class instance variable holding a boolean which represents whether you are in verbose mode. Verbose mode means the console will provide more detailed information about the current state. It defaults to false.

# Provider events

We can listen to different provider events. Note that not all the providers are able to emit all the events listed here.

Options:

Example:

provider.on(ProviderEvent.ACCOUNT_CHANGE, (accountId) => {
    console.log('Account has changed', accountId);
});
provider.on(ProviderEvent.NETWORK_CHANGE, (networkVersion) => {
    console.log('Network has changed', networkVersion);
});

# Mutation

The 0xcert Framework performs mutations for any request that changes the state on the Wanchain blockchain.

# Mutation(provider, mutationId, context?)

A class which handles transaction-related operations on the Wanchain blockchain.

Arguments

Usage

import { Mutation } from '@0xcert/wanchain-http-provider';

// arbitrary data
const mutationId = '0x...';

// create mutation instance
const mutation = new Mutation(provider, mutationId);

# cancel()

An asynchronous class instance function which attempts to cancel a mutation. You can only cancel a mutation that has not yet been accepted onto the blockchain. Canceling works by overwriting a pending mutation (using the same nonce) with a new mutation that performs no action, which could also lead the cancel function to fail. The cancel function will throw an error if the mutation has already been accepted onto the blockchain or if you are not the originator of the mutation you want to cancel.

# complete()

An asynchronous class instance function which waits until a mutation reaches a specified number of confirmations.

Result:

An instance of the same mutation class.

Example:

// wait until confirmed
await mutation.complete();

See also:

forget()

# confirmations

A class instance variable holding an integer number of confirmations reached. Default is 0.

# emit(event, options);

A synchronous class instance function to manually trigger a mutation event.

Arguments:

Result:

An instance of the same mutation class.

Example:

import { MutationEvent } from '@0xcert/wanchain-http-provider';

mutation.emit(MutationEvent.ERROR, new Error('Unhandled error'));

# forget()

A synchronous class instance function which stops listening for confirmations which causes the complete() function to resolve immediately.

Result:

An instance of the same mutation class.

Example:

mutation.forget();

# id

A class instance variable holding a string which represents a hash of a Wanchain transaction.

# isCompleted()

A synchronous class instance function which returns true if a mutation has reached the required number of confirmations.

Result:

A boolean telling whether the mutation has been completed.

Example:

mutation.isCompleted();

See also:

isPending

# isPending()

A synchronous class instance function which returns true when a mutation is in the process of completion.

Result:

A boolean telling whether the mutation is waiting to be confirmed.

Example:

mutation.isPending();

See also:

isPending

# logs

A class instance variable holding an array of logs. It only resolves if you called either complete() or resolve() function upon Mutation and if the Mutation context is set. Logs are dynamically defined and represent Events that were triggered by the smart contract.

# on(event, handler);

A synchronous class instance function which attaches a new event handler.

Arguments:

Result:

An instance of the same mutation class.

Example:

import { MutationEvent } from '@0xcert/wanchain-http-provider';

mutation.on(MutationEvent.COMPLETE, () => {
    console.log('Mutation has been completed!');
});

See also:

once(event, handler), off (event, handler)

# once(event, handler);

A synchronous class instance function which attaches a new event handler. The event is automatically removed once the first event is emitted.

Arguments:

Result:

An instance of the same mutation class.

Example:

import { MutationEvent } from '@0xcert/wanchain-http-provider';

mutation.once(MutationEvent.COMPLETE, () => {
    console.log('Mutation has been completed!');
});

See also:

on (event, handler), off (event, handler)

# off(event, handler)

A synchronous class instance function which removes an existing event.

Arguments:

Result:

An instance of the same mutation class.

Example:

import { MutationEvent } from '@0xcert/wanchain-http-provider';

mutation.off(MutationEvent.ERROR);

See also:

on (event, handler), once (event, handler)

# receiverId

A class instance variable holding a string which represents a Wanchain account address that plays the role of a receiver.

# retry()

An asynchronous class instance function which resubmits the same mutation to the blockchain at a higher price. Since the speed of accepting mutations onto the blockchain depends on the current network state, a mutation could remain unconfirmed for a while. In that case, you can retry submitting the same mutation at an increased price to speed up its acceptance onto the blockchain. The price is determined by the current network price, multiplied by the retryGasPriceMultiplier parameter on the provider (which defaults to 2). Note that this method will throw an error if the mutation has already been accepted onto the blockchain.

# resolve()

An asynchronous class instance function which resolves the current mutation status.

# senderId

A class instance variable holding a string which represents a Wanchain account address that plays the role of a sender.

# Mutation events

We can listen to different mutation events that are emitted by the mutation in the process of completion.

Options:

Example:

mutation.on(MutationEvent.COMPLETE, () => {
    console.log('Mutation has been completed!');
});

# Asset ledger

Asset ledger represents ERC-721-related smart contract on the Wanchain blockchain.

# Installation

We recommend you employ the asset ledger module as an NPM package in your application.

$ npm i --save @0xcert/wanchain-asset-ledger

On our official GitHub repository, we also host a compiled and minimized JavaScript file that you can directly include in your website. Please refer to the API section to learn more about asset ledger.

# AssetLedger(provider, ledgerId)

A class which represents a smart contract on the Wanchain blockchain.

Arguments:

Example:

import { HttpProvider } from '@0xcert/wanchain-http-provider';
import { AssetLedger } from '@0xcert/wanchain-asset-ledger';

// arbitrary data
const provider = new HttpProvider({ url: 'https://...' });
const ledgerId = '0x...';

// create ledger instance
const ledger = new AssetLedger(provider, ledgerId);

# approveAccount(assetId, accountId)

An asynchronous class instance function which approves a third-party accountId to take over a specific assetId. This function succeeds only when performed by the asset's owner.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const assetId = '100';
const accountId = '0x...';

// perform mutation
const mutation = await ledger.approveAccount(assetId, accountId);

See also:

disapproveAccount, approveOperator

# approveOperator(accountId)

An asynchronous class instance function which approves the third-party accountId to take over the management of all the assets of the account that performed this mutation.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const assetId = '100';
const accountId = '0x...';

// perform mutation
const mutation = await ledger.approveOperator(accountId);

See also:

disapproveOperator, approveAccount

# createAsset(recipe)

An asynchronous class instance function which creates a new asset on the Wanchain blockchain.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const asset = {
    id: '100',
    imprint: 'd747e6ffd1aa3f83efef2931e3cc22c653ea97a32c1ee7289e4966b6964ecdfb',
    receiverId: '0x...',
};

// perform mutation
const mutation = await ledger.createAsset(asset);

See also:

Cert

# deploy(provider, recipe)

An asynchronous static class function which deploys a new asset ledger to the Wanchain blockchain.

Arguments:

Result:

An instance of the same mutation class.

Example:

import { HttpProvider } from '@0xcert/wanchain-http-provider';
import { AssetLedger, AssetLedgerCapability } from '@0xcert/wanchain-asset-ledger';

// arbitrary data
const provider = new HttpProvider({
    url: 'https://...',
    accountId: '0x...'
});
const capabilities = [
    AssetLedgerCapability.TOGGLE_TRANSFERS,
];
const recipe = {
    name: 'Math Course Certificate',
    symbol: 'MCC',
    uriPrefix: 'https://example.com/assets/',
    uriPostfix: '.json',
    schemaId: '3f4a0870cd6039e6c987b067b0d28de54efea17449175d7a8cd6ec10ab23cc5d', // base asset schemaId
    capabilities,
};

// perform mutation
const mutation = await AssetLedger.deploy(provider, recipe).then((mutation) => {
    return mutation.complete(); // wait until first confirmation
});

# destroyAsset(assetId)

An asynchronous class instance function which destroys a specific assetId on the Wanchain blockchain. The asset is removed from the account, and all queries about it will be invalid. The function succeeds only when performed by the asset's owner. This function is similar to revokeAsset, but it differs in who can trigger it.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const assetId = '100';

// perform mutation
const mutation = await ledger.destroyAsset(assetId);

See also:

revokeAsset

# disapproveAccount(assetId)

An asynchronous class instance function which removes the ability of the currently set third-party account to take over a specific assetId. This function succeeds only when performed by the asset's owner.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const assetId = '100';

// perform mutation
const mutation = await ledger.disapproveAccount(assetId);

See also:

disapproveOperator, approveAccount

# disapproveOperator(accountId)

An asynchronous class instance function which removes the third-party accountId the ability to manage assets of the account that performed this mutation.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const accountId = '0x...';

// perform mutation
const mutation = await ledger.disapproveOperator(accountId);

See also:

disapproveAccount, approveOperator

# disableTransfers()

An asynchronous class instance function which disables all asset transfers.

Result:

An instance of the same mutation class.

Example:

// perform mutation
const mutation = await ledger.disableTransfers();

See also:

enableTransfers

# enableTransfers()

An asynchronous class instance function which enables all asset transfers.

Result:

An instance of the same mutation class.

Example:

// perform mutation
const mutation = await ledger.enableTransfers();

See also:

disableTransfers

# getAbilities(accountId)

An asynchronous class instance function which returns accountId abilities.

Arguments:

Result:

An array of integer numbers representing account abilities.

Example:

// arbitrary data
const accountId = '0x...';

// perform query
const abilities = await ledger.getAbilities(accountId);

# getAccountAssetIdAt(accountId, index)

An asynchronous class instance function which returns the asset ID at specified index for desired accountId.

Arguments:

Result:

A number representing the asset ID.

Example:

// arbitrary data
const accountId = '0x...';
const index = 0; // the account has 3 tokens on indexes 0, 1 and 2

// perform query
const assetId = await ledger.getAccountAssetIdAt(accountId, index);

# getApprovedAccount(assetId)

An asynchronous class instance function which returns an account ID of a third party which is able to take over a specific assetId.

Arguments:

Result:

A string representing account ID.

Example:

// arbitrary data
const assetId = '100';

// perform query
const accountId = await ledger.getApprovedAccount(assetId);

See also:

approveAccount

# getAsset(assetId)

An asynchronous class instance function which returns assetId data.

Arguments:

Result:

Example:

// arbitrary data
const assetId = '100';

// perform query
const data = await ledger.getAsset(assetId);

# getAssetAccount(assetId)

An asynchronous class instance function which returns an account ID that owns the assetId.

Arguments:

Result:

A string which represents an account ID.

Example:

// arbitrary data
const assetId = '100';

// perform query
const accountId = await ledger.getAssetAccount(assetId);

# getAssetIdAt(index)

An asynchronous class instance function which returns the asset ID at specified index.

Arguments:

Result:

A number representing the asset ID.

Example:

// arbitrary data
const index = 0; // the contract holds 100 tokens on indexes 0 to 99

// perform query
const assetId = await ledger.getAssetIdAt(index);

# getBalance(accountId)

An asynchronous class instance function which returns the number of assets owned by accountId.

Arguments:

Result:

An integer number representing the number of assets in the accountId.

Example:

// arbitrary data
const accountId = '0x...';

// perform query
const balance = await ledger.getBalance(accountId);

# getCapabilities()

An asynchronous class instance function which returns ledger's capabilities.

Result:

An array of integer numbers representing ledger capabilities.

Example:

// perform query
const capabilities = await ledger.getCapabilities();

# getInfo()

An asynchronous class instance function which returns an object with general information about the ledger.

Result:

Example:

// perform query
const info = await ledger.getInfo();

# getInstance(provider, ledgerId)

A static class function that returns a new instance of the AssetLedger class (alias for new AssetLedger).

Arguments:

See the class constructor for details.

Example:

import { HttpProvider } from '@0xcert/wanchain-http-provider';
import { AssetLedger } from '@0xcert/wanchain-asset-ledger';

// arbitrary data
const provider = new HttpProvider({ url: 'https://...' });
const ledgerId = '0x...';

// create ledger instance
const ledger = AssetLedger.getInstance(provider, ledgerId);

# id

A class instance variable holding the address of ledger's smart contract on the Wanchain blockchain.

# grantAbilities(accountId, abilities)

An asynchronous class instance function which grants management permissions for this ledger to a third party accountId.

Arguments:

Result:

An instance of the same mutation class.

Example:

import { GeneralAssetLedgerAbility } from '@0xcert/wanchain-asset-ledger';

// arbitrary data
const accountId = '0x...';
const abilities = [
    GeneralAssetLedgerAbility.CREATE_ASSET,
    GeneralAssetLedgerAbility.TOGGLE_TRANSFERS,
];

// perform mutation
const mutation = await ledger.grantAbilities(accountId, abilities);

See also:

Ledger abilities revokeAbilities

# isApprovedAccount(assetId, accountId)

An asynchronous class instance function which returns true when the accountId has the ability to take over the assetId.

Arguments:

Result:

A boolean which tells whether the accountId is approved for assetId.

Example:

// arbitrary data
const accountId = '0x...';
const assetId = '100';

// perform query
const isApproved = await ledger.isApprovedAccount(assetId, accountId);

See also:

isApprovedOperator, approveAccount

# isApprovedOperator(accountId, operatorId)

An asynchronous class instance function which returns true when the accountId has the ability to manage any asset of the accountId.

Arguments:

Result:

A boolean which tells whether the operatorId can manage assets of accountId.

Example:

// arbitrary data
const accountId = '0x...';
const operatorId = '0x...';

// perform query
const isOperator = await ledger.isApprovedOperator(accountId, operatorId);

See also:

isApprovedAccount, approveAccount

# isTransferable()

An asynchronous class instance function which returns true if the asset transfer feature on this ledger is enabled.

Result:

A boolean which tells whether ledger asset transfers are enabled.

Example:

// perform query
const isTransferable = await ledger.isTransferable();

See also:

enableTransfers

# revokeAbilities(accountId, abilities)

An asynchronous class instance function which removes abilities of an accountId.

Arguments:

Result:

An instance of the same mutation class.

Example:

import { GeneralAssetLedgerAbility } from '@0xcert/wanchain-asset-ledger';

// arbitrary data
const accountId = '0x...';
const abilities = [
    GeneralAssetLedgerAbility.CREATE_ASSET,
    GeneralAssetLedgerAbility.TOGGLE_TRANSFERS,
];

// perform mutation
const mutation = await ledger.revokeAbilities(accountId, abilities);

See also:

Ledger abilities grantAbilities

# revokeAsset(assetId)

An asynchronous class instance function which destroys a specific assetId of an account. The asset is removed from the account and all queries about it will be invalid. The function is meant to be used by ledger owners to destroy assets of other accounts. This function is similar to destroyAsset, but it differs in who can trigger it.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const assetId = '100';

// perform mutation
const mutation = await ledger.revokeAsset(assetId);

See also:

destroyAsset

# setAbilities(accountId, abilities)

An asynchronous class instance function which sets abilities of an accountId.

Arguments:

Result:

An instance of the same mutation class.

Example:

import { GeneralAssetLedgerAbility } from '@0xcert/wanchain-asset-ledger';

// arbitrary data
const accountId = '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce';
const abilities = [
    GeneralAssetLedgerAbility.CREATE_ASSET,
    GeneralAssetLedgerAbility.TOGGLE_TRANSFERS,
];

// perform mutation
const mutation = await ledger.setAbilities(accountId, abilities);

See also:

Ledger abilities grantAbilities revokeAbilities

# update(recipe)

An asynchronous class instance function which updates ledger data.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const recipe = {
    uriPrefix: 'https://example.com/',
    uriPostfix: '.json',
};

// perform mutation
const mutation = await ledger.update(recipe);

See also:

updateAsset

# updateAsset(assetId, recipe)

An asynchronous class instance function which updates assetId data.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const assetId = '100';
const recipe = {
    imprint: 'd747e6ffd1aa3f83efef2931e3cc22c653ea97a32c1ee7289e4966b6964ecdfb',
};

// perform mutation
const mutation = await ledger.updateAsset(assetId, recipe);

See also:

update

# transferAsset(recipe)

An asynchronous class instance function which transfers an asset to another account.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const recipe = {
    receiverId: '0x...',
    id: '100',
};

// perform mutation
const mutation = await ledger.transferAsset(recipe);

# Ledger abilities

Ledger abilities represent account-level permissions. For optimization reasons, the abilities are managed as bitfields, and for that reason, enums are values of 2^n. There are two categories of abilities, general and super. General abilities are abilities that can not change other account's abilities, whereas super abilities can. This categorization is for safety purposes since revoking your own super ability can lead to unintentional loss of control.

Super abilities options:

General abilities options:

Example:

import { GeneralAssetLedgerAbility } from '@0xcert/wanchain-asset-ledger';
import { SuperAssetLedgerAbility } from '@0xcert/wanchain-asset-ledger';

const abilities = [
    SuperAssetLedgerAbility.MANAGE_ABILITIES,
    GeneralAssetLedgerAbility.TOGGLE_TRANSFERS,
];

See also:

grantAbilities revokeAbilities

# Ledger capabilities

Ledger capabilities represent the features of a smart contract.

Options:

Example:

import { AssetLedgerCapability } from '@0xcert/wanchain-asset-ledger';

const capabilities = [
    AssetLedgerCapability.TOGGLE_TRANSFERS,
];

# Value ledger

Value ledger represents an ERC-20-related smart contract on the Wanchain blockchain.

# Installation

We recommend you employ the asset ledger module as an NPM package in your application.

$ npm i --save @0xcert/wanchain-value-ledger

On our official GitHub repository, we also host a compiled and minimized JavaScript file that you can directly include in your website. Please refer to the API section to learn more about asset ledger.

# ValueLedger(provider, ledgerId)

A class which represents a smart contract on the Wanchain blockchain.

Arguments:

Example:

import { HttpProvider } from '@0xcert/wanchain-http-provider';
import { ValueLedger } from '@0xcert/wanchain-value-ledger';

// arbitrary data
const provider = new HttpProvider({ url: 'https://...' });
const ledgerId = '0x...';

// create ledger instance
const ledger = new ValueLedger(provider, ledgerId);

# approveValue(value, accountId)

An asynchronous class instance function which approves a third-party accountId to transfer a specific value. This function succeeds only when performed by the asset's owner. Multiple accounts can be approved for different values at the same time.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const value = '1000000000000000000'; // 1 unit (18 decimals)
const accountId = '0x...';

// perform mutation
const mutation = await ledger.approveValue(value, accountId);

See also:

disapproveValue

# deploy(provider, recipe)

An asynchronous static class function which deploys a new value ledger to the Wanchain blockchain.

Arguments:

Result:

An instance of the same mutation class.

Example:

import { HttpProvider } from '@0xcert/wanchain-http-provider';
import { ValueLedger } from '@0xcert/wanchain-value-ledger';

// arbitrary data
const provider = new HttpProvider({
    url: 'https://...',
    accountId: '0x...'
});
const recipe = {
    name: 'Utility token',
    symbol: 'UCC',
    decimal: '18',
    supply: '500000000000000000000', // 500 mio
};

// perform mutation
const mutation = await ValueLedger.deploy(provider, recipe).then((mutation) => {
    return mutation.complete(); // wait until first confirmation
});

# disapproveValue(accountId)

An asynchronous class instance function which removes the ability of a third-party account to transfer value. Note that this function succeeds only when performed by the value owner.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const accountId = '0x...';

// perform mutation
const mutation = await ledger.disapproveValue(accountId);

See also:

approveValue

# getApprovedValue(accountId, spenderId)

An asynchronous class instance function which returns the approved value that the spenderId is able to transfer for accountId.

Arguments:

Result:

A big number string representing the approved value.

Example:

// arbitrary data
const accountId = '0x...';
const spenderId = '0x...';

// perform query
const value = await ledger.getApprovedValue(accountId, spenderId);

See also:

approveValue

# getBalance(accountId)

An asynchronous class instance function which returns the total possessed amount of the accountId.

Arguments:

Result:

A big number string representing the total value of the accountId.

Example:

// arbitrary data
const accountId = '0x...';

// perform query
const balance = await ledger.getBalance(accountId);

# getInfo()

An asynchronous class instance function that returns an object with general information about the ledger.

Result:

Example:

// perform query
const info = await ledger.getInfo();

# getInstance(provider, id)

A static class function that returns a new instance of the ValueLedger class (alias for new ValueLedger).

Arguments

See the class constructor for details.

Usage

import { HttpProvider } from '@0xcert/wanchain-http-provider';
import { ValueLedger } from '@0xcert/wanchain-value-ledger';

// arbitrary data
const provider = new HttpProvider({ url: 'https://...' });
const ledgerId = '0x...';

// create ledger instance
const ledger = ValueLedger.getInstance(provider, ledgerId);

# id

A class instance variable holding the address of ledger's smart contract on the Wanchain blockchain.

# isApprovedValue(value, accountId, spenderId)

An asynchronous class instance function which returns true when the spenderId has the ability to transfer the value from an accountId.

Arguments:

Result:

A boolean which tells whether the spenderId is approved to move value from accountId.

Example:

// arbitrary data
const accountId = '0x...';
const spenderId = '0x...';
const value = '1000000000000000000';

// perform query
const isApproved = await ledger.isApprovedAccount(value, accountId, spenderId);

See also:

approveValue

# transferValue(recipe)

An asynchronous class instance function which transfers an asset to another account.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const recipe = {
    receiverId: '0x...',
    value: '1000000000000000000', // 1 unit (18 decimals)
};

// perform mutation
const mutation = await ledger.transferValue(recipe);

# Gateway

The Gateway allows for performing multiple actions in a single atomic swap. The gateway always operates with an order. There are different kinds of order, depending on the type of action you want to perform. We can separate orders into two groups based on their functionality and their flow. First, there are orders for deploying a new ValueLedger and AssetLedger. These two orders only perform the deployment of a new smart contract to the blockchain plus a transfer of ERC-20 tokens (value). They are primarily targeted to delegating a deployment to a third party. For example, if you want to deploy a new AssetLedger but you do not want to do that yourself, you can pay someone some ERC-20 tokens to perform that for you. These two orders have the following flow:

1. Maker (address creating an order) defines the order (defines who will be the owner of the newly deployed ledger, who will receive tokens, etc.).
2. Maker generates the order claim and signs it (sign function).
3. Maker approves value transfer if necessary.
4. Maker sends the order and signature to the taker (through arbitrary ways).
5. Taker performs the order.

In this case, the taker can also be defined as "anyone", meaning you can define an order saying basically, "I am willing to pay X tokens to anyone willing to create this ledger for me".

Order kinds that fit into this group are:

• DeployAssetLedgerOrder
• DeployValueLedgerOrder

Then, there are orders for performing actions on existing ledgers. These orders are really powerful, but this makes them more complicated, too. Unlike deploy orders that have a specific maker and taker, the actions order are more dynamic, allowing an X number of participants to join but who need to sign an order for it to be valid. That also means that we can have multiple participants performing actions in a single atomic order. Actions that can be performed are the following:

• Transfer asset
• Transfer value
• Create new asset
• Update existing asset imprint
• Destroy an asset
• Update account abilities

Since we have multiple participants in an order, there are four different ways to interact with it, resulting in four ActionsOrders differentiating only in the way participants interact with it, namely:

• FixedActionsOrder - All participants are known and set in the order. Only the last defined participant can peform the order, other participants have to provide signatures.
• SignedFixedActionsOrder - All participants are known and set in the order. All participants have to provide signatures. Any participant can perform the order.
• DynamicActionsOrder - The last participant can be unknown or "any". All defined participants have to provide signatures. Any participant can peform the order and automatically becomes the last participant.
• SignedDynamicActionsOrder - The last participant can be unknown or "any". All defined participants have to provide signatures, the last or "any" participant, as well. Any participant can perform the order.

Let's illustrate the above concepts through an example. Let's say we want to sell two CryptoKitties for 5.000 ZXC. To allow anyone to buy it, we would use a DynamicActionsOrder, since we do not need to set the receiverId of the CryptoKitties and neither the senderId of ZXC. This means that anyone that wants to perform the order will automatically become the empty recipient/sender with whom we will exchange the assets. If we use the same case, but this time, we want to sell our CryptoKitties to Bob for 5.000 ZXC, we will use FixedActionsOrder, so that we can specify the exact receiver. Now, let's say that Bob does not have any WAN and is unable to perform the order, but he has tons of ZXC tokens, and his friend Sara is willing to help him out. In this case, we can use a SignedFixedActionsOrder, so that Bob only needs to sign the order, and Sara can perform it. If he wanted to pay Sara some ZXC for doing this, he could specify this in the order.

Therefore, signed orders are perfect for third-party services providing order execution for someone else. This can come handy in a variety of dApps.

# Installation

We recommend you employ the package as an NPM package in your application.

$ npm i --save @0xcert/wanchain-http-provider

On our official GitHub repository, we also host a compiled and minimized JavaScript file that can be directly implemented into your website. Please refer to the API section to learn more about the value ledger.

# Gateway(provider, gatewayConfig?)

A class representing a smart contract on the Wanchain blockchain.

Arguments

Usage

import { HttpProvider, buildGatewayConfig } from '@0xcert/wanchain-http-provider';
import { Gateway } from '@0xcert/wanchain-gateway';

// arbitrary data
const provider = new HttpProvider();

// create ledger instance
const gateway = new Gateway(provider, buildGatewayConfig(NetworkType.ROPSTEN));

# cancel(order)

An asynchronous class instance function which marks the provided order as canceled. It prevents the order from being performed.

Arguments:

Result:

An instance of the same mutation class.

Example:

import { ActionsOrderActionKind } from '@0xcert/wanchain-gateway';

// arbitrary data
const order = {
    kind: OrderKind.FixedActionsOrder,
    signers: ['0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce', '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce'],
    actions: [
        {
            kind: ActionsOrderActionKind.TRANSFER_ASSET,
            ledgerId: '0xcc377f78e8821fb8d19f7e6240f44553ce3dbfce',
            senderId: '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce',
            receiverId: '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce',
            assetId: '100',
        },
    ],
    expiration: Date.now() + 60 * 60 * 24, // 1 day
    seed: 12345,
};

// perform mutation
const mutation = await gateway.cancel(order);

See also:

claim, perform

# config

A class instance variable holding the configuration of gateway smart contracts.

# getInstance(provider, gatewayConfig?)

A static class function that returns a new instance of the Gateway class (alias for new Gateway).

Arguments

See the class constructor for details.

Usage

import { HttpProvider, buildGatewayConfig } from '@0xcert/wanchain-http-provider';
import { Gateway } from '@0xcert/wanchain-gateway';

// arbitrary data
const provider = new HttpProvider();

// create gateway instance
const gateway = Gateway.getInstance(provider, buildGatewayConfig(NetworkType.ROPSTEN));

# getProxyAccountId(proxyKind, ledgerId?)

An asynchronous class instance function which gets the accountId of a desired proxy from the gateway smart contract infrastructure.

Arguments:

Result:

A string representing proxy accountId.

Example:

// perform query
const proxyAccountId = await gateway.getProxyAccountId(ProxyKind.CREATE_ASSET);

# hash(order)

An asynchronous class instance function which returns a hash of the provided order.

Arguments:

Result:

A string representing order hash.

Example:

// arbitrary data
const order = {
    kind: OrderKind.FixedActionsOrder,
    signers: ['0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce', '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce'],
    actions: [
        {
            kind: ActionsOrderActionKind.TRANSFER_ASSET,
            ledgerId: '0xcc377f78e8821fb8d19f7e6240f44553ce3dbfce',
            senderId: '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce',
            receiverId: '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce',
            assetId: '100',
        },
    ],
    expiration: Date.now() + 60 * 60 * 24, // 1 day
    seed: 12345,
};

// perform query
const hash = await gateway.hash(order);

# perform(order, signature)

An asynchronous class instance function which submits the order with a signature.

Arguments:

Result:

An instance of the same mutation class.

Example:

// arbitrary data
const order = {
    kind: OrderKind.FixedActionsOrder,
    signers: ['0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce', '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce'],
    actions: [
        {
            kind: ActionsOrderActionKind.TRANSFER_ASSET,
            ledgerId: '0xcc377f78e8821fb8d19f7e6240f44553ce3dbfce',
            senderId: '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce',
            receiverId: '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce',
            assetId: '100',
        },
    ],
    expiration: Date.now() + 60 * 60 * 24, // 1 day
    seed: 12345,
};

// perform mutation
const mutation = await gateway.perform(order, signature);

See also:

cancel

# sign(order)

An asynchronous class instance function which cryptographically signs the provided order and returns a signature.

Arguments:

Result:

A string representing order signature.

Example:

// arbitrary data
const order = {
    kind: OrderKind.FixedActionsOrder,
    signers: ['0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce', '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce'],
    actions: [
        {
            kind: ActionsOrderActionKind.TRANSFER_ASSET,
            ledgerId: '0xcc377f78e8821fb8d19f7e6240f44553ce3dbfce',
            senderId: '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce',
            receiverId: '0xcc567f78e8821fb8d19f7e6240f44553ce3dbfce',
            assetId: '100',
        },
    ],
    expiration: Date.now() + 60 * 60 * 24, // 1 day
    seed: 12345,
};

// perform query
const signature = await gateway.sign(order);

# Order kinds

Orders define what an atomic swap will do. There are three different order kinds with different use cases and definitions.

# Asset ledger deploy order

This order kind is used for delegating AssetLedger deploy.

# DynamicActionsOrder

This order kind can perform multiple operations such as value transfer, asset transfer, asset creation, asset update, setting user abilities, and destroying assets. All participants (signers) except for the last one are defined. This means that any participant with the order and signatures from other participants can perform the order and, by doing so, becomes the last "unknown" participant.

# FixedActionsOrder

This order kind can perform multiple operations such as value transfer, asset transfer, asset creation, asset update, setting user abilities, and destroying assets. All participants (signers) have to be known beforehand, and the last defined signer can peform the order (the last signer's signature is not needed since he is the one performing the order).

# SignedDynamicActionsOrder

This order kind can perform multiple operations such as value transfer, asset transfer, asset creation, asset update, setting user abilities, and destroying assets. All participants (signers) except for the last one are defined. This means that any participant can provide the last signature and, by doing so, becomes the last participant. Any participant with all the signatures is able to perform the order.

# SignedFixedActionsOrder

This order kind can perform multiple operations such as value transfer, asset transfer, asset creation, asset update, setting user abilities, and destroying assets. All participants (signers) have to be known beforehand, and any participant with all signatures provided can perform the order.

# Value ledger deploy order

This order kind is used for delegating ValueLedger deploy.

# ActionsOrder actions

ActionsOrder actions define the atomic operations of the actions order.

Options:

# DynamicActionsOrderActionCreateAsset

# DynamicActionsOrderActionDestroyAsset

# DynamicActionsOrderActionSetAbilities

# DynamicActionsOrderActionUpdateAssetImprint

# DynamicActionsOrderActionTransferAsset

# DynamicActionsOrderActionTransferValue

# FixedActionsOrderActionCreateAsset

# FixedActionsOrderActionDestroyAsset

# FixedActionsOrderActionSetAbilities

# FixedActionsOrderActionUpdateAssetImprint

# FixedActionsOrderActionTransferAsset

# FixedActionsOrderActionTransferValue

# Public addresses

These are the latest addresses that work with the 0xcert Framework version 2.0.0. For older addresses, check Documentation v1.

# Mainnet

Coming soon...

# Testnet

# Possible errors

The 0xcert Framework handles any kind of error that happens either in smart contracts or in the Framework itself and provides a thorough description wherever possible.

Error example:

{
  name: 'ProviderError',
  issue: '001001',
  original: '', // optional
  message: 'Sender does not have sufficient balance.'
}

This is a list of all possible errors that can be thrown by the 0xcert Framework. The list is split into two categories depending on the origin of the error.

# Framework errors

# Smart contract errors