Harmony Marketplace SDK

Harmony Marketplace SDK provides a collection of interfaces to interact with HRC721, HRC1155 and any Smart Contracts that extends those standards. This library was based on @harmony-js

Install

npm i harmony-marketplace-sdk

Usage

Node

// JavaScript
const { HRC721 } = require('harmony-marketplace-sdk')

// TypeScript
import { HRC721 } from 'harmony-marketplace-sdk'

Browser

Include the ESM module (harmony-marketplace-sdk.esm.js) and import using:

<script type="module">
  import { HRC721 } from './harmony-marketplace-sdk.esm.js'
</script>

Wallet

Harmony Marketplace SDK provides three implementations of Wallet which help to create a Signer from a private key or mnemonic effortless.

Private Key

Implementation of the Wallet that uses a private key.

import { HttpProvider, WSProvider } from '@harmony-js/network'
import { PrivateKey, HarmonyShards, HARMONY_RPC_SHARD_0_URL, HARMONY_RPC_WS } from 'harmony-marketplace-sdk'

const privateKey = '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'

// Using a HttpProvider with a string url.
const pk = new PrivateKey(new HttpProvider('https://api.harmony.one'), privateKey)

// Using a HttpProvider with a const from Harmony Marketplace SDK.
const pk = new PrivateKey(new HttpProvider(HARMONY_RPC_SHARD_0_URL), privateKey)

// Using a WSProvider with a string url.
const pk = new PrivateKey(new WSProvider('wss://ws.s0.t.hmny.io'), privateKey)

// Using a WSProvider with a const from Harmony Marketplace SDK.
const pk = new PrivateKey(new WSProvider(HARMONY_RPC_WS), privateKey)

// Using a provider with a pre-configuration from Harmony Marketplace SDK.
const pk = new PrivateKey(HarmonyShards.SHARD_0, privateKey)

Mnemonic Key

Implementation of the Wallet that uses a list of words for the mnemonic key.

import { HttpProvider, WSProvider } from '@harmony-js/network'
import { MnemonicKey, HarmonyShards, HARMONY_RPC_SHARD_0_URL, HARMONY_RPC_WS } from 'harmony-marketplace-sdk'

const mnemonic = 'glory seat canal seven erosion asset guilt perfect fluid dice floor unfold'

// Using a HttpProvider with a string url.
const mnemonicKey = new MnemonicKey(new HttpProvider('https://api.harmony.one'), { mnemonic })

// Using a HttpProvider with a const from Harmony Marketplace SDK.
const mnemonicKey = new MnemonicKey(new HttpProvider(HARMONY_RPC_SHARD_0_URL), { mnemonic })

// Using a WSProvider with a string url.
const mnemonicKey = new MnemonicKey(new WSProvider('wss://ws.s0.t.hmny.io'), { mnemonic })

// Using a WSProvider with a const from Harmony Marketplace SDK.
const mnemonicKey = new MnemonicKey(new WSProvider(HARMONY_RPC_WS), { mnemonic })

// Using a provider with a pre-configuration from Harmony Marketplace SDK.
const mnemonicKey = new MnemonicKey(HarmonyShards.SHARD_0, { mnemonic })

Simple Key

Implementation of the Wallet that does not use any pk or mnemonic.

import { HttpProvider, WSProvider } from '@harmony-js/network'
import { Key, HarmonyShards, HARMONY_RPC_SHARD_0_URL, HARMONY_RPC_WS } from 'harmony-marketplace-sdk'

// Using a HttpProvider with a string url.
const key = new Key(new HttpProvider('https://api.harmony.one'))

// Using a HttpProvider with a const from Harmony Marketplace SDK.
const key = new Key(new HttpProvider(HARMONY_RPC_SHARD_0_URL))

// Using a WSProvider with a string url.
const key = new Key(new WSProvider('wss://ws.s0.t.hmny.io'))

// Using a WSProvider with a const from Harmony Marketplace SDK.
const key = new Key(new WSProvider(HARMONY_RPC_WS))

