Skip to content

Latest commit

 

History

History
430 lines (366 loc) · 15 KB

BSH.md

File metadata and controls

430 lines (366 loc) · 15 KB

BTP Service Handler (BSH)

Currently, there are two types of BSH implementations:

  • The native coin transfer service: a service supports multi-token standard (ERC-1155)
  • The token transfer service: this service supports ERC-20 standard

This section provides interfaces of the Native Coin Transfer Service which could be deployed to other blockchains that support Ethereum Virtual Machine (EVM). The NativeCoinBSH, written by Solidity language, consists of two contracts:

BSHCore

BSHCore (IBSHCore) is a smart contract that holds important application-specific logic implementations to handle coin transferring service

Interface

addOwner()

function addOwner(address _owner) external;
  • Description:
    • Allow a current owner to add an additional owner
    • Caller MUST have an ownership role
  • Params:
    • _owner: address ( Address of a new Owner )

removeOwner()

function removeOwner(address _owner) external;
  • Description:
    • Allow a current owner to remove an existing owner
    • Caller MUST have an ownership role
    • Unable to remove the last Owner
  • Params:
    • _owner: address ( Address of an Owner to be removed )

isOwner()

function isOwner(address _owner) external view returns (bool);
  • Description:
    • Checking whether one specific address has an ownership role
    • Caller can be ANY
  • Params:
    • _owner: address ( Address needs to be verified )
  • Returns:
    • true or false: bool

getOwners()

function getOwners() external view returns (address[] memory);
  • Description:
    • Query a list of current Owners
    • Caller can be ANY
  • Params:
    • None
  • Returns:
    • _owners: address[] ( An array of addresses of current Owners )

updateBSHPeriphery()

function updateBSHPeriphery(address _bshPeriphery) external;
  • Description:
    • Link/Update an address of BSHPeriphery contract
    • Caller MUST have an ownership role
    • The address of BSHPeriphery MUST be different from a current one
    • The current BSHPeriphery contract MUST have none of any pending requests
  • Params:
    • _bshPeriphery: address ( Address of BSHPeriphery contract )

updateUri()

function updateUri(string calldata _newURI) external;
  • Description:
    • Update a new base URI
    • Caller MUST have an ownership role
    • The current URI must be initialized in construction before
  • Params:
    • _newURI: string ( New string URI )

setFeeRatio()

function setFeeRatio(uint256 _feeNumerator) external;
  • Description:
    • Update a new value of fee_ratio
    • Caller MUST have an ownership role
    • The transfer fee is calculated by fixed_fee + feeNumerator/FEE_DEMONINATOR * transfer_amount
    • The feeNumetator should be less than FEE_DEMONINATOR
    • _feeNumerator is set to 10 in construction by default, which means the default fee ratio is 0.1%
  • Params:
    • _feeNumerator: uint256 ( Unsigned integer value of Fee Numerator )

setFixedFee()

function setFixedFee(uint256 _fixedFee) external;
  • Description:
    • Update a new value of fixed_fee
    • Caller MUST have an ownership role
    • The transfer fee is calculated by fixed_fee + feeNumerator/FEE_DEMONINATOR * transfer_amount
    • The fixed_fee will be set by SCORE Admin, the value is calculated based on an exchange rate at a setting time
  • Params:
    • _fixedFee: uint256 ( Unsigned integer value of fixed_fee )

register()

function register(string calldata _name) external;
  • Description:
    • Registers a wrapped native coin and its id number
    • Caller MUST have an ownership role
    • The registering name MUST be different from a native coin name of a current blockchain
    • id of a registering wrapped coin is generated by using uint256(keccak256(abi.encodePacked(name)))
    • id = 0 is fixed to assign to a native coin name of a current blockchain
  • Params:
    • _name: string ( A registered name of a wrapped coin )

coinNames()

function coinNames() external view returns (string[] memory _names);
  • Description:
    • Query all supporting coins
    • Caller can be ANY
  • Params:
    • None
  • Returns:
    • _names: string[] ( An array of string names of supporting coins )

coinId()

    function coinId(string calldata _coinName) external view returns (uint256 _coinId);
  • Description:
    • Query an id number of Coin/Wrapped Coin whose name is the same with given name
    • Caller can be ANY
  • Params:
    • _coinName: string ( A registered name of a native coin/wrapped coin )
  • Returns:
    • _coinId: uint256 ( An id of a given name )

