cross-chain deposit approval

[BigLep]

This is a placeholder to add more details.

Done Criteria

FILL THIS IN

Why Important

FILL THIS IN

@BigLep understanding is that this should enable cross-chain actions to work without users needing to pay gas inn FIL.

User/Customer

FILL THIS IN

Notes

[BigLep]

2025-12-04 discussion around prioritization: This is not in scope for FOC GA. This needs a new filecoin pay contract, and needing to migrate from v1->v2 filecoin pay for FWSS is expanded scope for getting on GA & the ROI is unclear to us yet. We'd like to see clearer user demand for this.

We'll be figuring out and documenting the contract migration strategy as part of FilOzone/filecoin-services#361

[BigLep]

@rvagg @jennijuju : can we fill in more of the details about this work (or add pointers about where this is discussed more)?

[nijoe1]

Cross-Chain Operator Approval Problem

Summary

FilecoinPayV1 operator approval relies on msg.sender, which in cross-chain scenarios is the bridge contract—not the user.

Background

FOC requires two on-chain operations to start storing files:

1. Deposit - Fund user's FilecoinPay balance
2. Approve Operator - Authorize service to spend on user's behalf

Technical Issue

// https://github.com/FilOzone/filecoin-pay/blob/main/src/FilecoinPayV1.sol#L359
OperatorApproval storage approval = operatorApprovals[token][msg.sender][operator];

Context	msg.sender	Intended Approver	Result
Direct call	User wallet	User wallet	Correct
Cross-chain	Bridge contract	User wallet	Incorrect

User Impact

1. User initiates cross-chain deposit via Axelar/Squid/OnlySwaps
2. Deposit succeeds (deposit() has a to parameter)
3. Operator approval fails—user must acquire FIL and submit manually

Conclusion

Signature-based operator approval is required for seamless cross-chain onboarding without FIL.

[nijoe1]

Potential Solution

Summary

Implement signature-based operator approval using EIP-712, allowing cross-chain bridges to execute approvals on behalf of users by recovering the signer address.

Approach

Replace msg.sender dependency with signature verification.

Implementation

1. Storage Additions

bytes32 public constant OPERATOR_APPROVAL_TYPEHASH = keccak256(
    "OperatorApproval(address token,address operator,bool approved,uint256 rateAllowance,uint256 lockupAllowance,uint256 maxLockupPeriod,uint256 nonce,uint256 deadline)"
);

mapping(address => uint256) public approvalNonces;

2. Refactor Internal Function

The existing _setOperatorApproval uses msg.sender. Add a new internal function with explicit client parameter:

function _setOperatorApprovalFor(
    IERC20 token,
    address client,
    address operator,
    bool approved,
    uint256 rateAllowance,
    uint256 lockupAllowance,
    uint256 maxLockupPeriod
) internal {
    OperatorApproval storage approval = operatorApprovals[token][client][operator];

    approval.isApproved = approved;
    approval.rateAllowance = rateAllowance;
    approval.lockupAllowance = lockupAllowance;
    approval.maxLockupPeriod = maxLockupPeriod;

    emit OperatorApprovalUpdated(
        token, client, operator, approved, rateAllowance, lockupAllowance, maxLockupPeriod
    );
}

// Existing function delegates to new internal function
function _setOperatorApproval(
    IERC20 token,
    address operator,
    bool approved,
    uint256 rateAllowance,
    uint256 lockupAllowance,
    uint256 maxLockupPeriod
) internal {
    _setOperatorApprovalFor(token, msg.sender, operator, approved, rateAllowance, lockupAllowance, maxLockupPeriod);
}

3. New Signature-Based Function

function setOperatorApprovalWithSignature(
    IERC20 token,
    address client,
    address operator,
    bool approved,
    uint256 rateAllowance,
    uint256 lockupAllowance,
    uint256 maxLockupPeriod,
    uint256 deadline,
    uint8 v,
    bytes32 r,
    bytes32 s
) external nonReentrant validateNonZeroAddress(operator, "operator") {
    require(block.timestamp <= deadline, "Expired");

    bytes32 digest = _hashTypedDataV4(keccak256(abi.encode(
        OPERATOR_APPROVAL_TYPEHASH,
        address(token),
        operator,
        approved,
        rateAllowance,
        lockupAllowance,
        maxLockupPeriod,
        approvalNonces[client]++,
        deadline
    )));

    require(ECDSA.recover(digest, v, r, s) == client, "Invalid signature");

    _setOperatorApprovalFor(token, client, operator, approved, rateAllowance, lockupAllowance, maxLockupPeriod);
}

