@circle-fin/adapter-ethers-v6 1.7.0 → 1.8.1

package/index.d.ts

@@ -1812,12 +1812,14 @@ declare enum PermitType {
  * The Adapter Contract uses this to pull tokens from the user's wallet
  * using permit signatures instead of requiring separate approval transactions.
  *
+ * Shared by the `swap.*` and `earn.*` action namespaces because both forward
+ * `tokenInputs` unchanged to the adapter contract's `execute` call.
+ *
  * @example
  * ```typescript
  * const tokenInput: TokenInput = {
  *   permitType: PermitType.EIP2612,
  *   token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
- *   from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  *   amount: 1000000n, // 1 USDC
  *   permitCalldata: '0x...' // Encoded permit(value, deadline, v, r, s)
  * }
@@ -1840,12 +1842,91 @@ interface TokenInput {
      * ABI-encoded permit calldata.
      *
      * For EIP-2612: encode(value, deadline, v, r, s)
-     * For Permit2: encode(permit, signature)
      *
      * @example '0x0000000000000000000000000000000000000000000000000000000000989680...'
      */
     permitCalldata: `0x${string}`;
 }
+
+/**
+ * Parameters for executing a service-signed earn operation via the Adapter
+ * smart contract on EVM chains.
+ *
+ * Shared across earn action keys: `earn.deposit`, `earn.withdraw`, and
+ * `earn.claimRewards`. Each operation forwards the same `executeParams`,
+ * `tokenInputs`, and `signature` triple to the adapter contract's `execute`
+ * function. The service signs `executeParams` off-chain; the contract verifies
+ * the signature on-chain.
+ *
+ * @example
+ * ```typescript
+ * import type { ActionPayload } from '@core/adapter'
+ *
+ * const params: ActionPayload<'earn.deposit'> = {
+ *   executeParams: { instructions: [], tokens: [], execId: 1n, deadline: 0n, metadata: '0x' },
+ *   tokenInputs: [],
+ *   signature: '0x...',
+ * }
+ *
+ * const prepared = await adapter.prepareAction('earn.deposit', params, { chain, address })
+ * const txHash = await prepared.execute()
+ * ```
+ */
+interface ExecuteEarnEVMParams extends ActionParameters {
+    /**
+     * Execution parameters returned by the earn service.
+     *
+     * Kept as an opaque record so the adapter forwards the service-signed struct
+     * unchanged. The adapter contract ABI decodes it on-chain.
+     */
+    executeParams: Record<string, unknown>;
+    /**
+     * Token inputs with permit signatures for gasless approvals.
+     *
+     * Populated by the earn provider after it decides how token spending is
+     * authorised. Today deposit uses a separate `token.approve` transaction and
+     * passes `PermitType.NONE`; a future permit-enabled path can populate this
+     * field without a breaking change.
+     */
+    tokenInputs: TokenInput[];
+    /**
+     * EIP-712 signature from the earn service proxy.
+     *
+     * The adapter contract verifies this signature on-chain. Passed through
+     * unchanged.
+     */
+    signature: `0x${string}`;
+}
+/**
+ * Parameters for earn execute actions across supported ecosystems.
+ *
+ * EVM-only today; becomes a union when a non-EVM adapter implementation
+ * lands. Action handlers narrow via a property-based type guard, same
+ * pattern as {@link ExecuteSwapParams}.
+ */
+type ExecuteEarnParams = ExecuteEarnEVMParams;
+/**
+ * Action map for earn operations.
+ *
+ * Each action key forwards the same `(executeParams, tokenInputs, signature)`
+ * triple to the adapter contract. Provider-side orchestration performs any
+ * required token approval; this action only prepares the adapter execute call.
+ */
+interface EarnActionMap {
+    /**
+     * Execute a service-signed deposit against the adapter contract.
+     */
+    readonly deposit: ExecuteEarnParams;
+    /**
+     * Execute a service-signed withdraw against the adapter contract.
+     */
+    readonly withdraw: ExecuteEarnParams;
+    /**
+     * Execute a service-signed claim rewards against the adapter contract.
+     */
+    readonly claimRewards: ExecuteEarnParams;
+}
+
 /**
  * Single instruction to execute within the Adapter Contract.
  *
@@ -2027,7 +2108,6 @@ interface ExecuteParams {
  * const tokenInputs: TokenInput[] = [{
  *   permitType: PermitType.EIP2612,
  *   token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
- *   from: userAddress,
  *   amount: 1000000n,
  *   permitCalldata: '0x...' // Encoded permit signature
  * }]
@@ -2070,7 +2150,6 @@ interface ExecuteSwapEVMParams extends ActionParameters {
      * [{
      *   permitType: PermitType.EIP2612,
      *   token: '0xUSDC',
-     *   from: userAddress,
      *   amount: 1000000n,
      *   permitCalldata: '0x...'
      * }]
@@ -2806,6 +2885,8 @@ interface ActionMap {
     readonly usdt: USDTActionMap;
     /** Swap operations for DEX aggregator integrations. */
     readonly swap: SwapActionMap;
+    /** Earn operations that execute service-signed payloads via the adapter contract. */
+    readonly earn: EarnActionMap;
 }
 /**
  * Determine if a type represents an action parameter object (leaf node).
@@ -3974,6 +4055,37 @@ declare abstract class EvmAdapter<TAdapterCapabilities extends AdapterCapabiliti
      * @throws Error when balance retrieval fails.
      */
     abstract readNativeBalance(address: string, chain: EVMChainDefinition): Promise<bigint>;
+    /**
+     * Reads the on-chain bytecode for a given address.
+     *
+     * Returns the deployed contract bytecode as a hex string (`0x`-prefixed),
+     * or `'0x'` when the address has no code (i.e. is a plain EOA).
+     * Implementations MUST normalize a "no code" RPC response to `'0x'` so
+     * callers can compare against a single sentinel.
+     *
+     * Useful for detecting smart-contract accounts before attempting an
+     * operation that only supports EOA signing (e.g. Gateway burn intents).
+     *
+     * @param address - The address to read bytecode for.
+     * @param chain - The chain definition to read from.
+     * @returns Promise resolving to `'0x'` for an EOA, or the hex-encoded
+     *   deployed bytecode otherwise.
+     * @throws Error when the underlying RPC call fails.
+     *
+     * @example
+     * ```typescript
+     * import { ViemAdapter } from '@circle-fin/adapter-viem-v2'
+     * import { Ethereum } from '@core/chains'
+     *
+     * const adapter = new ViemAdapter({ publicClient, walletClient })
+     * const code = await adapter.readBytecode('0xabc...', Ethereum)
+     *
+     * if (code !== '0x') {
+     *   throw new Error('signer has on-chain bytecode')
+     * }
+     * ```
+     */
+    abstract readBytecode(address: string, chain: EVMChainDefinition): Promise<`0x${string}`>;
     /**
      * Calculate the total transaction fee including compute cost and buffer for the configured chain.
      *
@@ -4573,6 +4685,15 @@ declare class EthersAdapter<TAdapterCapabilities extends AdapterCapabilities = A
      * ```
      */
     readNativeBalance(address: string, chain: EVMChainDefinition): Promise<bigint>;
+    /**
+     * Reads the on-chain bytecode for a given address via ethers' `getCode`.
+     *
+     * Returns the hex-encoded bytecode when the address is a contract, or
+     * `'0x'` when the address has no code (EOA). Used by Gateway burn-intent
+     * signing to detect smart-contract accounts, which are not supported by
+     * Gateway's ecrecover-based verification path.
+     */
+    readBytecode(address: string, chain: EVMChainDefinition): Promise<`0x${string}`>;
     /**
      * Signs EIP-712 typed data using the configured signer with OperationContext.
      *