Token interface

This page contains a list of functions and events you can use to interact with the registry smart contracts

Functions

This section contains a list of functions you can use to interact with the registry smart contracts. The functions denoted with the [ERC-20] tag follow the ERC-20 standard specification.

Name [ERC-20]

Returns the name of the token - e.g. "MyToken".

function name() public view returns (string)

This function is public and can be called by anyone without specific permissions applied.

Symbol [ERC-20]

Returns the symbol of the token. E.g. “HIX”.

function symbol() public view returns (string)

This function is public and can be called by anyone without specific permissions applied.

Decimals [ERC-20]

Returns the number of decimals the token uses - e.g. 8, means to divide the token amount by 100000000 to get its user representation. To avoid dust on wallets the decimals value is always set to 0.

function decimals() public view returns (uint8)

This function is public and can be called by anyone without specific permissions applied.

Total Supply [ERC-20]

Returns the total token supply. Depending on the token parameter “autoMint” the total supply is either fixed (autoMint = False) or variable (autoMint = True).

This function always returns the total number of tokens that have been issued since the token has been deployed. In contrast to some ERC-20 implementations, this field doesn’t return the value of outstanding tokens. Burning tokens doesn’t reduce the total supply. To get the currently outstanding tokens, iterate over the holders array using the “number of holders” and “get holder” functions and sum the balances retrieved by calling the “balanceOf”, “activeBalanceOf” and/or “frozenBalanceOf” functions.

function totalSupply() public view returns (uint256)

This function is public and can be called by anyone without specific permissions applied.

Balance Of [ERC-20]

Returns the account balance of an account with address _owner. Please note, that this function returns the total balance of a holder including the frozen amount.

function balanceOf(address _owner) public view returns (uint256 balance)

This function is public and can be called by anyone without specific permissions applied.

Transfer [ERC-20]

Transfers _value amount of tokens to address _to. Fires a Transfer event. Transfers of 0 values are treated as normal transfers and fire the Transfer event.

function transfer(address _to, uint256 _value) public returns (bool success)

This function is public and can be called by anyone without specific permissions applied. The function throws if the message caller’s account balance does not have enough tokens to spend.

Transfer From [ERC-20]

Transfers _value amount of tokens from address _from to address _to. Fires the Transfer event. Transfers of 0 values are treated as normal transfers and fire the Transfer event. The _from address can use the "approve" or "increaseAllowance" function to add an allowance for the message's caller to spend the tokens.

function transferFrom(address _from, address _to, uint256 _value) public returns (bool success)

This function is public and can be called by anyone without specific permissions applied. The function throws unless the _from account has deliberately authorized the sender of the message via some mechanism.

Approve [ERC-20]

Allows _spender to withdraw from the message's sender account multiple times, up to the _value amount. If this function is called again it adds the value to the allowance. To prevent attack vectors like the one described here and discussed here, the approve function will throw an error if the allowance for the spender is not 0. Clients must make sure to create user interfaces in such a way that they set the allowance first to 0 before setting it to another value for the same spender.

We advise to use the safer "increaseAllowance" and "decreaseAllowance" functions described below.

function approve(address _spender, uint256 _value) public returns (bool success)

This function is public and can be called by anyone without specific permissions applied. The function throws if the message caller’s account balance does not have enough tokens to spend.

Allowance [ERC-20]

Returns the amount which _spender is still allowed to withdraw from _owner.

function allowance(address _owner, address _spender) public view returns (uint256 remaining)

This function is public and can be called by anyone without specific permissions applied.

Increase Allowance

Increases the allowance with the addedAmount for the spender to withdraw tokens from the message's sender balance. This is safer alternative to the "approve" function (see here for details).

function increaseAllowance(address spender, uint256 addedAmount) external

This function is public and can be called by anyone without specific permissions applied. The function throws if the message caller’s account balance does not have enough tokens to spend.

Decrease Allowance

Decreases the allowance with the subtractedAmount.

function decreaseAllowance(address spender, uint256 subtractedAmount) external

This function is public and can be called by anyone without specific permissions applied.

Frozen Balance Of

Returns the frozen balance of an account. Frozen tokens cannot be transferred to other wallets. Frozen balances can be burned.

function frozenBalanceOf(address who) external view returns (uint256)

This function is public and can be called by anyone without specific permissions applied.

Number of Holders

This function returns the total number of account holders. You can use this function to iterate over the holders array using the "getHolder" function. The array starts with index 1.

function numberOfHolders() external view returns (uint256) 

This function is public and can be called by anyone without specific permissions applied.

Get Holder

This function returns the address of a holder with the given ID. The number of holders can be retrieved via the "numberOfHolders" function.

function getHolder(uint256 idx) external view returns (address)

This function is public and can be called by anyone without specific permissions applied.

Paused

