Origin Domain Callback Interaction

[LayneHaber]

Summary

Create a JS-style callback template for use in the Connext.sol contract. If the callback address is specified, the result from Executor.execute will be returned to the callback address via Nomad, and a handler will be executed.

Motivation

One of the great things about the Amarok upgrade is it can enable JS-style callbacks to respond to some call on a destination domain. The flow here (at a high level) would be:

1. User creates some callData to be executed on a destination domain
2. User initiates the call using Connext.xcall(...)
3. The callData is executed on the destination domain
4. The destination domain Connext.sol returns the result via a PromiseRouter on nomad to the specified address on the origin domain
5. The origin domain handler contract (which implements the interface) can process the callback data

In this way contracts could handle something that happened on a different domain. Imagine a DAO initiates a crosschain call, but something on the destination domain is not executed properly. The callback on the origin domain could contain error-handling logic to address the failure.

Design Requirements

To be effective, the following goals must be met:

• Simple nomad return handler (should not go through bridge to reduce gas overhead)
• Should be an opt-in feature, you should not have to incur this overhead if you do not need a callback function
• Should be compatible with relayer fee scheme

Proposed Solution

At a high level, the following should happen when a callback is provided:

1. User creates a crosschain transfer with optional callback using xcall
2. If a callbackFee is included, it should be transferred to the local PromiseRouter and stored by transactionId
3. Router calls execute
4. In the Executor.execute function, if a callback address is provided it should call PromiseRouter.send(...) to dispatch the callback to the origin chain
5. The PromiseRouter should format the message and call Home.send to dispatch the callback data through nomad
6. Nomad will call handle which will store the message data onchain but will not execute the callback. The callback is not executed as a part of the handle function to avoid putting arbitrary gas obligations onto the nomad routers
7. A relayer calls PromiseRouter.process to execute the callback from the stored data
8. The relayerFee is paid directly to the msg.sender

If no callback is provided, the execute function should behave normally.

PromiseRouter and PromiseMessage

This design relies on a lightweight nomad PromiseRouter that is responsible for simply forwarding data across domains. The message structure should be flexible, but the length of the data should be capped to cap gas costs. The message can be prefixed with a single-byte version number to allow flexibility. The handler itself should have the following interface:

contract PromiseRouter is Router {
    function send(bytes32 transferId, uint32 destination, address callback, bytes calldata data) {
        // Should call Home.dispatch()
    }
    
    function handle(uint32 _origin, uint32 _nonce, bytes32 _sender, bytes memory _message) {
        // Should assert it is the right type
        
        // Should parse the `transactionId` from the message and store a hash of the message
    }

    function process(bytes32 transactionId, bytes memory _message) {
       // Should parse out the return data and callback address from message

       // Should execute the callback() function on the provided Callback address

       // Should enforce relayer is whitelisted by calling local connext contract

       // Should transfer the stored relayer fee to the msg.sender
    }
}

The PromiseMessage should encode the callback address, transfer identifier, and calldata. Any information required about the transfer should also be included in this message.

ICallback

Every contract that wishes to handle the return data from the destination domain should implement the following interface:

interface ICallback {
    function callback(bytes32 transferId, bytes memory data);
}

IConnext

The IConnext.CallParams should be updated to include:

struct CallParams {
    ...
    address callback; // address on the origin domain of the callback contract
    uint256 callbackFee; // relayer fee to execute the callback
}

In execute it should:

contract Connext {
    function execute(...) {
        bytes returnData = executor.execute(...); 
        // after data is executed, call .send on the PromiseRouter
        if (params.callback != address(0)) {
            promiseRouter.send(params.transferId, params.destinationDomain, params.callback, returnData);
        }
    }
}

Test Cases

This is a minimum required list of tests, but more should be included.

// ========= Executor.t.sol =========

// Should not interact with PromiseRouter if no callback provided
function testNoCallback() public {}

// Should send return data if callback is provided
function testSendCallback() public {}

// ========= PromiseRouter.t.sol =========

// Should handle data correctly
function testHandleCorrectData() public {}

// Should not handle message if it is not of the correct type
function testEnforceMessageType() public {}

// Should format + send message correctly
function testSendMessage() public {}

// Should fail to send message if message contents in valid
function testDontSendInvalidMessage() public {}

// Should fail to process message if doesn't match what's stored
function testDontProcessBadMessage() public {}

// Should fail to process message if relayer not whitelisted
function testProcessRelayerInvalid() public {}

// Should process + send funds to relayer
function testProcess() public {}

// ========= PromiseMessage.t.sol =========

// Should format message correctly
function testFormatMessage() public {}

