Socket Contract API

The vault contract is an entry point for a user request. When a user requests Bridge or BridgeAndCall with their cryptocurrency, the vault contract securely locks it until the opposite-directional bridge request occurs.

The socket contract receives and verifies event messages from users or relayers. If the requested message is determined as valid, the socket contract executes request-indicated actions (e.g. mint, lending, leveraged investment) and checks whether or not these actions are executed correctly.

Interfaces of Vault contract

interface IVault {
    // Events that occur when a user's request is generated or an asset is processed
    event Vault(uint8 type_, uint128 asset_id_, uint256 amount_);
    
    // Function that returns the address of the associated WBFC
    function WBFC() view returns (address);
    // Function that returns the address of the associated socket
    function socket() view returns (address);
    // Function that returns the address of the associated swap router
    function swap_router() view returns (address);
    
    // Entry point for the user to initiate a CCCP request
    function request(User_Request memory user_request) payable returns (bool);
    // Entry point for socket to execute user request
    function execute(Instruction memory instruction) returns (bool);
    // Entry point for socket to complete user request
    function resolve(Task_Params memory params) returns (bool);
    // Entry point for socket to rollback user request
    function rollback(Task_Params memory params) returns (bool);
    // Entry point to provide the liquidity
    function liquidity_deposit(uint128 _asset_index, uint256 _amount) payable returns ();
    
    // Function that returns a value that identifies the native coin in which the contract was deployed
    function this_chain_coin_index() view returns (uint128);
    // Function that returns the fee rate
    function fee_rate() view returns (uint256);
    
    // Function that returns the handler address of the associated lending service
    function lending_handlers(uint128) view returns (address);
    
    // Function that returns a value that identifies the asset(coin, token)
    function get_asset_id(address) view returns (uint128);
    // Function that returns a token(coin) registered with an asset identification value
    function assets(uint128) view returns (AssetInfo memory asset_info);

    struct Asset_Config {
        uint128 min_amount;
        uint128 max_amount;
        uint32 _type;
        uint64 fee_rate;
        address target;
    }
    struct AssetInfo {
        Asset_Config config;
        uint256 amount;
        uint256 fee;
    }
    struct User_Request {
        Instruction ins_code;
        Task_Params params;
    }

    struct Instruction {
        ChainIndex chain;
        RBCmethod method;
    }
    struct Task_Params {
        Asset_Index tokenIDX0; Asset_Index tokenIDX1;
        address refund;
        address to;
        uint256 amount;
        bytes variants;
    }
}

Interfaces of Socket contract

interface ISocket {
    // Events that occur when relayer submits a round_up poll or when the round_up poll reaches majority
    event RoundUp(Task_Status status, Round_Up_Submit roundup);
    // An event that occurs when a user generates a request or when the request state is transitioned by relayer's poll
    event Socket(Socket_Message msg);
    
    // Entry point for user requests passed by Vault
    function user_executor(User_Request calldata request) external returns (bool)
    // Entry point for relayer to process user requests
    function poll(Poll_Submit calldata _submit) external returns (bool returnData)
    // Entry point for user to rollback unprocessed requests
    function timeout_rollback(RequestID calldata request, User_Request calldata _req) external returns (bool)
    
    // Function that returns a filter that records whether relayer has properly "poll" for the request
    function get_poll_filter(RequestID calldata _rid, address _sender) external view returns (uint256)
    // Function that returns stored request information
    function get_request(RequestID calldata _rid) external view returns(RequestInfo memory)
    // Function that returns signature information submitted by relayer for round update
    function get_round_signatures(uint256 _round) external view returns (Signatures memory)
    // Function that returns the signature submitted by relayer for processing the user's request
    function get_signatures(RequestID memory _rid, Task_Status _status) external view returns (Signatures memory)
    
    // Function that returns the address of the associated authority
    function authority() view returns (address)
    // Function that returns the address of the associated oracle manager
    function orc_manager() view returns (address)
    // Function that returns the address of the associated vault
    function vault() view returns (address)
    
    // Function that returns a value that identifies the chain in which the contract was deployed
    function this_chain() view returns (uint64)
    // Function that returns the number of requests generated by the user
    function sequence() view returns (uint128)
    // Function that returns a timeout value for rollback
    function timeout_blocks() view returns (uint256)
    
    // Entry point for relayer to update the round of native network
    function round_control_relay(Round_Up_Submit calldata _round_up_submit) external returns (bool)
    
    // --- only on BIFROST network ---
    
    // The entry point for relayer to feed Oracle of aggregate type
    function oracle_aggregate_feeding(Oracle_ID[] memory oids, bytes32[] memory data) onlyRelayer external returns (bool)
    // The entry point for relayer to feed Oracle of consensus type
    function oracle_consensus_feeding(Oracle_ID[] memory oids, uint128[] memory rounds, bytes32[] memory data) onlyRelayer external returns (bool)
    // The entry point for submitting a signature to update the round of the native network
    function round_control_poll(Round_Up_Submit calldata _round_up_submit) external returns (bool)

    type ChainIndex is uint64;
    type RBCmethod is uint64;
    type Asset_Index is uint128;
    type Oracle_ID is bytes32;

    struct Socket_Message {
        RequestID req_id;
        Task_Status status;
        Instruction ins_code;
        Task_Params params;
    }

    struct Poll_Submit {
        Socket_Message msg;
        Signatures sigs;
        uint256 option;
    }

    struct Instruction {
        ChainIndex chain;
        RBCmethod method;
    }

    struct Task_Params {
        Asset_Index tokenIDX0; Asset_Index tokenIDX1;
        address refund;
        address to;
        uint256 amount;
        bytes variants;
    }

    struct RequestID {
        ChainIndex chain;
        uint64 round_id;
        uint128 sequence;
    }

    struct Signatures {
        bytes32[] r;
        bytes32[] s;
        bytes     v;
    }

    struct Round_Up_Submit {
        uint256 round;
        address[] new_relayers;
        Signatures sigs;
    }

    enum Task_Status {
        None,
        Requested,
        Failed,
        Executed,
        Reverted,
        Accepted,
        Rejected,
        Committed,
        Rollbacked,
        Round_Up,
        Round_Up_Committed
    }
}