// Using a provider with a pre-configuration from Harmony Marketplace SDK.
const key = new Key(HarmonyShards.SHARD_0)

// Add Private key manually
key.addByPrivateKey('45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e')

HD Key

Implementation of a hierarchical deterministic (HD) wallet that uses a mnemonic to generate the derivative addresses.

import { HttpProvider, WSProvider } from '@harmony-js/network'
import { HDKey, HarmonyShards, HARMONY_RPC_SHARD_0_URL, HARMONY_RPC_WS } from 'harmony-marketplace-sdk'

const options = {
  mnemonic: 'glory seat canal seven erosion asset guilt perfect fluid dice floor unfold',
  index: 0,
  numberOfAddresses: 1,
  shardId: 0,
  gasLimit: '1000000',
  gasPrice: '2000000000',
}

// Using a HttpProvider with a string url.
const key = new HDKey(new HttpProvider('https://api.harmony.one'), options)

// Using a HttpProvider with a const from Harmony Marketplace SDK.
const key = new HDKey(new HttpProvider(HARMONY_RPC_SHARD_0_URL), options)

// Using a WSProvider with a string url.
const key = new HDKey(new WSProvider('wss://ws.s0.t.hmny.io'), options)

// Using a WSProvider with a const from Harmony Marketplace SDK.
const key = new HDKey(new WSProvider(HARMONY_RPC_WS), options)

// Using a provider with a pre-configuration from Harmony Marketplace SDK.
const key = new HDKey(HarmonyShards.SHARD_0, options)

Metamask Provider

Implementation a subclass of HttpProvider that takes window.ethereum as a parameter, each method of HttpProvider is implemented by this subclass by cascading the request appropriately to window.ethereum

import detectEthereumProvider from '@metamask/detect-provider'
import { MetamaskProvider } from 'harmony-marketplace-sdk'

const provider = await detectEthereumProvider()

// Using a MetamaskProvider with window or a detected provider.
const key = new Key(new MetamaskProvider(window.ethereum || provider))

Base Token

The BaseToken is an extension over a regular Contract which is the Harmony recomendation for interact with smart contracts. This abstract class contains the core functionality for interact with Harmony Smart Contracts.

HRC20 API

The HRC20 implements the abstract class Base Token.

NOTE: The harmony explorer will look for a specific list of functions and events to identify HRC20 tokens. You can validate if the bytecode of your HRC20 is valid here.

Expected Methods:

Method	Description
totalSupply	Total amount of tokens stored by the contract.
balanceOf	Returns the amount of tokens owned by account.
transfer	Moves amount tokens from the caller’s account to another account.
allowance	Returns the remaining number of tokens that spender will be allowed to spend on behalf of owner through transferFrom
approve	Sets amount as the allowance of spender over the caller’s tokens.
transferFrom	Moves amount tokens from an account to another account using the allowance mechanism.
symbol	Returns the symbol of the token.
name	Returns the name of the token.
decimals	Returns the decimals places of the token.
mint	Creates amount tokens and assigns them to account.
burn	Destroys amount tokens from account.
burnFrom	Destroys amount tokens from an account.

Expected Events

Event	Description
Transfer	Emitted when a token id is transferred from an address to another.
Approval	Emitted when owner enables approved to manage the tokenId token.

You can find an example of HRC20 in this address 0x...0a0a.

Initializing

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// A contract instance with options
const contract = new HRC20('0x...00', ABI, wallet, {
  data: '0x',
  shardID: 0,
  address: '0x...00',
  defaultAccount: wallet.getAccount('0x...00'),
  defaultBlock: 'lastest',
  defaultGas: '21000',
  defaultGasPrice: '1',
  transactionBlockTimeout: 2000,
  transactionConfirmationBlocks: '10',
  transactionPollingTimeout: 200,
})

Methods

totalSupply(txOptions?: ITransactionOptions): Promise<BN>

Returns the amount of tokens in existence.

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// returns the totalSupply as a BN instance
const totalSupply = await contract.totalSupply()

balanceOf(address: string, txOptions?: ITransactionOptions): Promise<BN>

