metronome-lib

A JavaScript library for the Metronome Token.

This library is a thin wrapper around web3, metronome-contracts and metronome-ops to easy even more the interaction with the Metronome contracts. Operations like buying MET tokens in an auction, converting or porting tokens is mostly a one-liner.

Installation

npm install metronome-lib

Basic usage

const Metronome = require('metronome-lib')

// Get the status of the Metronome auction and converter contracts
const met = new Metronome(web3Instance)
met.getStatus().then(status => { /* ... */ })

// But MET in the ongoing auction
met.setAccount(myPrivateKeyOrMnemonic)
met.buyMet('1000000000000000000').then(purchase => { /* ... */ })

// Check my MET balance
met.getMetBalance().then(balance => { /* ... */ })

// Send MET to another account
met.sendMet(destinationAddress).then(transfer => { /* ... */ })

// Convert ether to MET
met.convertCoinsToMet('1000000000000000000').then(conv => { /* ... */ })

// Convert MET back to ether
met.convertMetToCoins('1000000000000000000').then(back => { /* ... */ })

// Port MET to another chain
const destMet = new Metronome(web3InstanceOnDestinationChain) // I.e. ETC
Promise.all([destMet.getDestinationChainData(), met.getOriginChainData()])
  .then(([destChainData, origChainData]) => met.exportMet(destChainData, '1000000000000000000')
    .then(exp => met.getExportProof(exp.data)
      .then(proof => destMet.importMet(origChainData, exp.data, proof))
    )
  )
  .then(imp => { /* ... */ })

API

new Metronome(web3)

Create a Metronome object ready to work with the Metronome contracts.

The proper contracts-set will be selected based on which chain the web3 instance is connected to.

| Param | Type | Description | | --- | --- | --- | | web3 | Object | A Web3 instance. |

metronome.getContracts() ⇒ Promise.<MetronomeContractsInstance>

Get the Metronome contracts of the library instance.

metronome.getMetChainName() ⇒ Promise.<string>

Get the Metronome chain name.

Returns: Promise.<string> - The name i.e. 'ETH'.

metronome.getAuctionStatus() ⇒ Promise.<AuctionStatus>

Get the status of the Auctions contract.

Returns: Promise.<AuctionStatus> - The status.

metronome.getConverterStatus() ⇒ Promise.<AutonomousConverterStatus>

Get the status of the AutonomousConverter contract.

Returns: Promise.<AutonomousConverterStatus> - The status.

metronome.getStatus() ⇒ Promise.<AuctionAndConverterStatus>

Get the status of both the Auctions and AutonomousConverter contracts.

Returns: Promise.<AuctionAndConverterStatus> - The statuses.

metronome.getMetBalance([owner]) ⇒ Promise.<string>

Get the MET balance of an account.

Returns: Promise.<string> - The MET balance.

| Param | Type | Description | | --- | --- | --- | | [owner] | string | The address of the account. Defaults to the set account. |

metronome.getCoinsToMetResult(depositAmount) ⇒ Promise.<string>

Calculate the coin to MET return conversion.

Returns: Promise.<string> - The MET amount that would be returned.

| Param | Type | Description | | --- | --- | --- | | depositAmount | string | The coin amount to convert. |

metronome.getMetToCoinsResult(depositAmount) ⇒ Promise.<string>

Calculate the MET to coin return conversion.

Returns: Promise.<string> - The coin amount that would be returned.

| Param | Type | Description | | --- | --- | --- | | depositAmount | string | The MET amount to convert. |

metronome.getDestinationChainData() ⇒ Promise.<DestinationChainData>

Get the destination chain data to perform an export.

Returns: Promise.<DestinationChainData> - The chain data.

metronome.getOriginChainData() ⇒ Promise.<OriginChainData>

Get the destination chain data to perform an export.

Returns: Promise.<OriginChainData> - The chain data.

metronome.getExportProof(exportData) ⇒ Promise.<string>

Get the Merkle root of a last 16 burns.

Returns: Promise.<string> - The Merkle root hash.

| Param | Type | Description | | --- | --- | --- | | exportData | Object | The returned export data. | | exportData.burnSequence | string | The burn sequence number. |

metronome.setAccount(privKeyOrMnemonic, options) ⇒ Metronome

Set the default account for this library instance.

All transactions will be signed and sent using the default account.

Returns: Metronome - The library instance.

| Param | Type | Description | | --- | --- | --- | | privKeyOrMnemonic | string | Either an 0x prefixed hex private key or a 12-word mnemonic. | | options | Object | | | [options.derivationPath] | string | The key derivarion path to derive the keys from the mnemonic. Defaults to m/44'/60'/0'/0/0. | | [options.password] | string | The mnemonic password. |

