Create a high-level transfer helper

[troggy]

Bounty

⚠️Bounty has EXPIRED. If you want to work on this issue, chime in into comments first ⚠️

We already have transferFromUtxos helper which is good, but still too low-level. Proposing to make an additional API hiding the whole UTXO thing completely and overall making it as lenient as possible. Aim to replace boilerplate like this, this and this with a one line of code.

API sketch:

type BigIntable = BigIntType | Number | string; // defined in `jsbi-utils` package
type PlasmaProvider = ExtendedWeb3 | LeapEthers | JsonRpcProvider;

function transfer(transferParams: {
  from: string, 
  to: string, 
  amount: BigIntable, 
  color: string | number, 
  plasma: PlasmaProvider, 
  signer: Signer // optional
}): Promise

Inspired by Exit.fastSellAmount

Scope

• the helper should get UTXOs for a given color from plasma provider, create a transfer tx, sign it and send out
• should return a Promise which resolves to TransactionReceipt (for now, as returned by sendSignedTransaction)
• should support
  • NST
  • NFT
  • ERC20
• if it takes more than 15 inputs to transfer the given amount, it should create a consolidation transaction and resume the transfer upon it's mined (see fastSell helper for inspiration)
• if there is not enough balance on the from account, it should throw a meaningful exception
• validates all the parameters are provided (except optional signer), otherwise throws a meaningful exception
• make sure from and to are both accepting valid Ethereum addresses only
• amount parameter. Should accept both string, BigInt or number. Consider to use jsbi-utils helper. Should validate the param and throw a meaningful exception if it is not coercible to integer value.
• color parameter. Should accept both string and number. Should validate it and throw a meaningful exception if it is not coercible to integer value.
• plasma parameter. Should support plasma providers:
  • ExtendedWeb3 (aka Leap web3)
  • LeapEthers
  • raw JsonRpcProvider from Ethers.js (usage example)
• signer parameter. Is optional. If omitted, then default signer should be used (see fastExit helper for the examples)

Deliverables

• updated library with the helper
• updated typedef
• updated Transfer Tokens page in docs. Keep the current content, add a "high level" option with example of how to use this API

Gain for the project

Roles

bounty gardener: @troggy / 20%
bounty worker: name / share
bounty reviewer: name / share

[troggy]

Sizing: https://leapdao.slack.com/archives/CAAGW85BR/p1559059236017200?thread_ts=1559059236.017200