Add an explicit EVM contract-call capability to App Kit

[gaysonloser]

Summary

Please consider adding a distinct EVM contract-call capability to App Kit.

The current SendParams interface in @circle-fin/app-kit@1.10.0 supports from, to, amount, and optional token, but it cannot express a payable EVM function call with calldata. This blocks payment applications whose settlement and application state must remain atomic.

Concrete Arc Testnet use case

Payment Receipt uses a verified Arc Testnet contract with:

pay(bytes32 orderId, bytes32 metadataHash)

The call accepts native USDC, transfers it to the merchant, stores an application receipt, rejects duplicate order IDs, and emits PaymentReceived in one transaction.

• Verified contract: https://testnet.arcscan.app/address/0x05fd366E0F1Af3C5DCDCdC88ED8824bbf175E1Df
• Live read-only evidence viewer: https://arc-payment-receipt.onrender.com/
• Function selector: 0x91f8a6db

A correct payment must carry that selector, two ABI-encoded bytes32 arguments, and native value together.

Current behavior

The closest documented App Kit operation is:

await kit.send({
  from: { adapter, chain: "Arc_Testnet" },
  to: paymentReceipt,
  amount: "0.01",
  token: "NATIVE",
});

This transfers value without the required selector or arguments. The current contract intentionally has no receive or fallback, so a bare transfer to it reverts. Sending directly to the merchant can move funds, but bypasses receipt storage, duplicate-order protection, and the PaymentReceived event.

The application therefore uses a custom pay() call for settlement and keeps Circle Contracts/Event Monitor plus an independent RPC monitor as read-only evidence sources.

Expected capability

A separate EVM contract-call operation could accept source adapter/chain, target, calldata, and native value, with matching estimation and explicit wallet confirmation. A typed ABI/function/args convenience layer could sit above the raw call.

I am not suggesting that send() silently reinterpret token transfers as arbitrary contract calls; a distinct capability would keep the API boundary clear.

Suggested acceptance criteria

1. An EVM browser-wallet adapter can estimate and submit one call containing to, data, and native value.
2. The wallet displays normal user confirmation; App Kit never signs or submits silently.
3. Reverts are surfaced as failures and do not produce a false success state.
4. The result exposes the transaction hash and explorer URL consistently with existing operations.
5. The capability is documented as EVM-only where other adapters cannot provide equivalent semantics.

Environment

• @circle-fin/app-kit@1.10.0
• Arc Testnet, chain ID 5042002
• Browser EVM wallet / Viem-style contract call

This is a feature request based on a reproducible Arc Testnet payment flow, not a claim that the existing Send capability is broken.

[osr21]

I have been building on Arc Testnet with CCTP and can independently verify the technical premises here, and add a workaround for anyone who needs this today.

Independent verification

I checked the contract and the claimed selector against the live Arc Testnet state:

Claim	Result
keccak256("pay(bytes32,bytes32)") = 0x91f8a6db	✓ confirmed
Contract deployed at 0x05fd366...	✓ 914 bytes, selector present in bytecode
No receive / fallback	✓ confirmed from source and on-chain — bare call reverts
pay() with zero value reverts	✓ execution reverted (ZeroPayment path reached — dispatcher routes correctly)

The contract source is also public on GitHub. The pay() function is external payable, stores an immutable receipt keyed by orderId, forwards the full msg.value to the merchant in the same transaction, and emits PaymentReceived. A bare value transfer without the selector reverts at the ABI dispatcher — there is no receive or fallback handler. The reporter's description of the atomicity constraint is accurate.

App Kit 1.10.0 has no current escape hatch

I inspected the type surface of the published tarball. The exported paths are bridge, swap, earn, estimateBridge, estimateSwap, unifiedBalance, chains, and context. There is no execute, call, sendTransaction, or similar export, and the adapter types do not expose the underlying provider directly. The gap described in the issue exists as stated.

Workaround for today

App Kit establishes the wallet session but does not prevent direct use of the underlying window.ethereum provider. After kit.connect() or equivalent has been called, a parallel ethers.js call works without interfering with the App Kit session:

import { BrowserProvider, Interface, parseEther } from 'ethers';

const CONTRACT = '0x05fd366E0F1Af3C5DCDCdC88ED8824bbf175E1Df';
const iface = new Interface([
  'function pay(bytes32 orderId, bytes32 metadataHash) payable'
]);

async function payOrder(
  orderId: `0x${string}`,
  metadataHash: `0x${string}`,
  amountNative: string,  // in Arc native denomination
) {
  const provider = new BrowserProvider(window.ethereum);
  const signer = await provider.getSigner();

  const data = iface.encodeFunctionData('pay', [orderId, metadataHash]);
  const value = parseEther(amountNative);

  // eth_estimateGas must include both data and value — a plain transfer
  // estimate (no data) will underestimate for a contract call and may revert.
  const gasLimit = await provider.estimateGas({ to: CONTRACT, data, value });

  const tx = await signer.sendTransaction({
    to: CONTRACT,
    data,
    value,
    gasLimit: gasLimit * 120n / 100n,  // 20% headroom; Arc gas is sometimes tight
  });
  const receipt = await tx.wait();
  if (!receipt || receipt.status !== 1) throw new Error(`Pay reverted: ${tx.hash}`);
  return { txHash: tx.hash, receipt };
}

The wallet shows the normal confirmation prompt; nothing is signed or submitted silently. This is a workaround, not a substitute for a first-class SDK capability — it requires consumers to manage the ethers.js dependency separately and bypasses any App Kit telemetry or error normalisation.

One implementation note for the feature

The existing send() path estimates gas with { to, value } — no data field — because simple USDC transfers have a known gas cost. A contract-call capability must pass { to, data, value } to eth_estimateGas, otherwise the estimate is for an empty-data transfer and will underestimate (or overestimate) the actual execution cost. This is the main implementation difference between send() and a new executeContract() at the estimation layer.