metronome.buyMet(value) ⇒ Promise.<OperationResult>

Buy MET in auction.

Returns: Promise.<OperationResult> - The purchase result.

| Param | Type | Description | | --- | --- | --- | | value | string | The coins to send to the contract. |

metronome.sendMet(to, value) ⇒ Promise.<OperationResult>

Transfer MET.

Returns: Promise.<OperationResult> - The transfer result.

| Param | Type | Description | | --- | --- | --- | | to | string | The recipient address. | | value | string | The amount to transfer. |

metronome.approveMet(spender, value) ⇒ Promise.<OperationResult>

Set MET allowance.

Returns: Promise.<OperationResult> - The allowance result.

| Param | Type | Description | | --- | --- | --- | | spender | string | The address allowed to spend tokens. | | value | string | The amount to approve. |

metronome.convertCoinsToMet(value, [minReturn]) ⇒ Promise.<OperationResult>

Convert coins to MET.

Returns: Promise.<OperationResult> - The conversion result.

| Param | Type | Description | | --- | --- | --- | | value | string | The coin amount to convert. | | [minReturn] | string | Will cancel conversion if minReturn tokens are not obtained. |

metronome.convertMetToCoins(amount, [minReturn]) ⇒ Promise.<OperationResult>

Convert MET to coins.

This function can result in up to 3 transactions depending on the previous allowance level granted to the AutonomousConverter contract. Only the last operation -the conversion- will be returned as the result of calling this function.

Returns: Promise.<OperationResult> - The conversion result.

| Param | Type | Description | | --- | --- | --- | | amount | string | The MET amount to convert. | | [minReturn] | string | Will cancel conversion if minReturn tokens are not obtained. |

metronome.exportMet(destinationData, amount) ⇒ Promise.<OperationResult>

Initiate an export of MET to another chain and obtain the burn data.

Returns: Promise.<OperationResult> - The export result.

| Param | Type | Description | | --- | --- | --- | | destinationData | DestinationChainData | The destination chain data. | | amount | string | The MET amount to burn and export. |

metronome.importMet(originData, exportData, proof) ⇒ Promise.<OperationResult>

Request the import of MET burned on another chain.

Returns: Promise.<OperationResult> - The import request result.

| Param | Type | Description | | --- | --- | --- | | originData | OriginChainData | The origin chain data. | | exportData | Object | The data obtained when the tokens were exported. | | proof | string | The burn proof on the origin chain. |

MetronomeContractsInstance : Object

A Metronome contracts set.

Properties

| Name | Type | Description | | --- | --- | --- | | Auctions | Object | The Web3 contract instance. | | AutonomousConverter | Object | The Web3 contract instance. | | METToken | Object | The Web3 contract instance. | | TokenPorter | Object | The Web3 contract instance. |

AuctionStatus : Object.<string, any>

An object representing the auction status.

Properties

| Name | Type | Description | | --- | --- | --- | | currAuction | string | The auction number. | | currentAuctionPrice | string | The MET price. | | dailyAuctionStartTime | number | The daily auctions start time (ms). | | genesisTime | number | The ISA start time (ms). | | lastPurchasePrice | string | The last purchase price. | | lastPurchaseTime | number | The last purchase time (ms). | | minting | string | The coins available in the current auction. | | nextAuctionTime | number | The next auction start time (ms). |

AutonomousConverterStatus : Object

An object representing the autonomous converter status.

The converter price returned is for informational purposes only as the conversion price will change depending on the amount sent and the contract's balance.

Properties

| Name | Type | Description | | --- | --- | --- | | currentConverterPrice | string | The coins returned for 1 MET. | | ethBalance | string | The contract's coins balance. I.e. ETH. | | metBalance | string | The contract's MET balance. |

AuctionAndConverterStatus : Object

A combined status.

Properties

| Name | Type | | --- | --- | | auction | AuctionStatus | | converter | AutonomousConverterStatus |

DestinationChainData : Object

An object having destination contracts data.

Properties

| Name | Type | Description | | --- | --- | --- | | destChain | string | The Metronome chain name. | | destMetronomeAddr | string | The METToken contract address. |

OriginChainData : Object

An object having destination contracts data.

Properties

| Name | Type | Description | | --- | --- | --- | | dailyAuctionStartTime | number | The METToken contract address. | | genesisTime | number | The METToken contract address. | | originChain | string | The Metronome chain name. |

OperationResult : Object

The result of any library operation.

Properties

| Name | Type | Description | | --- | --- | --- | | transactionHash | strict | The hash of the resulting transaction. | | data | Object | The returned data in the transaction logs for the operation. |

License

MIT