Returns the number of tokens owned by address.

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// returns a BN instance.
const balance = await contract.balanceOf('0x...01')

transfer(to: string, amount: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

Moves amount tokens from the caller’s account to to.

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.transfer('0x...01', '1')

allowance(owner: string, spender: string, txOptions?: ITransactionOptions): Promise<BN>

Returns the remaining number of tokens that spender will be allowed to spend on behalf of owner through transferFrom. This is zero by default.

This value changes when approve or transferFrom are called.

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// returns a BN instance.
const tx = await contract.allowance('0x...01', '0x...02')

approve(spender: string, amount: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

Sets amount as the allowance of spender over the caller’s tokens.

Emits an Approval event.

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.approve('0x...01', 100)

transferFrom(from: string, to: string, amount: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

Moves amount tokens from from account to to.

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.transferFrom('0x...01', '0x...02', 100)

symbol(txOptions?: ITransactionOptions): Promise<string>

Returns the token symbol.

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// returns a string value.
const symbol = await contract.symbol()

name(txOptions?: ITransactionOptions): Promise<string>

Returns the token name.

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// returns a string value.
const name = await contract.name()

decimals(txOptions?: ITransactionOptions): Promise<number>

Returns the decimals places of the token.

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// returns a number value.
const name = await contract.decimals() // 18

mint(account: string, amount: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

Mints an amount of tokens and transfers them to the account increasing the total supply.

Emits a Transfer event with from set to the zero address.

Requirements

account cannot be the zero address.

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.mint('0x...01', 10)

burn(amount: number, txOptions?: ITransactionOptions)

Destroys an amount of tokens from the caller wallet, reducing the total supply.

Emits a Transfer event with to set to the zero address.

Requirements

account cannot be the zero address.
account must have at least amount tokens.

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.burn(10)

burnFrom(account: string, amount: number, txOptions?: ITransactionOptions)

Destroys amount tokens from account, deducting from the caller’s allowance.

Requirements

the caller must have allowance for accounts's tokens of at least amount.

import { PrivateKey, HarmonyShards, HRC20 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC20('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.burnFrom('0x...01', 10)

HRC721 API

The HRC721 implements the abstract class Base Token.

NOTE: The harmony explorer will look for a specific list of functions and events to identify HRC721 tokens. You can validate if the bytecode of your HRC71 is valid here.

Expected Methods:

Method	Description
balanceOf	The number of tokens in owner's account.
ownerOf	The owner of a token.
safeTransferFrom	Safely transfers a token from an address to another.
transferFrom	Transfers a token from an address to another address.
approve	Gives permission to an account to transfer a token to another account.
getApproved	Returns the account approved for a token.
setApprovalForAll	Approve or remove operator as an operator for the caller.
isApprovedForAll	Returns if the operator is allowed to manage all of the assets of an account.
totalSupply	Total amount of tokens stored by the contract.
tokenURI	The Uniform Resource Identifier (URI) for a token.
symbol	The token collection symbol.
name	The token collection name.
mint	Mints a token with the given id and transfers it to an address.
safeMint	Safely mints a token and transfers it to an address.
burn	Destroys a token

Expected Events

Event	Description
Transfer	Emitted when a token id is transferred from an address to another.
Approval	Emitted when an account enables another account to manage a token.

You can find an example of HRC721 in this address 0x...0a0a.

Initializing

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// A contract instance with options
const contract = new HRC721('0x...00', ABI, wallet, {
  data: '0x',
  shardID: 0,
  address: '0x...00',
  defaultAccount: wallet.getAccount('0x...00'),
  defaultBlock: 'lastest',
  defaultGas: '21000',
  defaultGasPrice: '1',
  transactionBlockTimeout: 2000,
  transactionConfirmationBlocks: '10',
  transactionPollingTimeout: 200,
})

Methods

balanceOf(address: string, txOptions?: ITransactionOptions): Promise<BN>

Returns the number of tokens in address's account.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a BN instance.
const balance = await contract.balanceOf('0x...01')

ownerOf(tokenId: BNish, txOptions?: ITransactionOptions): Promise<string>

Returns the owner of the tokenId token.

Requirements

tokenId must exist.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns an address.
const owner = await contract.ownerOf('1')

safeTransferFrom(from: string, to: string, tokenId: BNish, data?: any, txOptions?: ITransactionOptions): Promise<Transaction>

Safely transfers tokenId token from from to to.

Requirements

from cannot be the zero address.
to cannot be the zero address.
tokenId token must exist and be owned by from.
If the caller is not from, it must be approved to move this token by either approve or setApprovalForAll.
If to refers to a smart contract, it must implement IERC721Receiver.onERC721Received, which is called upon a safe transfer.

Emits a Transfer event.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.safeTransferFrom('0x...01', '0x...02', '1')

transferFrom(from: string, to: string, tokenId: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

Transfers tokenId token from from to to. Usage of this method is discouraged, use safeTransferFrom whenever possible.

Requirements

from cannot be the zero address.
to cannot be the zero address.
tokenId token must exist and be owned by from.
If the caller is not from, it must be approved to move this token by either approve or setApprovalForAll.

Emits a Transfer event.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.transferFrom('0x...01', '0x...02', '1')

approve(to: string, tokenId: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

Gives permission to to to transfer tokenId token to another account. The approval is cleared when the token is transferred.

Only a single account can be approved at a time, so approving the zero address clears previous approvals.

Requirements

The caller must own the token or be an approved operator.
tokenId must exist.

Emits a Approval event.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.approve('0x...01', '1')

getApproved(tokenId: BNish, txOptions?: ITransactionOptions): Promise<string>

Returns the account approved for tokenId token.

Requirements

tokenId must exist.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns an address.
const address = await contract.getApproved('1')

setApprovalForAll(addressOperator: string, approved: boolean, txOptions?: ITransactionOptions): Promise<Transaction>

Approve or remove addressOperator as an operator for the caller. Operators can call transferFrom or safeTransferFrom for any token owned by the caller.

Requirements

The addressOperator cannot be the caller.

Emits an ApprovalForAll event.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.setApprovalForAll('0x...01', true)

isApprovedForAll(owner: string, operator: string, txOptions?: ITransactionOptions): Promise<boolean>

Returns if the operator is allowed to manage all of the assets of owner.

See setApprovalForAll

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a boolean
const isApproved = await contract.isApprovedForAll('0x...01', '0x...02')

totalSupply(txOptions?: ITransactionOptions): Promise<BN>

Returns the total amount of tokens stored by the contract.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a number value.
const supply = await contract.totalSupply()

tokenURI(tokenId: BNish, txOptions?: ITransactionOptions): Promise<string>

Returns the Uniform Resource Identifier (URI) for tokenId token.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a string value.
const uri = await contract.tokenURI('10')


#### symbol(txOptions?: ITransactionOptions): Promise&lt;string&gt;

<p>Returns the token collection symbol.</p>

```ts

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a string value.
const symbol = await contract.symbol()

name(txOptions?: ITransactionOptions): Promise<string>

Returns the token collection name.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a string value.
const name = await contract.name()

mint(account: string, tokenId: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

Mints a token with tokenId and transfers it to the account.

Usage of this method is discouraged, use safeMint whenever possible

Requirements

tokenId must not exist.
account cannot be the zero address.

Emits an Transfer event.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.mint('0x...01', '1')

safeMint(to: string, tokenId: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

Safely mints a token with tokenId and transfers it to to.

Requirements

tokenId must not exist.
If to refers to a smart contract, it must implement IERC721Receiver.onERC721Received, which is called upon a safe transfer.

Emits an Transfer event.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.mint('0x...01', '1')

burn(tokenId: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

Destroys tokenId. The caller must own tokenId or be an approved operator.

Requirements

tokenId must exist.

Emits an Transfer event.

import { PrivateKey, HarmonyShards, HRC721 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC721('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.burn('1')

HRC1155 API

The HRC1155 implements the abstract class Base Token.

NOTE: The harmony explorer will look for a specific list of functions and events to identify HRC1155 tokens. You can validate if the bytecode of your HRC1155 is valid here.

Expected Methods:

Method	Description
balanceOf	Returns the amount of tokens of a token type (id) owned by an account.
balanceOfBatch	Batched version of balanceOf.
safeTransferFrom	Transfers the amount of tokens of a token type (id) from an address to another address.
safeBatchTransferFrom	Batched version of safeTransferFrom.
setApprovalForAll	Grants or revokes permission to an operator to transfer the caller’s tokens.
isApprovedForAll	Returns true if an operator is approved to transfer the tokens of an account.
owner	Returns the address of the current contract owner.
tokenURIPrefix	Returns the token URI prefix
contractURI	Returns a URL for the storefront-level metadata for your contract.
tokenURI	Returns the Uniform Resource Identifier (URI) for a token.
totalSupply	Total amount of tokens with a given token id
symbol	Returns the token collection symbol.
name	Returns the token collection name.
mint	Creates the amount of tokens of a token type (id), and assigns them to an account.
mintBatch	Batched version of mint

Expected Events

Event	Description
TransferSingle	Emitted when a token id are transferred from an address to another by operator.
TransferBatch	Emitted when a token ids are transferred from an address to another by operator.

You can find an example of HRC1155 in this address 0x...b264.

Initializing

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// A contract instance with options
const contract = new HRC1155('0x...00', ABI, wallet, {
  data: '0x',
  shardID: 0,
  address: '0x...00',
  defaultAccount: wallet.getAccount('0x...00'),
  defaultBlock: 'lastest',
  defaultGas: '21000',
  defaultGasPrice: '1',
  transactionBlockTimeout: 2000,
  transactionConfirmationBlocks: '10',
  transactionPollingTimeout: 200,
})

Methods

balanceOf(address: string, id: BNish, txOptions?: ITransactionOptions): Promise<BN>

Returns the amount of tokens of token type (id) id owned by address.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns a BN instance.
const balance = await contract.balanceOf('0x...01', '1')

balanceOfBatch(accounts: string[], ids: BNish[], txOptions?: ITransactionOptions): Promise<BN[]>

Batched version of balanceOf.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns an array of BN instance.
const balances = await contract.balanceOfBatch(['0x...01', '0x...02'], ['1', '2'])

safeTransferFrom(from: string, to: string, id: BNish, amount: BNish, data: any, txOptions?: ITransactionOptions): Promise<Transaction>

Transfers amount tokens of token type (id) id from from to to.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.safeTransferFrom('0x...01', '0x...02', '1', '1', [])

safeBatchTransferFrom(from: string, to: string, ids: BNish[], amounts: BNish[], data: any, txOptions?: ITransactionOptions): Promise<Transaction>

Batched version of safeTransferFrom.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.safeBatchTransferFrom('0x...01', '0x...02', ['1', '2'], ['1', '1'], [])

setApprovalForAll(addressOperator: string, approved: boolean, txOptions?: ITransactionOptions): Promise<Transaction>

Grants or revokes permission to operator to transfer the caller’s tokens, according to approved.

Emits an ApprovalForAll event.

Requirements

operator cannot be the caller.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.setApprovalForAll('0x...01', true)

isApprovedForAll(owner: string, operator: string, txOptions?: ITransactionOptions): Promise<boolean>

Returns true if operator is approved to transfer account's tokens.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns an boolean value.
const isApproved = await contract.isApprovedForAll('0x...01', '0x...02')

owner(txOptions?: ITransactionOptions): Promise<string>

Returns the address of the current owner.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns an address.
const owner = await contract.owner()

tokenURIPrefix(txOptions?: ITransactionOptions): Promise<string>

Returns the token URI prefix.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns an string value.
const uri = await contract.tokenURIPrefix()

contractURI(txOptions?: ITransactionOptions): Promise<string>

returns a URL for the storefront-level metadata for your contract.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns an string value.
const uri = await contract.contractURI()

totalSupply(id: BNish, txOptions?: ITransactionOptions): Promise<BN>

Total amount of tokens with a given token id.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns a number value.
const total = await contract.totalSupply('1')

tokenURI(tokenId: BNish, txOptions?: ITransactionOptions): Promise<string>

Returns the Uniform Resource Identifier (URI) for tokenId token.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns a string value.
const uri = await contract.tokenURI('1')

symbol(txOptions?: ITransactionOptions): Promise<string>

Returns the token collection symbol.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns a string value.
const symbol = await contract.symbol()

name(txOptions?: ITransactionOptions): Promise<string>

Returns the token collection name.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns a string value.
const name = await contract.name()

mint(account: string, tokenId: BNish, amount: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

Creates amount tokens of token type (id) tokenId, and assigns them to to.

Emits a TransferSingle event.

Requirements

to cannot be the zero address.
If to refers to a smart contract, it must implement IERC1155Receiver.onERC1155Received and return the acceptance magic value.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.mint('0x...01', '1', '10')

mintBatch(account: string, tokenIds: BNish[], amounts: BNish[], txOptions?: ITransactionOptions): Promise<Transaction>

Batched version of mint.

Emits a TransferBatch event.

Requirements

tokenIds and amounts must have the same length.
If to refers to a smart contract, it must implement IERC1155Receiver.onERC1155Received and return the acceptance magic value.

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const wallet = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)

// A contract instance
const contract = new HRC1155('0x...00', ABI, wallet)

// returns a Harmony Transaction instance.
const tx = await contract.mintBatch('0x...01', ['1', '2', '3'], ['10', '5', '20'])

BridgeToken API

Harmony -> Ethereum way bridge

Initializing

import { PrivateKey, HarmonyShards, HRC1155 } from 'harmony-marketplace-sdk'
import * as ABI from './abi.json'

const ethOwner = new Wallet(
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e',
  new EtherscanProvider(
    { chainId: 1 },
    API_KEY,
  )
) 
const hmyOwner = new PrivateKey(
  HarmonyShards.SHARD_0,
  '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e'
)
const bridge = new BridgeHRC20Token(hmyOwner, ethOwner)
const token = new HRC20('0x...00', ABI, hmyOwner)
const sender =  hmyOwner.accounts[0].toLowerCase()
const recipient =  ethOwner.address.toLowerCase()
const tokenInfo = { amount: 1000000000 }

// Send tokens from Harmony to Ethereum
const { addr, receiptId } = await bridge.sendToken(
  BridgeType.HMY_TO_ETH,
  sender,
  recipient,
  token,
  tokenInfo,
)

// Send tokens from Ethereum to Harmony
const { addr, receiptId } = await bridge.sendToken(
  BridgeType.ETH_TO_HMY,
  sender,
  recipient,
  token,
  tokenInfo,
)

Development

Install all the dependencies:

npmn ci

Copy the .env.sample file to .env

cp .env.sample .env

Configure the environment variables

# An Etherscan API key. This is need it for use the bridge contracts.
API_KEY=
# A private key
TEST_PK_1=
# A private key
TEST_PK_2=
# A private key for the end 2 end test
MASTER_PRIVATE_KEY=
# A private key for the end 2 end test
OWNER_PRIVATE_KEY=
# A test seed for the unit test
TEST_SEED="pablo diego jose francisco de paula juan nepomuceno maria ruiz y picasso"

In the project directory, you can run:

`npm run test`

Running the unit tests.

`npm run test:cov`

Running the test coverage.

`npm run test:e2e`

Running the end to end test.

`npm run test:lint`

Running the lint.

Change Log

See Changelog for more information.

Contributing

Contributions welcome! See Contributing.

Collaborators

Acknowledgements

This project was kindly sponsored by Harmony.

License

Licensed under the MIT - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 63 Commits
.circleci		.circleci
.github		.github
.vscode		.vscode
src		src
.bettercodehub.yml		.bettercodehub.yml
.editorconfig		.editorconfig
.env.sample		.env.sample
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmignore		.npmignore
.nvmrc		.nvmrc
.nycrc		.nycrc
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
hardhat.config.js		hardhat.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

License

blockcoders/harmony-marketplace-sdk

Folders and files

Latest commit

History

Repository files navigation

Harmony Marketplace SDK

Install

Usage

Node

Browser

Wallet

Private Key

Mnemonic Key

Simple Key

HD Key

Metamask Provider

Base Token

HRC20 API

Initializing

Methods

totalSupply(txOptions?: ITransactionOptions): Promise<BN>

balanceOf(address: string, txOptions?: ITransactionOptions): Promise<BN>

transfer(to: string, amount: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

allowance(owner: string, spender: string, txOptions?: ITransactionOptions): Promise<BN>

approve(spender: string, amount: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

transferFrom(from: string, to: string, amount: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

symbol(txOptions?: ITransactionOptions): Promise<string>

name(txOptions?: ITransactionOptions): Promise<string>

decimals(txOptions?: ITransactionOptions): Promise<number>

mint(account: string, amount: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

burn(amount: number, txOptions?: ITransactionOptions)

burnFrom(account: string, amount: number, txOptions?: ITransactionOptions)

HRC721 API

Initializing

Methods

balanceOf(address: string, txOptions?: ITransactionOptions): Promise<BN>

ownerOf(tokenId: BNish, txOptions?: ITransactionOptions): Promise<string>

safeTransferFrom(from: string, to: string, tokenId: BNish, data?: any, txOptions?: ITransactionOptions): Promise<Transaction>

transferFrom(from: string, to: string, tokenId: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

approve(to: string, tokenId: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

getApproved(tokenId: BNish, txOptions?: ITransactionOptions): Promise<string>

setApprovalForAll(addressOperator: string, approved: boolean, txOptions?: ITransactionOptions): Promise<Transaction>

isApprovedForAll(owner: string, operator: string, txOptions?: ITransactionOptions): Promise<boolean>

totalSupply(txOptions?: ITransactionOptions): Promise<BN>

tokenURI(tokenId: BNish, txOptions?: ITransactionOptions): Promise<string>

name(txOptions?: ITransactionOptions): Promise<string>

mint(account: string, tokenId: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

safeMint(to: string, tokenId: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

burn(tokenId: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

HRC1155 API

Initializing

Methods

balanceOf(address: string, id: BNish, txOptions?: ITransactionOptions): Promise<BN>

balanceOfBatch(accounts: string[], ids: BNish[], txOptions?: ITransactionOptions): Promise<BN[]>

safeTransferFrom(from: string, to: string, id: BNish, amount: BNish, data: any, txOptions?: ITransactionOptions): Promise<Transaction>

safeBatchTransferFrom(from: string, to: string, ids: BNish[], amounts: BNish[], data: any, txOptions?: ITransactionOptions): Promise<Transaction>

setApprovalForAll(addressOperator: string, approved: boolean, txOptions?: ITransactionOptions): Promise<Transaction>

isApprovedForAll(owner: string, operator: string, txOptions?: ITransactionOptions): Promise<boolean>

owner(txOptions?: ITransactionOptions): Promise<string>

tokenURIPrefix(txOptions?: ITransactionOptions): Promise<string>

contractURI(txOptions?: ITransactionOptions): Promise<string>

totalSupply(id: BNish, txOptions?: ITransactionOptions): Promise<BN>

tokenURI(tokenId: BNish, txOptions?: ITransactionOptions): Promise<string>

symbol(txOptions?: ITransactionOptions): Promise<string>

name(txOptions?: ITransactionOptions): Promise<string>

mint(account: string, tokenId: BNish, amount: BNish, txOptions?: ITransactionOptions): Promise<Transaction>

mintBatch(account: string, tokenIds: BNish[], amounts: BNish[], txOptions?: ITransactionOptions): Promise<Transaction>

BridgeToken API

Initializing

Development

Configure the environment variables

npm run test

npm run test:cov

npm run test:e2e

npm run test:lint

Change Log

Contributing

Collaborators

Acknowledgements

`npm run test`

`npm run test:cov`

`npm run test:e2e`

`npm run test:lint`

Packages