isValidCoin()

    function isValidCoin(string calldata _coinName) external view returns (bool);
  • Description:
    • check validity of a given name of a coin/wrapped coin
    • Call by BSHPeriphery contract to validate a requested _coinName
  • Params:
    • _coinName: string ( A registered name of a native coin/wrapped coin )
  • Returns:
    • true or false: bool

getBalanceOf()

    function getBalanceOf(address _owner, string memory _coinName) external view returns (
        uint256 _usableBalance,
        uint256 _lockedBalance,
        uint256 _refundableBalance
    );
  • Description:
    • Query usable/locked/refundable balance of an account based on coinName
    • Caller can be ANY
    • _lockedBalance when a client requests to transfer coins/wrapped coins to another network, a requesting amount will be locked until getting a Service Message response
    • _refundableBalance upon receiving an Error Response of Service Message, a refund process occurs However, there might have an error in refunding back to the Requestor. Therein, it should issue _refundableBalance so that Requestor can re-claim later on
  • Params:
    • _owner: address ( Address of an account to query balance )
    • _coinName: string ( A registering name of a native coin/wrapped coin )
  • Returns:
    • _usableBalance: uint256 ( Balance of coinName that an account is currently holding )
    • _lockedBalance: uint256 ( Balance of coinName is currently locked until a pending request is settled )
    • _refundableBalance: uint256 ( Balance of coinName will be refunded back )

getBalanceOfBatch()

    function getBalanceOfBatch(address _owner, string[] calldata _coinNames) external view returns (
        uint256[] memory _usableBalances,
        uint256[] memory _lockedBalances,
        uint256[] memory _refundableBalances
    );
  • Description:
    • Query a list of usable/locked/refundable balances of an account based on coinNames
    • Caller can be ANY
  • Params:
    • _owner: address ( Address of an account to query balance )
    • _coinName: string[] ( An array of registering names of native coin/wrapped coins )
  • Returns:
    • _usableBalances: uint256[] ( Balances of coinNames that an account is currently holding )
    • _lockedBalances: uint256[] ( Balances of coinNames are currently locked until pending requests are settled )
    • _refundableBalances: uint256[] ( Balances of coinNames will be refunded back )

getAccumulatedFees()

    struct Asset {
        string coinName;
        uint256 value;
    }

    function getAccumulatedFees() external view returns (Asset[] memory _accumulatedFees);
  • Description:
    • Query a list of charged Fees
    • Caller can be ANY
    • Only return the asset that has value greater than 0
  • Params:
    • None
  • Returns:
    • _accumulatedFees: Asset[] ( An array of charged Fees )

transfer()

    function transfer(string calldata _to) external payable;
  • Description:
    • Allow users to deposit msg.value of native coins into a BSHCore contract
    • Caller can be ANY
    • MUST specify msg.value
  • Params:
    • _to: string ( An address that Requester expects to receive a corresponding amount of Tokens on another network)

transfer()

    function transfer(string calldata _coinName, uint256 _value, string calldata _to) external;
  • Description:
    • Allow users to deposit an amount of _coinName from the msg.sender address into the BSHCore contract
    • Caller can be ANY
    • Caller MUST set to approve that wrapped tokens can be transferred out of msg.sender account by BSHCore contract
  • Params:
    • _coinName: string ( A registered name of a wrapped coin )
    • _value: uint256 ( An amount requesting to transfer )
    • _to: string ( An address that Requester expects to receive a corresponding amount of Tokens on another network)

transferBatch()

    function transferBatch(string[] memory _coinNames, uint256[] memory _values, string calldata _to) external payable;
  • Description:
    • Allow users to transfer multiple coins/wrapped coins to another network
    • Caller can be ANY
    • Caller MUST set to approve that wrapped tokens can be transferred out of msg.sender account by BSHCore contract
    • MUST specify msg.value in case of requesting to transfer a native coin
    • A number of requested coins MUST be the same as the number of requested values
    • Requested coins and values MUST be matched respectively
  • Params:
    • _coinNames: string[] ( A list of requesting coins/wrapped coins )
    • _values: uint256[] ( A list of requesting values respectively with its coin name )
    • _to: string ( An address that Requester expects to receive a corresponding amount of Tokens on another network)