Returns true if the contract is paused and false if unpaused. While the contract is paused, the holder array as well as token amounts are stable.

If this is set to true, token transfers will fail. If autoMint is set to false and an initial total supply has been set, pausing the contract will also prohibit issuing token amounts. If autoMint is set to true and there is no initial total supply, minting tokens to addresses is still possible even though the contract is paused.

Pausing a contract doesn’t limit the ability to freeze or burn tokens.

function paused() public view returns (bool)

This function is public and can be called by anyone without specific permissions applied.

Allow Unverified Transfers

This function returns true if whitelisting is disabled and false if the whitelisting mechanism is enabled.

function allowUnverifiedTransfers() public view returns (bool)

This function is public and can be called by anyone without specific permissions applied.

Transfers Lockup Period

This function returns the lock-up time for transfers. If the current date and time are prior to the lock-up time, transfers will always fail. The lock-up time doesn’t prohibit the minting of tokens.

function lockTransfersUntil() public view returns (uint256)

This function is public and can be called by anyone without specific permissions applied.

MetadataJSON

This function returns the metadata for a specific token. MetadataJSON is set to contain a JSON object with the following key/values pairs: calculation_factor, issuer_company_name, isin.

function metadataJSON() public view returns (string)

This function is public and can be called by anyone without specific permissions applied.

Paper Contract Hash

This functions returns the SHA-256 hash digest integer value of the issuance document PDF file.

With a PDF file downloaded from the Cashlink Registry Website, you can verify that the PDF file is the one referenced by comparing the hash digest values: The following Python script gives an example on how to compute the hash digest from the PDF file. The printed value should match the value returned by the "paperContractHash" function.

Please make sure to always obtain the issuance document PDF file as well as the hash digest from the registry website on the cashlink.de domain having a valid certificate attached to it.

import hashlib
import mmap

FILE_PATH = '<enter path to file here'

def sha256sum(filename):
    h  = hashlib.sha256()
    with open(filename, 'rb') as f:
        with mmap.mmap(f.fileno(), 0, prot=mmap.PROT_READ) as mm:
            h.update(mm)
    return h.hexdigest()


h = sha256sum(FILE_PATH)

# Calculate integer value from the hex digest
print(int.from_bytes(bytes.fromhex(h), byteorder='little'))

A paper contract hash with the value 0 has a special meaning: As long as it is 0, transfers cannot be unpaused.

function paperContractHash() public view returns (uint256)

This function is public and can be called by anyone without specific permissions applied.

Events

This section contains a list of events that can be emitted when interacting with the smart contract. Subscribe to these events in order to update your client directly on status changes. The events denoted with the [ERC-20] tag follow the ERC-20 standard specification.

Transfer [ERC-20]

Triggers when tokens are transferred, including zero value transfers. Also, the event is triggered when tokens are minted.

event Transfer(address indexed _from, address indexed _to, uint256 _value)

Approval [ERC-20]

Triggered on any successful call to approve(address _spender, uint256 _value).

event Approval(address indexed _owner, address indexed _spender, uint256 _value)

Set Allow Unverified Transfers

Triggered when the setting is updated.

event SetAllowUnverifiedTransfers(bool allowUnverifiedTransfers)

Set Paper Contract Hash

Triggered when the paper contract hash is updated.

event SetPaperContractHash(uint256 paperContractHash)

Tokens Minted

Triggered on an increase of the total supply of the token.

event TokensMinted(uint256 amount)

Tokens Issued

Triggered when tokens are credited to a holder account as a result of a primary market transaction against the issuer. The same transaction will also trigger the TokensMinted event if new tokens will be created to fill the order.

event TokensIssued(address to, uint256 amount)

Tokens Frozen

Triggered when fractions of holder balances with the IDs are frozen.

event TokensFrozen(uint256 fromIdx, uint256 toIdx, uint256 quotNum, uint256 quotDenom)

Tokens Unfrozen

Triggered when fractions of holder balances with the IDs are unfrozen.

event TokensUnfrozen(uint256 fromIdx, uint256 toIdx, uint256 quotNum, uint256 quotDenom)

SetMetadataJSON

Triggered when function setMetadataJSON is called and metadataJSON is changed.

event SetMetadataJSON(string metadataJSON)

ForcedTransfer

Triggered when function forcedTransferFrom is called.

event ForcedTransfer(address indexed from, address indexed to, uint256 amount)

Tokens Burned

Triggered when frozen tokens of holders are burned. Note that a burn doesn't reduce the return value of the total supply function.

event TokensBurned(uint256 fromIdx, uint256 toIdx)

Tokens Destroyed

Triggered when a atomic freeze and burn operation is executed for the address and amount. Note that a destroy transaction doesn't reduce the return value of the total supply function.

event TokensDestroyed(address addr, uint256 amount)