// Should parse transferId correctly
function testParseTransferId() public {}

// Should parse callback address correctly
function testParseCallback() public {}

// Should parse return data correctly
function testParseReturnData() public {}

Open Questions

• What is the incurred overhead? Should we batch the return data?
• Should we expose properties about the transfer to the callback? What should those be?

Tasks

• PromiseRouter written
• PromiseMessage written
• Logic to bump callback fee on transaction
• Interface updates
• Updates to execute callback within Executor
• Tests

[jakekidd]

Is there anything besides the return data that should be passed across domains?

As discussed in discord, need to include official transfer ID in (at least) the return call on the origin domain, so the origin domain contract can validate that the return call is the one it sent (and not a malicious imposter call)...

How can we easily bake this into relayer fees? Can that be done onchain?

Well, we are calling execute, so fast liq connext routers when they do estimateGas on that call it will include any additional costs for this.... As for doing it onchain, that's pretty much just the sep. debated topic of onchain vs offchain fee calc

What is the incurred overhead? Should we batch the return data?

Batching should be done on the part of the consumer here. Basically, bus over as much data as you can in one go.

Should we add the ability to have permissioning in the callback?

How would permissioning in this context concern anyone other than us? If someone not permissioned to do the callback does the callback, it sounds like that's a nomad/connext infra failure. Shouldn't only the Connext.sol contract be calling promiseRouter.send ?

How can we ensure the Callback contract doesn't consume unbounded gas? If we can't, should we isolate it from the nomad agents?

Can you explain how it could consume unbounded gas if we have a messaging size limit? Sry im wooshing

[LayneHaber]

As discussed in discord, need to include official transfer ID in (at least) the return call on the origin domain, so the origin domain contract can validate that the return call is the one it sent (and not a malicious imposter call)...

we can also add onlyConnext modifiers to the PromiseRouter to reduce the likelihood of malicious callers

Well, we are calling execute, so fast liq connext routers when they do estimateGas on that call it will include any additional costs for this.... As for doing it onchain, that's pretty much just the sep. debated topic of onchain vs offchain fee calc

right, the question is more about the cost of the handling on the PromiseRouter -- basically it either gets offloaded completely to nomad (yikes) or you'll need some other function to poke it to the callback address with the right data. so it's unclear how to price in that callback poke function properly since you may not have the data to actually call estimateGas there

Batching should be done on the part of the consumer here. Basically, bus over as much data as you can in one go.

not sure 100% what you mean here, can you explain a bit further about what you're batching, how, and who pays?

How would permissioning in this context concern anyone other than us? If someone not permissioned to do the callback does the callback, it sounds like that's a nomad/connext infra failure. Shouldn't only the Connext.sol contract be calling promiseRouter.send ?

Callbacks may use similar msg.sender-esque checks about some of the properties set when processing the message, but I'm just not sure if that's useful or what would be needed there. These checks would be related to the message itself, not necessarily the promise router/connext (i.e. who was the msg.sender of the first call on the origin domain)

Can you explain how it could consume unbounded gas if we have a messaging size limit? Sry im wooshing

loop infinitely on the callback function, doesn't really have to be related to the message passed back

[LayneHaber]

Going to address some of the open questions:

What is the incurred overhead? Should we batch the return data?

We will have to take the same approach as we do with our existing nomad integration -- batch if needed. It's likely the cost for this is much lower than the bridge router because it is a very lightweight router.

How can we easily bake this into relayer fees? Can that be done onchain?

The enqueue of the promise into nomad will be implicit when the estimate gas using the SDK. We can expose the gas overhead as a constant for doing this. The more important (and difficult to incentivize) relay fee is the one for processing/executing the callback. If we don't include this as part of the handle call (which we shouldn't as the callbacks can be malicious), users will have to incentivize this with a relayer fee. Here we run into a similar problem as discussed in #899 -- namely that users will be the only ones who are able estimate the cost of the callback. It will be difficult to estimate this upfront (what if it fails?) or onchain (domains all account for gas differently). Users can define this fee when they xcall, or we can leave handling this contract call as a separate issue to be done outside of the scope of our system since its all on the origin domain.

The annoying part about handling this in our system is the callback address would have to store the fee and the fee amount as the Connext contract wouldn't necessarily be touched in the callback. You could custody on the Connext contract with appropriate validation, however.

How can we ensure the Callback contract doesn't consume unbounded gas? If we can't, should we isolate it from the nomad agents?

Can't -- should be isolated from the nomad agents.

Should we add the ability to have permissioning in the callback?

Can easily expose similar properties re: origin and destination initiators.

[LayneHaber]

Made into spec