GITBOOK-65: add withdrawal flow to usdcx guide

eric-stacks · gitbook-bot · commit b029f0fe39c2 · 2026-01-18T23:59:28.000Z
diff --git a/docs/build/README.md b/docs/build/README.md
@@ -33,64 +33,44 @@ If you're here on this page, hopefully you've already gotten a good sense of _wh
 
 The Stacks documentation is organized into a set of top-level sections, each aligned to a distinct stage of a developer’s journey—from learning core concepts to building applications and operating infrastructure.
 
-<details>
-
-<summary><strong>Learn</strong></summary>
-
-**How does the Stacks network work?**\
-The [Learn](https://app.gitbook.com/s/H74xqoobupBWwBsVMJhK/) section focuses on building a strong conceptual foundation. It explains how Stacks functions as a Bitcoin layer 2, providing clarity and context around the network’s design and mechanics.
+{% tabs %}
+{% tab title="Learn" %}
+**How does the Stacks network&#x20;**_**actually**_**&#x20;work?**\
+The [Learn](https://app.gitbook.com/s/H74xqoobupBWwBsVMJhK/) section focuses on building a strong academic foundation. It explains how Stacks functions as a Bitcoin layer 2, providing clarity and context around the network’s design and mechanics.
 
 Topics include Proof of Transfer (PoX), Bitcoin finality, block production, the transaction lifecycle, and more. If you want a deep understanding of how Stacks anchors to Bitcoin and why it works the way it does, this is the best place to start.
+{% endtab %}
 
-</details>
-
-<details>
-
-<summary><strong>Build</strong></summary>
-
+{% tab title="Build" %}
 **How do you build on Stacks?**\
-The Build section (you're on it!) is for developers—both new and experienced—who want to start writing, deploying, and interacting with Stacks applications.
+This section is for experienced developers, but are new to Stacks, who are in the exploratory phase of understanding the general workflow of building apps on Stacks. These guides focus on accomplishing specific tasks—writing contracts, integrating wallets, working with sBTC or USDC—without extensive explainers.
 
 It includes curated quick starts for smart contract development with Clarinet and frontend development with Stacks.js, along with step-by-step guides covering common use cases such as integrating sBTC, onboarding users, working with price oracles, and more.
+{% endtab %}
 
-If you’re new to building on Stacks, this section provides a practical, hands-on introduction to the ecosystem.
-
-</details>
-
-<details>
-
-<summary><strong>Operate</strong></summary>
-
+{% tab title="Operate" %}
 **How do you run Stacks infrastructure?**\
 The [Operate](https://app.gitbook.com/s/4cpTb2lbw0LAOuMHrvhA/) section is designed for node operators and infrastructure providers. It covers how to run and manage Stacks nodes, signers, and miners.
 
 If you’re responsible for operating or maintaining Stacks-related infrastructure, this section contains the resources you’ll need.
+{% endtab %}
 
-</details>
-
-<details>
-
-<summary><strong>Reference</strong></summary>
-
+{% tab title="Reference" %}
 **Where do you look up technical details?**\
 The [Reference](https://app.gitbook.com/s/GVj1Z9vMuEOMe7oH7Wnq/node-operations/readme) section contains authoritative technical documentation for Stacks devtools and APIs. This includes function and type definitions for Clarity and Stacks.js, API endpoint schemas, and interactive API playgrounds.
 
 If you’re an experienced Stacks developer looking to quickly reference a specific method, type, or API response, this section is built for fast lookup and precision.
+{% endtab %}
 
-</details>
-
-<details>
-
-<summary><strong>Tutorials</strong></summary>
-
-**Looking for a more guided, learning-first experience?**\
-The [Tutorials](https://app.gitbook.com/s/skGYu79qDNfITOqDNU3s/) section is designed for readers who want structured, long-form lessons rather than quick answers.
+{% tab title="Tutorials" %}
+**Looking for a more guided, lesson-oriented experience?**\
+The [Tutorials](https://app.gitbook.com/s/skGYu79qDNfITOqDNU3s/) section is designed for complete beginner developers who want structured, long-form lessons rather than quick answers.
 
 These tutorials provide step-by-step walkthroughs alongside in-depth explanations of the underlying concepts. The goal isn’t just to help you complete a task, but to help you understand _why_ things work the way they do as you build.
 
-If you’re completely new to Stacks—or prefer a classroom-style, concept-driven learning experience—this section is the best place to start.
-
-</details>
+If you’re a complete beginner and prefer a classroom-style, concept-driven learning experience—this section is the best place to start.
+{% endtab %}
+{% endtabs %}
 
 ***
 
diff --git a/docs/build/more-guides/bridging-usdcx.md b/docs/build/more-guides/bridging-usdcx.md
@@ -25,49 +25,58 @@ Current work is underway to abstract this entire flow via Circle's Bridge Kit SD
 5. Approve xReserve as a spender of your USDC.
 6. Execute deposit to the remote chain Stacks.
 
+**Withdrawal**
+
+1. Prepare contract call arguments
+2. Invoke `burn` function from the `.usdcx-v1` contract
+
 ### Key Tools To Use
 
 * [viem](https://viem.sh/) - A Typescript-first library that interfaces with Ethereum.
 * [stacks.js](/broken/pages/dH5waQhE6Vb7rhcrUG7z) - A js library that helps developers build Stacks apps by handling transactions, wallet authentication, and smart contract interactions.
+* [Circle Faucet](https://faucet.circle.com/) - Get testnet USDC
+* [Ethereum Sepolia faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia) - Get testnet ETH
 
 ***
 
 ## Complete Code
 
 If you want to jump straight to the full implementation, the complete working code used in this guide is shown below.
 
-#### Deposit
-
 {% tabs %}
 {% tab title="index.ts" %}
 This script bridges USDC from Ethereum Sepolia testnet to Stacks testnet by first approving the xReserve contract to spend USDC, then calling `depositToRemote` to initiate the cross-chain transfer. It encodes the Stacks recipient address into the bytes32 format required by the Ethereum contract and submits both transactions to the Sepolia network. The Stacks attestation service will receive this event and mint the equivalent amount to the specified Stacks address.
 
-{% code expandable="true" %}
-```typescript
-import "dotenv/config";
+<pre class="language-typescript" data-expandable="true"><code class="lang-typescript">import "dotenv/config";
 import {
   createWalletClient,
   createPublicClient,
   http,
   parseUnits,
+  pad
 } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { sepolia } from "viem/chains";
 import { bytes32FromBytes, remoteRecipientCoder } from "./helpers";
+import { makeContractCall, Cl, Pc, broadcastTransaction } from '@stacks/transactions'
 
 // ============ Configuration constants ============
 const config = {
   // Public Ethereum Sepolia RPC and your private wallet key
   ETH_RPC_URL: process.env.RPC_URL || "https://ethereum-sepolia.publicnode.com",
-  PRIVATE_KEY: process.env.PRIVATE_KEY, 
+  PRIVATE_KEY: process.env.ETHEREUM_PRIVATE_KEY, 
 
   // Contract addresses on testnet
   X_RESERVE_CONTRACT: "008888878f94C0d87defdf0B07f46B93C1934442",
   ETH_USDC_CONTRACT: "1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+  STACKS_USDC:
+    "0x00000000061a6d78de7b0625dfbfc16c3a8a5735f6dc3dc3f2ce057573646378",
 
   // Deposit parameters for Stacks
   STACKS_DOMAIN: 10003, // Stacks domain ID
+  ETHEREUM_DOMAIN: 0, // Ethereum domain ID
   STACKS_RECIPIENT: "ST1F1M4YP67NV360FBYR28V7C599AC46F8C4635SH", // Address to receive minted USDCx on Stacks
+  ETHEREUM_RECIPIENT: "9F685cc614148f35efC238F5DFC977e08ed6bA86", // Address to receive withdrawn USDC on Ethereum
   DEPOSIT_AMOUNT: "1.00",
   MAX_FEE: "0",
 };
@@ -111,8 +120,8 @@ const ERC20_ABI = [
 ];
 
 
-async function main() {
-  if (!config.PRIVATE_KEY) {
+<strong>async function deposit() {
+</strong>  if (!config.PRIVATE_KEY) {
     throw new Error("PRIVATE_KEY must be set in your .env file");
   }
 
@@ -165,7 +174,7 @@ async function main() {
       Number(usdcBalance) / 1e6
     ).toFixed(6)} USDC)`,
   );
-  if (usdcBalance < value) {
+  if (usdcBalance &#x3C; value) {
     throw new Error(
       `Insufficient USDC balance. Required: ${(Number(value) / 1e6).toFixed(
         6,
@@ -207,13 +216,33 @@ async function main() {
   );
 }
 
-// ============ Call the main function ============
-main().catch((error) => {
-  console.error("❌ Error:", error);
-  process.exit(1);
-});
-```
-{% endcode %}
+<strong>async function withdraw() {
+</strong>  let amount = 4800000 // in micro USDCx (6 decimals)
+
+  let functionArgs = [
+    Cl.uint(amount), // amount in micro USDC
+    Cl.uint(config.ETHEREUM_DOMAIN), // native domain for Ethereum
+    Cl.bufferFromHex(pad(`0x${config.ETHEREUM_RECIPIENT}`, { size: 32 })) // native recipient
+  ]
+
+  let postCondition_1 = Pc.principal(config.STACKS_RECIPIENT)
+    .willSendEq(amount)
+    .ft('ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx', 'usdcx-token')
+
+  let transaction = await makeContractCall({
+    contractName: 'usdcx-v1',
+    contractAddress: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
+    functionName: 'burn',
+    functionArgs,
+    network: 'testnet',
+    postConditions: [postCondition_1],
+    postConditionMode: 'deny',
+    senderKey: process.env.STACKS_PRIVATE_KEY,
+  })
+
+  let result = await broadcastTransaction({transaction, network: 'testnet'})
+}
+</code></pre>
 {% endtab %}
 
 {% tab title="helpers.ts" %}
@@ -275,8 +304,6 @@ Before beginning, make sure you:
 
 * Create a wallet on Ethereum Sepolia.
 * Create a Stacks testnet wallet.
-* Get testnet USDC from the [Circle Faucet](https://faucet.circle.com/).
-* Get testnet ETH from a public [Ethereum Sepolia faucet](https://cloud.google.com/application/web3/faucet/ethereum/sepolia).
 
 {% stepper %}
 {% step %}
@@ -590,3 +617,64 @@ These are example transactions on testnet:
 * Stacks: [Minting USDCx](https://explorer.hiro.so/txid/0x12ad17401bf89d1bb1489623203b489b059609187eae2c5cebb898a89bdb926f?chain=testnet\&tab=overview)
 {% endstep %}
 {% endstepper %}
+
+***
+
+## Walkthrough (Withdrawal)
+
+{% hint style="danger" %}
+**Limit:** Up to **50 burn intents per request** (max **10 per batch**, max **5 batches**). Submitting more than 50 intents in a single transaction request may lead to failed processing and **risk of fund loss**.
+{% endhint %}
+
+{% stepper %}
+{% step %}
+### Prepare contract call arguments
+
+Before invoking the `burn` function of the `.usdcx-v1` contract, you'll need to determine the amount of USDCx to withdraw and the native recipient address that'll receive the USDC on the other chain.
+
+An Ethereum address is technically only 20 bytes but the `native-recipient` needs to be a 32 byte buffer. Pad left the address to 32 bytes.
+
+```typescript
+let amount = 4800000 // in micro USDCx (6 decimals)
+
+let functionArgs = [
+  Cl.uint(amount), // amount in micro USDC
+  Cl.uint(config.ETHEREUM_DOMAIN), // native domain for Ethereum
+  Cl.bufferFromHex(pad(`0x${config.ETHEREUM_RECIPIENT}`, { size: 32 })) // native recipient
+]
+
+let postCondition_1 = Pc.principal(config.STACKS_RECIPIENT)
+  .willSendEq(amount)
+  .ft('ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.usdcx', 'usdcx-token')
+```
+{% endstep %}
+
+{% step %}
+### Execute withdrawal
+
+Prepare the contract call transaction to invoke the `burn` function and broadcast the transaction payload.
+
+```typescript
+let transaction = await makeContractCall({
+  contractName: 'usdcx-v1',
+  contractAddress: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM',
+  functionName: 'burn',
+  functionArgs,
+  network: 'testnet',
+  postConditions: [postCondition_1],
+  postConditionMode: 'deny',
+  senderKey: process.env.STACKS_PRIVATE_KEY,
+})
+
+let result = await broadcastTransaction({transaction, network: 'testnet'})
+```
+
+The Stacks network's attestation service passes the burn intent message and signature to xReserve, managed by Circle. xReserve verifies the burn and issues a withdrawal attestation to release USDC to the user’s wallet.
+{% endstep %}
+{% endstepper %}
+
+***
+
+## Additional Resources
+
+* \[[StacksDevs Livestream](https://x.com/StacksDevs/status/2011817589782249600)] A technical breakdown by the main builder behind Stacks' USDCx
diff --git a/docs/build/more-guides/c32check.md b/docs/build/more-guides/c32check.md
@@ -1,5 +1,6 @@
 ---
 description: Generating and decoding addresses on the Stacks blockchain.
+hidden: true
 ---
 
 # c32check
