feat: created Circle Gateway helper

README.md

@@ -32,6 +32,9 @@ By doing near mainnet testing, developers can quickly check sender authenticatio
 | CCIP      |      ✅      | ✅  |
 | a.DI      |      ✅      |    |
 | Arbitrum (native) |      ✅      |    |
+| Relay     |      ✅      |    |
+| CCTP V2   |      ✅      |    |
+| Circle Gateway |      ✅      |    |
 ## Getting Started
 
 ### Installation
@@ -114,6 +117,28 @@ adiHelper.helpMultiBridge(AdiHelper.MultiBridgeArgs({
 
 **AMB endpoint addresses**: read each deployed adapter's configured AMB endpoint via its public getter (`HL_MAIL_BOX()`, `LZ_ENDPOINT()`, `getRouter()`) and pass that to `MultiBridgeArgs`. Do NOT hardcode canonical AMB addresses — deployments may use custom AMB infrastructure (different validator sets / ISMs / etc.).
 
+Circle Gateway (unified USDC balance — there is NO source-chain message to relay; the helper plays Circle's attestation signer):
+
+```solidity
+CircleGatewayHelper gw = new CircleGatewayHelper(0); // 0 = default test signer key; persistent across forks
+
+// optional source-side realism: fund + deposit into GatewayWallet on the source fork
+gw.helpDeposit(ETH_FORK_ID, ETH_USDC, depositor, 1000e6);
+
+// describe the transfer (Gateway domains: Ethereum 0, Avalanche 1, OP 2, Arbitrum 3, Base 6, Polygon 7, ...)
+CircleGatewayHelper.TransferSpec memory spec =
+    gw.buildSpec(0, 3, ETH_USDC, ARB_USDC, depositor, recipient, destinationCaller, 1000e6, hookData);
+
+// mint on the destination fork through the REAL GatewayMinter (pranked as destinationCaller when set)
+CircleGatewayHelper.Attested memory a = gw.help(ARB_FORK_ID, spec);
+// or hand the signed payload to a destination adapter that calls gatewayMint itself
+gw.helpMintViaAdapter(ARB_FORK_ID, address(adapter), spec);
+// or just attest and drive gatewayMint yourself (optionally with an explicit maxBlockHeight)
+a = gw.helpAttest(ARB_FORK_ID, spec);
+```
+
+`helpSet` / `helpMintViaAdapterSet` / `helpAttestSet` use the `AttestationSet` wire format (several specs, one atomic mint; a set of one stays a set). `a.transferSpecHashes` are the minter's replay keys (`isTransferSpecHashUsed`). Attestations are EIP-191 (`personal_sign` over `keccak256(payload)`), valid through 1000 blocks from the destination fork's block by default; the minter's own checks (signer, expiry, domain, caller, token, replay, denylist, pause) all run for real. A reverting destination call restores your previously selected fork before re-raising.
+
 To display estimations, run the `npm install` and `npm run compile` commands from the [utils/scripts directory](./utils/scripts) before running your tests. Then run tests with the `--ffi` flag and `ENABLE_ESTIMATES` env variable set to `true.`
 
 **Gas estimation** is the gas costs required in native tokens to pay for the message delivery.

src/circle-gateway/interfaces/IERC20.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.0;
+
+interface IERC20 {
+    function balanceOf(address account) external view returns (uint256);
+    function approve(address spender, uint256 amount) external returns (bool);
+    function transfer(address to, uint256 amount) external returns (bool);
+}

src/circle-gateway/interfaces/IGatewayAttestationReceiver.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.0;
+
+/// @notice a destination contract that consumes a Gateway attestation itself (e.g. Superform's
+///         CircleGatewayAdapter): it calls GatewayMinter.gatewayMint and acts on the TransferSpec's hookData
+interface IGatewayAttestationReceiver {
+    function receiveAndExecute(bytes calldata attestationPayload, bytes calldata signature) external;
+}

src/circle-gateway/interfaces/IGatewayMinter.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.0;
+
+/// @notice the GatewayMinter surface the helper and its tests use
+/// @dev proxy at 0x2222222d7164433c4C09B0b0D809a9b52C04C205 on every Gateway chain
+interface IGatewayMinter {
+    function gatewayMint(bytes calldata attestationPayload, bytes calldata signature) external;
+    function owner() external view returns (address);
+    function isAttestationSigner(address signer) external view returns (bool);
+    function addAttestationSigner(address signer) external;
+    function isTransferSpecHashUsed(bytes32 transferSpecHash) external view returns (bool);
+}

src/circle-gateway/interfaces/IGatewayWallet.sol

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.0;
+
+/// @notice the GatewayWallet surface the helper and its tests use
+/// @dev proxy at 0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE on every Gateway chain
+interface IGatewayWallet {
+    function deposit(address token, uint256 value) external;
+    function availableBalance(address token, address depositor) external view returns (uint256);
+}