External Developer Guide

Become External Developer

To begin using the Photon messaging or DataStream protocol, please reach out to Entangle to undergo the KYC process and become registered as an external developer.

Contracts Preparation Guide

To utilize the Photon messaging or DataStream protocol, an external developer must ensure their smart contracts are compatible with the Endpoint contract.

This contract has the following interface for proposing omni-chain 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
                    )
                )
            );

Protocol Configuration Guide - Configuring with External Developer Hub contract

To create your protocol X within the ExternalDeveloperHub contract, you should set up the following parameters (note that all values are provided as examples, and it's mandatory to deploy at least one manual Receiver Agent, also known as a Transmitter, 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:

• maxTransmitters: In a protocol, an external developer can permit third-party agents to operate, with each agent managing one transmitter. The total number of agents allowed is determined by the number of transmitters the protocol can support minus any manually registered transmitters at launch. For example, if a protocol has a capacity for 16 transmitters and 2 are registered manually at the start, then up to 14 additional agents can join. Each agent is limited to operating just one transmitter within the same 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 beginning of each round, each NGL agent must hold a minimum amount of stake, which they can acquire either through self-purchase and self-delegation or by receiving delegations from others. This minimum amount is specified individually for each agent.

• msgBetAmount: A transmitter offers a specific amount for sending its message. If the message fails to achieve confirmation and consensus, this amount is locked for a minimum period of one month. During this time, it can be claimed by an address with a designated service role. The locked amount 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 specific amounts to the agent for their services. Initially, a protocol fee is deducted by Photon, and the remaining balance is then distributed between the agent and their delegators. The distribution ratio is determined by the agent, who specifies their own share, with the remainder proportionally allocated to delegators based on their individual contributions to the total delegation.

• msgBetFirstReward: The reward is granted to the agent whose transmitter is the first to propose an operation. However, if a manual transmitter proposes first, no reward is issued because manual transmitters neither place bets nor receive rewards. It is recommended that this reward, known as the msgBetFirstReward, be higher than the msgBetReward to compensate for the higher gas costs incurred by the first transmitter. Both rewards are disbursed to the agent only after the operation is confirmed by a consensus of watchers.

• 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.

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);

NOTE: 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.

Deposit NGL for protocol fees and receiver 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)

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.