zerc20-client-sdk 0.2.0 → 0.2.2

package/README.md

@@ -94,6 +94,7 @@ src/
 │   ├── invoice.ts      # Invoice creation
 │   ├── teleport.ts     # Single teleport proof
 │   ├── teleportProof.ts # Batch teleport proof (Nova + Decider)
+│   ├── relay/          # Relay node HTTP client (redeem/swap)
 │   ├── liquidityManager/ # Wrap/unwrap with slippage protection
 │   └── layerzeroScan/   # LayerZero message tracking & decoding
 ├── wasm/         # WASM runtime & bindings
@@ -170,6 +171,75 @@ const quote = await buildCrossUnwrapQuote({
 });
 ```
 
+### Relay Operations
+
+Interact with a relay node for relayer-based redeem and token-to-native swap flows:
+
+```typescript
+import {
+  estimateRelayFee,
+  fetchSwapQuote,
+  submitRelaySwap,
+  submitRelayTeleport,
+} from "zerc20-client-sdk";
+
+const fee = await estimateRelayFee("https://relay.example", 1);
+
+const quote = await fetchSwapQuote("https://relay.example", 1, 1_000_000n);
+if (quote.priceFallback) {
+  console.warn("Relay is using fallback oracle prices");
+}
+
+await submitRelaySwap("https://relay.example", {
+  chainId: 1,
+  tokenAmount: 1_000_000n,
+  minNativeAmount: 900_000n,
+  maxNativeAmount: quote.nativeAmount,
+  recipient: "0x...",
+  owner: "0x...",
+  permitDeadline: 1_700_000_000n,
+  permitV: 27,
+  permitR: "0x...",
+  permitS: "0x...",
+});
+```
+
+### Adaptor Withdraw (Stuck Fund Recovery)
+
+When a cross-chain unwrap fails (e.g. due to Stargate liquidity shortage), user funds may remain in the destination chain's Adaptor contract. The SDK provides functions to detect and recover these stuck funds:
+
+```typescript
+import {
+  fetchAdaptorBalances,
+  hasStuckFunds,
+  withdrawFromAdaptor,
+  NATIVE_TOKEN_ADDRESS,
+} from "zerc20-client-sdk";
+
+// Check if a user has stuck funds in an adaptor
+const stuck = await hasStuckFunds({
+  provider: readProvider,
+  account: "0xUser...",
+  adaptorAddress: "0xAdaptor...",
+});
+
+// Fetch detailed balances
+const balances = await fetchAdaptorBalances({
+  provider: readProvider,
+  account: "0xUser...",
+  adaptorAddress: "0xAdaptor...",
+});
+// balances.underlyingTokenBalance, balances.zerc20Balance, balances.nativeBalance
+
+// Withdraw stuck funds
+const result = await withdrawFromAdaptor({
+  writeProvider,
+  adaptorAddress: "0xAdaptor...",
+  token: balances.underlyingTokenAddress, // or zerc20TokenAddress, or NATIVE_TOKEN_ADDRESS
+  amount: balances.underlyingTokenBalance,
+});
+```
+
 ### LayerZero Scan
 
 Track and decode LayerZero cross-chain messages. Configuration and providers are injected as parameters, making this module framework-agnostic: