ioCash smart contracts


Contents






EMToken - ERC 2020



ioCash team, in collaboration with Adhara, have created the ERC 2020, EM-Token Standard that extends the ERC-20 token standard and adds extra functionalities with the aim to enable the issuance of regulated electronic money on blockchain networks and its practical usage in real financial applications.

These main functionalities are: compliance, holds, clearing, funding requests and payouts orders.

ioCash is already using these concepts in its smart contracts. The next paragraphs will explain how you can use some of these functionalities by interacting with the smart contracts.





Interacting with ioCash smart contract



ioCash smart contracts are built based on the EM-Token standard. All ioCash smart contracts, except the cross ledger one, inherit from one master contract that we have called the EM-Token smart contract. Therefore, you can access all the available functionalities (holds, transfers, two step transfers etc.) by making calls against it. To make cross ledger transfers your have to use a different contract -The Cross Ledger Link (CLL)-.

To interact with the Em-Token you can use the following abstract contract from our GitHub repository. Our Github also contains a couple of very simple smart contract examples that showcase the interaction with the EM-Token. To use the Cross Ledger Link you can see its abstract in Github.

You can also check the demo web app that we have created to interact with the EM-Token. You could use it to get familiar with the creation of Dapps using the EM-Token and to build on top of it some extra functionalities with the aim of doing a simple and fast PoC or a demo of your use case.


Current smart contract addresses


Alastria Telsius. Chain id: 83584648538


Em-Token:

  • PRO environment: 0xd3Fbd750bd0D604E21e93F3bd1d347C07B9F2B49
  • PRE environment: 0x7a5437C7FEc1eEEFf208CE7F032a57C12296b073

Cross Ledger Link:

  • PRO environment: 0x86DD13DC2063786D644B3e202e3beA121B560111
  • PRE environment: 0x7F20b0B040cF33dbEB2bB64316f2Ff96572dB4f6


LacChain. Chain id: 648529


Em-Token:

  • PRO environment: 0xd29968dC60fB5f5341A09288C0417dBDb438064E
  • PRE environment: 0xd6ffB04b2392c75D557Bb9956EcAC2cd286D2a41

Cross Ledger Link:

  • PRO environment: 0x2DbF3F8beD4d04E038582850f1Dc7cBB8e714D55
  • PRE environment: 0xF0E4cD40Cce15953aCEd4567E513500D4cDdABd4


ioBuilders network - Hyperledger Besu. Chain id: 1003


Em-Token:

  • PRO environment: 0x1287da876DE7FA8E461fffB397ffF4eC92dA860a
  • PRE environment: 0x8ebA836187b3c2E17Fc8C48447C425A9bC1A9101

Cross Ledger Link:

  • PRO environment: 0xe5C333Bb9C0350F759B558c470De9f88919b0b4B
  • PRE environment: 0x82194C1f89aF9eA4BD22307257bE031075958d14


Features


ioCash smart contracts offer the following features:

Transfers


ioCash is fully compliant with the ERC-20 standard which is used for transfers. The following functions are available:

transfer
Send tokens to another address.

transferFrom
Send tokens on behalf of somebody else.

approve
Allow another address to send on your behalf.

allowance
Tells you how much somebody can send on somebody else's behalf.

balanceOf
Tells you how many tokens an address has.

totalSupply
Tells you total amount of all tokens combined.

decimals
Tells you how many decimals after the coma can be used when transferring tokens.

symbol
Tells you the individual symbol of a token.

name
Tells you the individual name of a token.



For more details please see the ERC-20 standard.


Holds


Holds guarantee a future transfer and make the held tokens unavailable for transfer in the meantime. Holds are similar to escrows because they are firm and lead to final settlement.
A hold specifies a payer, a target, an amount, a notary and an expiration time. When the hold is created, the specified token balance from the payer is put on hold. A held balance cannot be transferred until the hold is either executed or released. The hold can only be executed by the notary, which triggers the transfer of the tokens from the payer to the payee. The execution of a hold can be done with the full amount or a partial one. If only a partial hold is executed the remaining tokens are available again to the payer. If a hold is released, either by the notary or the target no transfer is carried out and the amount is available again for the payer. It is also possible to add an expiration date to holds. If ther hold has not yet been executed or released and the expiration date is achieved, the held quantity is realesed on the sender's account. The expiration of a hold is optional, it can also be perpetual (no expiration).

The following functions are offered:

hold
Creates a new hold.

holdWithExpirationDate
Creates a new hold passing the expiration date in seconds instead of the time until it expires.

holdFrom
Creates a new hold on behalf of another account.

holdFromWithExpirationDate
Creates a new hold on behalf of another account passing the expiration date in seconds instead of the time until it expires.

executeHold
Transfers all or a part of the tokens which were specified when creating the hold. The remaining part of the hold that is not sent is released on the sender's account

executeHoldAndKeepOpen
Transfers a part of the tokens which were specified when creating the hold. The remaining part that is not sent is kept on hold for a future execution or release.

releaseHold
Does not make a transfer and makes the held tokens available again to the payer.

renewHold
Changes the expiration time.

renewHoldWithExpirationDate
Changes the expiration time passing the expiration date in seconds instead of the time until it expires.

retrieveHoldData
Returns the details of a given hold.

balanceOnHold
Tells you how many tokens of an address are held.

netBalanceOf
Tells you how many tokens including the held tokens an address has.

totalSupplyOnHold
Tells you total amount of all held tokens combined.

authorizeHoldOperator
Authorizes an account to create holds on behalf of the sender.

revokeHoldOperator
Revokes the permission to create holds on behalf of the sender.

isHoldOperatorFor
Returns if an account is authorized to create hold on behalf of another account.


The following ERC-20 functions behave differently than the standard if a hold is used:

balanceOf
The held balance of an account is deducted from the ERC-20 balance. In order to get all tokens assigned to an account the function virtualBalanceOf has to be used.

transfer
The implementation of ERC-20 has been changed in order to deduct the held balance from the ERC-20 balance. Any amount that is held can not be transferred.

transferFrom
The standard implementation of ERC-20 has been changed in order to deduct the held balance from the ERC-20 balance. Any amount that is held can not be transferred.


For more details please see our GitHub repository with the interface of the Holdable Token.



Two Step Transfers


The two step transfer (clearing) process turns the promise of a transfer into the actual movement of money from one account to another. It has the same properties as a hold, but the notary and expiration are set automatically by the ioCash platform. The amount which should be transferred is not deducted from the balance of the payer, but neither is it available for another transfer and therefore ensures, that the execution of the transfer will be successful when it is executed. Off-chain checks are executed to decide if the transfer can be executed or not.

The following functions are offered:

orderTransfer
Creates a request for a transfer.

releaseTransfer
Transfers the token which were specified when requesting the transfer.

revokeTransferByExpiration
Revokes the transfer after it has expired.

revokeTransferByNotary
The notary can revoke the hold at any time.

revokeTransferByTarget
The target can revoke the hold at any time.



For more details please see our GitHub repository with the interface of the TwoStep Transferable Token.


Cross ledger transfers


Cross ledger transfers enable the transfer tokens between different networks. There are several steps in a cross ledger transfer that transits it to different statuses. After a user orders it, status ORDERED, the money is put into escrow in the origin network. Then, the platform checks that the operation fulfills all the needed requirements, confirming it in the origin network, status ACCEPETED, and in the destination network, status ACKNOWLEDGED. Finally, it is executed in the destination nework, status TRANSFER_IN_EXECUTED and origin network, status TRANSFER_OUT_EXECUTED.

Hash-locks and suspense accounts are used to ensure the correct order in the operation and the needed security measures. If you want to know more about the flow and functioning of our cross ledger implementation, check this post

To make a cross ledger you have to use the Cross Ledger Link smart contract. The following functions are offered:

orderTransfer
Creates a request for a cross ledger transfer.

getTransferData
Retrieves the information about a cross ledger transfer.




Smart contract error codes


For size reasons, we have codified some revert reasons of our smart contracts. Although the movements already have the translation made and the error text is displayed, if you are directly working with our smart contracts you will get the plain error codes. You can use the table below for the needed translation.


Error code Error reason
0x10 Operation only allowed for owner/bank
0x11 Only available for migrator
0x12 Only available for operators
0x13 Token can not trade partial amounts
0x14 Token is locked
0x15 Token not whitelisted
0x16 Only available if one-step-transfers are activated
0x17 Sender is not allowed to send tokens
0x18 Receiver is not allowed to receive tokens
0x19 Sender is not allowed to mint tokens
0x1A Sender is not allowed to burn tokens
0x1B The sender is unsubscribed
0x1C The receiver is unsubscribed
0x1D Action not allowed to any user
0x1E Only available for currency registry operator
0x1F Only available for cross ledger operator
0x20 Target cannot be zero address
0x21 Compliance registry cannot be zero address
0x22 Registry cannot be zero address
0x23 The address is not permissioned in the token
0x24 Origin cannot be zero address
0x32 Token is already locked
0x33 Cross ledger transfer operation Id already exists
0x34 Status of cross ledger transfer should be "Ordered"
0x35 Status of cross ledger transfer should be "Acknowledged"
0x36 Status of cross ledger transfer should be "Accepted"
0x37 Hold operation Id already exists
0x50 Amount should be greater than zero
0x51 Not enough balance
0x52 Currency is not active
0x53 Currency is already active
0x54 Currency token is not equal to source token
0x55 Suspense account already exists
0x56 Suspense account does not exist
0x57 Token operator already exists
0x58 Token operator does not exist
0x59 Suspense account cannot be deactivated because it has positive balance
0x5A Hashlock and secret do not match
0x5B Cross ledger operator already exists
0x5C Cross ledger operator does not exist
0x5D Chain already active
0x5E Chain is not active