Function Calls

Function Call #1 – Calling The Transmitters

    /// @notice function of emitting event Propose for catching by receiverkeepers
    /// @param protocolId protocol id to interact
    /// @param dstChainId dest chain id
    /// @param protocolAddress dest protocol address is bytes32 cause dstChainId may be non-EVM
    /// @param functionSelector dest protocol function id, for EVM is abi func selector, for non-EVM may be any id format
    /// @param params function params for dest protocol function
    function propose(
        bytes32 protocolId,
        uint256 dstChainId,
        bytes calldata protocolAddress,
        bytes functionSelector,
        bytes calldata params
    ) external isAllowedProposer(protocolId) {
        emit Propose(protocolId, nonce++, dstChainId, protocolAddress, functionSelector, params);
    }

Caller

import "@entangle_protocol/oracle-sdk/contracts/IProposer.sol";
import "@entangle_protocol/oracle-sdk/contracts/lib/PhotonFunctionSelectorLib.sol";
contract MyContract {
    struct YourMsgStruct {
        string str;
        uint num;
    }

    IProposer endPoint;
    address ethContractAddress;

    function sendProposeOperation() external {
        bytes32 protocolId = bytes32("your-protocol-id");
        uint destChainId = 1; // eth
        bytes memory destContractAddress = abi.encode(ethContractAddress);
        // encode EVM selector as PhotonSelector
        bytes memory selector = PhotonFunctionSelectorLib.encodeEvmSelector(bytes4(keccak256(bytes("receive(bytes)"))));
        YourMsgStruct memory msg = YourMsgStruct("hello world", 9000);
        bytes memory encodedPayload = abi.encode(msg);
        endPoint.propose(
                protocolId,
                destChainId,
                destContractAddress,
                selector,
                encodedPayload);
    }
}

Explainer

The `propose` function is designed to emit a structured event containing details about a proposed interaction with a protocol on possibly another blockchain.

This event can then be caught by Transmitters, which may perform further actions such as validating the proposal, executing cross-chain calls, or any other required process as per the system's design.

Function Call #2 – Receive Prompt From End Point

/// @notice Receive function example, always should take 1 arg (bytes)
/// @param data encoded: bytes32 protocolId, uint256 srcChainId, uint256 srcBlockNumber, bytes32[2] srcOpTxId, bytes payload
function receive(bytes calldata data) external onlyRole(SPOTTER) {
    (bytes32 protocolId, uint256 srcChainId, uint256 srcBlockNumber, bytes32[2] memory srcOpTxId, bytes memory payload) = abi.decode(data, (bytes32, uint256, uint256, bytes32[2], bytes));
    YourMsgStruct memory msg = abi.decode(payload, (YourMsgStruct));
}

Explainer

The receive function is triggered by an End Point contract on a destination blockchain network once an operation has received consensus approval. It is restricted to ensure only authorized entities can activate it, bolstering security.

Function Parameters:

• data (bytes calldata): Encapsulates essential details of the operation in a byte array format, which includes:

  • protocolId: Identifier of the originating protocol.

  • srcChainId: ID of the source blockchain.

  • srcBlockNumber: Block number on the source blockchain where the operation was initiated.

  • srcOpTxId: Unique identifier for the operation on the source blockchain. For blockchains with 32-byte transaction IDs, srcOpTxId[0] holds the ID and srcOpTxId[1] is set to 0x00.

  • payload: Additional operation-specific data.

Function Execution:

1. Data Decoding: The function uses abi.decode to extract srcChainId, srcBlockNumber, srcOpTxId, and payload from the data parameter.

2. Payload Processing: Further decodes the payload to retrieve specific data relevant to the operation.

This function ensures secure and verified execution of approved operations from the source blockchain to the destination network.

For Web2 triggers, the srcChainId, srcBlockNumber, and srcOpTxId parameters can contain information about source identifier. This can be beneficial for processing information from various sources differently.