reclaim()

    function reclaim(string calldata _coinName, uint256 _value) external;
  • Description:
    • Allow Users to re-claim a refundable balance
    • Caller MUST be an owner of a refundable balance
    • The amount to claim MUST be smaller or equal to a refundable balance
  • Params:
    • _coinName: string ( A registered coin/wrapped coin name )
    • _value: uint256 ( An amount about to re-claim )

mint()

    function mint(address _to, string calldata _coinName, uint256 _value) external;
  • Description:
    • Mint an amount of wrapped coins
    • Caller MUST be a BSHPeriphery contract
    • Invalid _coinName will have an _id = 0. However, _id = 0 is also dedicated to a native coin. Thus, BSHPeriphery will check the validity of a requested _coinName before calling. For the _coinName indicates with _id = 0, it should send native coins (Example: PRA) to _to - a user's account
  • Params:
    • _to: address ( Address to receive a mint coin/wrapped coin )
    • _coinName: string ( A registered coin/wrapped coin name )
    • _value: uint256 ( An amount about to mint )

transferFees()

    function transferFees(string calldata _fa) external;
  • Description:
    • Handle a request of Fee Gathering
    • Caller MUST be a BSHPeriphery contract
  • Params:
    • _fa: string ( BTP Address of Fee Aggregator )

handleResponseService()

    function handleResponseService(
        address _requester,
        string calldata _coinName,
        uint256 _value,
        uint256 _fee,
        uint256 _rspCode
    ) external;
  • Description:
    • Handle a response of a requested service
    • Caller MUST be a BSHPeriphery contract
  • Params:
    • _requester: address ( Address of the originator of a requested service )
    • _coinName: string ( A registered coin/wrapped coin name )
    • _value: uint256 ( An amount to receive on a destination network )
    • _fee: uint256 ( An amount of charged fee )
    • _rspCode: uint256 ( Unsigned integer number of response code - RC_OK = 0, RC_ERR = 1)

BSHPeriphery

BSHPeriphery (IBSHPeriphery, ISBH) is a smart contract that handles communications between BMCPeriphery and BSHCore contracts

Interface

hasPendingRequest()

    function hasPendingRequest() external view returns (bool);
  • Description:
    • Check whether BSHPeriphery has any pending transferring requests
    • Caller can be ANY
    • Usage: BSHCore contract should check this before calling updateBSHPeriphery()
  • Params:
    • None
  • Returns:
    • true or false: bool

sendServiceMessage()

    function sendServiceMessage(
        address _from,
        string calldata _to,
        string[] memory _coinNames,
        uint256[] memory _values,
        uint256[] memory _fees
    ) external;
  • Description:
    • Send Service Message from BSHCore contract to BMCPeriphery contract
    • Caller MUST be BSHCore only
  • Params:
    • _from: address ( An address of Requester of this service )
    • _to: string ( A network address of destination chain )
    • _coinNames: string[] ( A list of coinNames that are requested to transfer )
    • _values: uint256[] ( A list of amounts to receive at a destination chain respectively with coinNames )
    • _fees: uint256[] ( A list of amounts of charging fees respectively with coinNames )

handleBTPMessage()

    function handleBTPMessage(
        string calldata _from,
        string calldata _svc,
        uint256 _sn,
        bytes calldata _msg
    ) external;
  • Description:
    • Handle BTP Message from BMC contract
    • Caller MUST be BMC contract only
  • Params:
    • _from: string ( An originated network address of a request )
    • _svc: string ( A service name of BSHPeriphery contract )
    • _sn: uint256 ( A serial number of a request )
    • _msg: bytes ( A RLP of a request/response )

handleBTPError()

    function handleBTPError(
        string calldata _src,
        string calldata _svc,
        uint256 _sn,
        uint256 _code,
        string calldata _msg
    ) external;
  • Description:
    • Handle BTP Error from BMC contract
    • Caller MUST be BMC contract only
  • Params:
    • _svc: string ( A service name of BSHPeriphery contract )
    • _sn: uint256 ( A serial number of a request )
    • _code: uint256 ( A response code of a request - RC_OK = 0, RC_ERR = 1 )
    • _msg: string ( A response message )

handleFeeGathering()

    function handleFeeGathering(string calldata _fa, string calldata _svc) external;
  • Description:
    • Handle Gather Fee request from BMC contract
    • Caller MUST be BMC contract only
  • Params:
    • _fa: string ( BTP Address of Fee Aggregator )
    • _svc: string ( A service name of BSHPeriphery contract )