How to Integrate Your Smart Contracts With Photon Messaging

Follow these FOUR simple steps

To begin using the Photon messaging please reach out to Entangle to undergo the KYB process and become registered as an external developer.

Once registered, here is what you need to do.

Step #1: Contract Preparation

Firstly, make sure that your smart contracts are compatible with the Endpoint contract.

This contract has the following interface for proposing omnichain operations:

/// @notice function of emitting event Propose for catching by receivers
    /// @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 encoded abi func selector, for non-EVM may be func signature or whole func name
    /// @param params function params for dest protocol function
    function propose(
        bytes32 protocolId,
        uint256 dstChainId,
        bytes calldata protocolAddress,
        bytes calldata functionSelector,
        bytes calldata params
    ) external isAllowedProposer(protocolId)

You can use our ready-to-use interface for ease of development.

The smart contract on the destination chain will be capable of processing the following call:

(bool success, bytes memory ret) = protocolAddress.call{value: msg.value}(
                abi.encodeWithSelector(
                    selector,
                    abi.encode(
                        opData.protocolId,
                        opData.srcChainId,
                        opData.srcBlockNumber,
                        opData.srcOpTxId,
                        opData.params
                    )
                )
            );

#2 Protocol Configuration Guide

To create your protocol within the ExternalDeveloperHub contract, you should set up the following parameters (note that all values are provided as examples). It's mandatory to deploy at least one manual Transmitter Agent for your protocol.

const MANUAL_TRANSMITTERS = ["address1", "address2"];
    const transmittersParams: TransmittersParams = {
        maxTransmitters: 10,
        minDelegateAmount: ethers.utils.parseUnits("100", "ether"),
        minPersonalAmount: ethers.utils.parseUnits("10", "ether"),
    }
    const protocolParams: ProtocolParams = {
        msgBetAmount: ethers.utils.parseUnits("0.001", "ether"),
        dataBetAmount: ethers.utils.parseUnits("0.0001", "ether"),
        msgBetReward: ethers.utils.parseUnits("0.002", "ether"),
        dataBetReward: ethers.utils.parseUnits("0.0002", "ether"),
        msgBetFirstReward: ethers.utils.parseUnits("0.004", "ether"),
        dataBetFirstReward: ethers.utils.parseUnits("0.0004", "ether"),
        consensusTargetRate: CONSENSUS_TARGET_RATE
    };

Parameters Explanation:

Parameter	Description
maxTransmitters	In a protocol, third-party agents can manage one transmitter each. The number of agents allowed equals the protocol's transmitter capacity minus any manually registered transmitters at launch. For instance, if a protocol supports 16 transmitters and 2 are registered initially, 14 additional agents can join. Each agent is restricted to one transmitter per protocol.
minPersonalAmount	At the start of each round, each agent is required to have a predetermined amount of personal stake, which must be deposited through the staking module. This stake amount is individually set for each agent.
minDelegateAmount	At the start of each round, each NGL agent must hold a specified minimum stake. This stake can be acquired through self-purchase and self-delegation or by receiving delegations from others. The minimum amount is determined individually for each agent.
msgBetAmount	If a transmitter's message fails to achieve confirmation and consensus, the amount offered is locked for at least one month. During this period, the locked amount can be claimed by a designated service address and is not returned to the transmitter.
dataBetAmount	The transmitter offers a specified amount as part of its participation in the stream data protocol, similar to the msgBetAmount mechanism.
msgBetReward	The protocol allocates funds to the agent for their services. After deducting a protocol fee by Photon, the remaining balance is split between the agent and their delegators. The agent sets their share, and the rest is distributed to delegators proportionally based on their contributions to the total delegation.
msgBetFirstReward	The reward goes to the agent whose transmitter first proposes an operation. If a manual transmitter proposes first, no reward is given, as manual transmitters don't place bets or receive rewards. The msgBetFirstReward should be set higher than the msgBetReward to offset the higher gas costs for the first transmitter. Both rewards are paid to the agent only after the operation is confirmed by consensus.
dataBetFirstReward	This reward functions similarly to the msgBetFirstReward within the stream data protocol, but it adheres to specific rules determined by a custom-created finalization library.
dataBetReward	The reward is paid similarly to the msgBetFirstReward; however, it is only disbursed if the specific protocol finalization library handling the bet determines that the agent merits the reward.
consensusTargetRate	The Master Smart Contract requires a specific percentage of signatures from the total current number of transmitters to approve an operation.

#3 Setting Up Your Protocol

To proceed with setting up your protocol, you'll need to add the protocol address on the destination chain where the data is intended to be delivered:

await protocol.addProtocolAddressEvm(CHAIN_ID, protocolContractAddress);

If it's the first time you are adding a protocol or proposer address to a new chain, you should wait until your protocol is initialized on the chain.

await protocol.waitProtocoloInitForChainId(CHAIN_ID, undefined, retries);

For Photon messaging protocol to work it is also needed to set at least one proposer address:

 await protocol.addProposerAddressEvm(CHAIN_ID, proposerContractAddress);

Deploy own Executor agent and add it too:

await protocol.addExecutorEvm(CHAIN_ID, executorAddress);

A proposer address is linked to a contract that initiates operations via the "propose" function. A protocol address, in contrast, is the recipient contract that processes the data sent by the proposer. While these addresses can sometimes be the same, they are often distinct to separate the roles of initiating and processing proposals for security and structural reasons.

#4 Deposit NGLfor Protocol Fees and Trasmitter Rewards

Once all setups are completed, external developers must supply their address with $NGL tokens by approving and depositing them into the ExternalDeveloperHub contract:

  /// @notice Deposit NGL to protocol balance
    /// @param _protocolId - Protocol id
    /// @param _amount - Amount of NGL to deposit
    function deposit(bytes32 _protocolId, uint _amount) external protocolOwner(_protocolId)

BONUS: Contract Deploying Guide – Not Required For Photon Messaging

In DataStream integration, the next step involves deploying the StreamDataSpotter contract via the StreamDataFactory contract using your specific parameters. This can be achieved by making a call.

    /// @notice Deploy spotter contract for the new sourceID
    /// @param protocolId protocol id
    /// @param sourceId source id
    /// @param processingLib address of deployed processing lib contract to be used for that spotter
    /// @param consensusRate consensus rate of agents necessary for update to happend
    /// @param allowedKeys array of allowed data keys, only existing datakeys can be used to vote the data for
    function deployNewStreamDataSpotter(
        bytes32 protocolId,
        bytes32 sourceId,
        address processingLib,
        uint256 consensusRate,
        uint256 minFinalizationInterval,
        bytes32[] calldata allowedKeys
    ) public onlyProtocolOwner(protocolId) returns (address)

Please note that these contracts are on the Entangle Oracle blockchain, so bridging some $NGL tokens is required to proceed.