@compass-labs/api-sdk 2.1.11 → 2.1.12-rc.0

package/docs/sdks/bridge/README.md

@@ -0,0 +1,222 @@
+# Bridge
+(*bridge*)
+
+## Overview
+
+### Available Operations
+
+* [cctpBurn](#cctpburn) - Initiate USDC bridging
+* [cctpMint](#cctpmint) - Complete USDC bridging
+
+## cctpBurn
+
+Bridge USDC from any Product account to any chain using Circle's CCTP Protocol.
+
+**Transfer modes:**
+- `standard` (default): ~15-19 minute transfers, **free** (no fee)
+- `fast`: ~30 second transfers, requires a small fee (typically ~0.01%)
+
+The fee for fast mode is automatically calculated based on Circle's current rates.
+
+**Flow:**
+1. Call this endpoint with `gas_sponsorship=false` to get an unsigned transaction,
+   or `gas_sponsorship=true` to get EIP-712 typed data for gas-sponsored execution
+2. Owner signs the transaction or typed data
+3. Broadcast the transaction on the source chain (or submit to `/gas_sponsorship/prepare`)
+4. Wait for Circle's attestation service to attest the burn
+5. Call the mint endpoint to receive USDC on the destination chain 
+
+**Supported chains:**
+- Ethereum (domain 0)
+- Arbitrum (domain 3)
+- Base (domain 6)
+
+**Note:** The USDC must already be deposited in the Product Account. If approval is needed
+for the TokenMessengerV2 contract, it will be included in the transaction automatically.
+
+### Example Usage
+
+<!-- UsageSnippet language="typescript" operationID="v2_cctp_burn" method="post" path="/v2/cctp/burn" -->
+```typescript
+import { CompassApiSDK } from "@compass-labs/api-sdk";
+
+const compassApiSDK = new CompassApiSDK({
+  apiKeyAuth: "<YOUR_API_KEY_HERE>",
+});
+
+async function run() {
+  const result = await compassApiSDK.bridge.cctpBurn({
+    owner: "0x01E62835dd7F52173546A325294762143eE4a882",
+    chain: "arbitrum",
+    amount: "3",
+    destinationChain: "base",
+    gasSponsorship: true,
+    transferMode: "standard",
+  });
+
+  console.log(result);
+}
+
+run();
+```
+
+### Standalone function
+
+The standalone function version of this method:
+
+```typescript
+import { CompassApiSDKCore } from "@compass-labs/api-sdk/core.js";
+import { bridgeCctpBurn } from "@compass-labs/api-sdk/funcs/bridgeCctpBurn.js";
+
+// Use `CompassApiSDKCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const compassApiSDK = new CompassApiSDKCore({
+  apiKeyAuth: "<YOUR_API_KEY_HERE>",
+});
+
+async function run() {
+  const res = await bridgeCctpBurn(compassApiSDK, {
+    owner: "0x01E62835dd7F52173546A325294762143eE4a882",
+    chain: "arbitrum",
+    amount: "3",
+    destinationChain: "base",
+    gasSponsorship: true,
+    transferMode: "standard",
+  });
+  if (res.ok) {
+    const { value: result } = res;
+    console.log(result);
+  } else {
+    console.log("bridgeCctpBurn failed:", res.error);
+  }
+}
+
+run();
+```
+
+### Parameters
+
+| Parameter                                                                                                                                                                      | Type                                                                                                                                                                           | Required                                                                                                                                                                       | Description                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `request`                                                                                                                                                                      | [components.DepositForBurnRequest](../../models/components/depositforburnrequest.md)                                                                                           | :heavy_check_mark:                                                                                                                                                             | The request object to use for the request.                                                                                                                                     |
+| `options`                                                                                                                                                                      | RequestOptions                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                             | Used to set various options for making HTTP requests.                                                                                                                          |
+| `options.fetchOptions`                                                                                                                                                         | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options)                                                                                        | :heavy_minus_sign:                                                                                                                                                             | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
+| `options.retries`                                                                                                                                                              | [RetryConfig](../../lib/utils/retryconfig.md)                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                             | Enables retrying HTTP requests under certain failure conditions.                                                                                                               |
+
+### Response
+
+**Promise\<[components.DepositForBurnResponse](../../models/components/depositforburnresponse.md)\>**
+
+### Errors
+
+| Error Type                 | Status Code                | Content Type               |
+| -------------------------- | -------------------------- | -------------------------- |
+| errors.HTTPValidationError | 422                        | application/json           |
+| errors.APIError            | 4XX, 5XX                   | \*/\*                      |
+
+## cctpMint
+
+Prepare a receiveMessage transaction to mint USDC to any Product Account on the
+destination chain.
+
+**How it works:**
+
+This endpoint uses the `bridge_id` from `/burn` to:
+1. Look up the bridge session
+2. Check if Circle's attestation is ready
+3. Depending on the status of the attestation return the following:
+    - if attestation is still pending, return URLs for real-time updates
+    - if attestation is ready, return a transaction to complete the bridging process
+    - if the minting for a given `bridge_id` has been completed, informs with `completed` status
+
+**Request parameters:**
+
+- `bridge_id`: The bridge ID returned from `/burn`
+- `burn_tx_hash`: The transaction hash of the burn transaction on the source chain
+
+**Response codes:**
+
+- **200 OK**: Attestation is ready, mint transaction is included
+- **202 Accepted**: Attestation is pending, SSE URL for real-time updates is included (The real-time update endpoints are in progress)
+- **404 Not found**: Bridge not found
+
+**After receiving 202:**
+
+Either:
+- Connect to the SSE stream at `sse_url` and wait for `attestation_ready` event (The SSE stream and status endpoint are in progress. Keep an eye on the updates from our team)
+- Poll this endpoint periodically until you get 200
+
+### Example Usage
+
+<!-- UsageSnippet language="typescript" operationID="v2_cctp_mint" method="post" path="/v2/cctp/mint" -->
+```typescript
+import { CompassApiSDK } from "@compass-labs/api-sdk";
+
+const compassApiSDK = new CompassApiSDK({
+  apiKeyAuth: "<YOUR_API_KEY_HERE>",
+});
+
+async function run() {
+  const result = await compassApiSDK.bridge.cctpMint({
+    bridgeId: "br_cae305798062",
+    burnTxHash: "0x42c914b870eacc2c1734420f6ab183f95a5b0e0fdbb1c82247183848b76fc8ad",
+    sender: "0x29F20a192328eF1aD35e1564aBFf4Be9C5ce5f7B",
+  });
+
+  console.log(result);
+}
+
+run();
+```
+
+### Standalone function
+
+The standalone function version of this method:
+
+```typescript
+import { CompassApiSDKCore } from "@compass-labs/api-sdk/core.js";
+import { bridgeCctpMint } from "@compass-labs/api-sdk/funcs/bridgeCctpMint.js";
+
+// Use `CompassApiSDKCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const compassApiSDK = new CompassApiSDKCore({
+  apiKeyAuth: "<YOUR_API_KEY_HERE>",
+});
+
+async function run() {
+  const res = await bridgeCctpMint(compassApiSDK, {
+    bridgeId: "br_cae305798062",
+    burnTxHash: "0x42c914b870eacc2c1734420f6ab183f95a5b0e0fdbb1c82247183848b76fc8ad",
+    sender: "0x29F20a192328eF1aD35e1564aBFf4Be9C5ce5f7B",
+  });
+  if (res.ok) {
+    const { value: result } = res;
+    console.log(result);
+  } else {
+    console.log("bridgeCctpMint failed:", res.error);
+  }
+}
+
+run();
+```
+
+### Parameters
+
+| Parameter                                                                                                                                                                      | Type                                                                                                                                                                           | Required                                                                                                                                                                       | Description                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `request`                                                                                                                                                                      | [components.MintPrepareRequest](../../models/components/mintpreparerequest.md)                                                                                                 | :heavy_check_mark:                                                                                                                                                             | The request object to use for the request.                                                                                                                                     |
+| `options`                                                                                                                                                                      | RequestOptions                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                             | Used to set various options for making HTTP requests.                                                                                                                          |
+| `options.fetchOptions`                                                                                                                                                         | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options)                                                                                        | :heavy_minus_sign:                                                                                                                                                             | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
+| `options.retries`                                                                                                                                                              | [RetryConfig](../../lib/utils/retryconfig.md)                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                             | Enables retrying HTTP requests under certain failure conditions.                                                                                                               |
+
+### Response
+
+**Promise\<[operations.V2CctpMintResponse](../../models/operations/v2cctpmintresponse.md)\>**
+
+### Errors
+
+| Error Type                              | Status Code                             | Content Type                            |
+| --------------------------------------- | --------------------------------------- | --------------------------------------- |
+| errors.MintPrepareNotFoundResponseError | 404                                     | application/json                        |
+| errors.HTTPValidationError              | 422                                     | application/json                        |
+| errors.APIError                         | 4XX, 5XX                                | \*/\*                                   |