4. Bridge Contract Example

contract CrossChainOnboarder {
    IFilecoinPay public filecoinPay;
    IERC20 public USDFC;
    address public storageService; // FOC service operator

    struct OnboardParams {
        address user;
        uint256 depositAmount;
        uint256 rateAllowance;
        uint256 lockupAllowance;
        uint256 maxLockupPeriod;
        uint256 approvalDeadline;
        uint8 v;
        bytes32 r;
        bytes32 s;
    }

    function onboardUser(bytes calldata data) external {
        OnboardParams memory params = abi.decode(data, (OnboardParams));

        // Deposit funds to user's FilecoinPay balance
        filecoinPay.deposit(USDFC, params.user, params.depositAmount);

        // Approve operator using user's signature
        filecoinPay.setOperatorApprovalWithSignature(
            USDFC,
            params.user,
            storageService,
            true,
            params.rateAllowance,
            params.lockupAllowance,
            params.maxLockupPeriod,
            params.approvalDeadline,
            params.v,
            params.r,
            params.s
        );
    }
}

[rvagg]

^ This aligns with my current thinking about the issue here. Separate method that takes a 712 to get the same job done.
The only suggestion I have here is that maybe we should do this for depositWithPermitAndIncreaseOperatorApproval instead, so we don't have the two operations, that was the point of that method in the first place and the onboardUser example above is doing both but only really needs to do one.

Implementing it here isn't the hard bit though @nijoe1, if we commit to this, we can't do it in a vacuum and have to have some kind of basic working example that proves that it solves for the workflow so we're not just adding cruft that can't be used in practice. So if we do a draft here, would you be able to commit to coming up with a POC on calibnet that uses it to demonstrate its utility? Just getting the approvals and deposit part working, not anything with FWSS.

[jennijuju]

• needs to acquire fil is good
• I think getting more signal on axelar and squid plan to support usdfc and filecoin pay support (deploy bridge contract with main evm chains) will help us better prioritize this work
• with OnlySwap - they'd have to support gasless tx for this to take into effect for builders, right?

This is a breaking change and require a new version of Filecoin Pay contract. To do this for GA, we will need to

• figure out how to support different versions of filecoin pay in services and implement it
• figure out migration and implement it
• figure out how sdks and tools like FP dashboard can support multiple version of filecoin pay and implement it

All these work we need to have an idea on what's the upgrade trajectory is like before GA, but not necessarily required to get implemented for GA. Adding them to the scope will push GA by at least weeks.

We could only deploy this change on mainnet without upgrade calibration - but that's bad dev practise and causes discrepancies between testnet and mainnet for builders.

I also want to know who are the builders / partners that are building on calibration and is blocked by this to deploy on mainnet. I do think we need more product input here.

[trruckerfling]

eastore is moving onto mainnet in 1 week. can we use them as a live POC for this? we also have filify (fleek on FOC) on calibration.

they both provide storage on their platforms and require users to pay directly for their own storage, without any gas/fee management from the platform, which is what this flow is meant for.

if these 2 POCs resolve the ask above, can we proceed with a PR based on nick's proposal above?

[jennijuju]

eastore is moving onto mainnet in 1 week. can we use them as a live POC for this? we also have filify (fleek on FOC) on calibration.

AFAICT, they both have a native Filecoin pathway, which can go live on mainnet first. While we want to support seamless cross chain experience in near future, the value and the impact of fully native Filecoin dapps are equally meaningful, and it is common to require an user to get chains token to use its dapp.

Could you please elaborate more on what you meant by live POC?

Timeline wise, as mentioned above, this features will take more than the implementation in Filecoin Pay before any devs can use it in production.

[nijoe1]

I created a repo using a mock FilecoinPay contract on Filecoin mainnet using Squid I was able to make that onboarding script work!!!

Here is the repo : https://github.com/nijoe1/foc-cross-chain-onboarding

cc: @rvagg @jennijuju