dbd517b279
- Update dbis_core, cross-chain-pmm-lps, explorer-monorepo, metamask-integration, pr-workspace/chains - Omit embedded publish git dirs and empty placeholders from index Made-with: Cursor
112 lines
6.4 KiB
Markdown
112 lines
6.4 KiB
Markdown
# Pathways: Chain 138 → native BTC (Changelly & Atomic Wallet)
|
||
|
||
**Purpose:** Define how value moves from **Chain 138** to **native BTC on Bitcoin mainnet** using **Changelly** (partner API, automation-friendly) and **Atomic Wallet** (in-app swap, user-operated). Machine-readable steps live in [`config/btc-settlement-pathways.json`](../../config/btc-settlement-pathways.json).
|
||
|
||
**Related:** [MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md](../00-meta/MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md) (mainnet liquidity for bridges), [MAINNET_RAMP_USER_FLOWS.md](MAINNET_RAMP_USER_FLOWS.md), [DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md](../11-references/DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md).
|
||
|
||
---
|
||
|
||
## 1. Changelly (recommended for orchestration)
|
||
|
||
Changelly operates a **white-label crypto-to-crypto** product: **Exchange API v2** (JSON-RPC over HTTPS). You implement calls **only on a backend**; keys must not ship to browsers. Official docs: [Changelly Exchange API v2](https://docs.changelly.com/).
|
||
|
||
### 1.1 Partner onboarding
|
||
|
||
1. Generate an **RSA key pair** (Changelly documents the format in [Generate keys](https://docs.changelly.com/development/generate-keys)).
|
||
2. Register at [changelly.com](https://changelly.com/) and email **pro@changelly.com** with account email, **public** key, and Base64 public key, plus project description (per [Getting started](https://docs.changelly.com/usage/getting-started)).
|
||
3. Store the **private key** in your secrets vault (file path or KMS); map env vars in [`.env.master.example`](../../.env.master.example) (`CHANGELLY_*`).
|
||
|
||
### 1.2 Auth model
|
||
|
||
Each request sends:
|
||
|
||
- **`X-Api-Key`** — SHA-256 hash of your public key (hex), as documented.
|
||
- **`X-Api-Signature`** — RSA-SHA256 signature of the **exact** JSON-RPC body.
|
||
|
||
See [Authentication](https://docs.changelly.com/development/authentication).
|
||
|
||
### 1.3 Typical API sequence (BTC payout)
|
||
|
||
Use the methods listed in `config/btc-settlement-pathways.json` under `changelly.documentedRpcFlow`. In practice:
|
||
|
||
1. **`getCurrencies` / `getPairsParams`** — Confirm **from** tickers you will fund (e.g. `eth`, `usdt20`, `usdc`) and **to** = `btc`.
|
||
2. **`getMinAmount`** — Respect minimums for the pair.
|
||
3. **`validateAddress`** — Validate the user’s **BTC** address before creating the transaction.
|
||
4. **`getExchangeAmount`** — Quote expected BTC out (v2 quotes must pair with v2 `createTransaction`).
|
||
5. **`createTransaction`** — Pass payout **BTC address**, **from** currency, and amount; receive **Changelly deposit (payin) address** and transaction id.
|
||
6. **On Ethereum:** Send the exact **payin** amount from your **treasury** wallet to the deposit address (ERC-20 `transfer` or native ETH per instructions).
|
||
7. **`getTransactions`** (or status polling) — Track until outbound BTC is sent; record **Bitcoin txid** for reconciliation.
|
||
|
||
**Constraint:** For currencies with multiple outputs (e.g. BTC), Changelly does not accept more than **one output per address** in a single transaction ([Getting started](https://docs.changelly.com/usage/getting-started)).
|
||
|
||
### 1.4 How this attaches to Chain 138
|
||
|
||
Changelly does **not** speak Chain 138. Your orchestrator must first land **standard Ethereum mainnet** assets:
|
||
|
||
- **Swap on 138** (e.g. cUSDT/cUSDC via PMM) into whatever your **bridge** expects (often **WETH** for CCIP WETH bridges).
|
||
- **Bridge 138 → Ethereum** using your **deployed** bridges; ensure **mainnet liquidity** so payouts do not stall ([MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md](../00-meta/MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md)).
|
||
- **Optional mainnet DEX** if the bridged asset is not exactly the Changelly **from** ticker (e.g. WETH → USDT).
|
||
|
||
Then run the Changelly sequence above from a **mainnet treasury** EOA or contract you control.
|
||
|
||
---
|
||
|
||
## 2. Atomic Wallet (user path, not a drop-in server API)
|
||
|
||
Atomic Wallet’s **Exchange** feature is documented for **end users**: you choose assets and send to **partner deposit flows** inside the app; rates are **not** fixed; completion time is vendor-dependent. See [How do I make a swap?](https://support.atomicwallet.io/article/73-how-to-make-an-exchange) and [The process of a swap](https://support.atomicwallet.io/article/90-the-process-of-exchange).
|
||
|
||
### 2.1 Pathway in this project
|
||
|
||
1. Same **138 → Ethereum** bridge outcome as for Changelly, but funds must end on an **Ethereum address the user controls in Atomic** (import the same key, or transfer to Atomic’s ETH account).
|
||
2. User opens **Exchange** in Atomic, selects **from** (e.g. ETH, USDT, USDC if listed) **to BTC**, confirms quote, completes the flow.
|
||
3. **Ops / compliance:** Treat as **manual** or **semi-manual**; idempotency and server-side reconciliation are **your** bookkeeping, not Atomic’s public API in this pathway.
|
||
|
||
### 2.2 Why not “just call Atomic’s API” like Changelly?
|
||
|
||
There is **no** first-party, documented **B2B swap API** in Atomic’s public knowledge base equivalent to Changelly v2 for arbitrary **server-to-BTC** settlement. Third-party **portfolio / connectivity** products may exist; they are **out of scope** for this repo unless you add a dedicated integration with contractual coverage.
|
||
|
||
**Use Atomic** when end users already use the wallet and you accept **human-in-the-loop** swaps. **Use Changelly** when you need **backend-driven** create-and-pay flows.
|
||
|
||
---
|
||
|
||
## 3. Architecture sketch (orchestrator)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph chain138 [Chain 138]
|
||
A[Source tokens e.g. cUSDT cUSDC]
|
||
B[PMM or router swap]
|
||
C[Bridge lock or CCIP send]
|
||
end
|
||
subgraph mainnet [Ethereum mainnet]
|
||
D[Recipient treasury or user EOA]
|
||
E[Optional DEX to USDT USDC ETH]
|
||
end
|
||
subgraph settlement [BTC settlement]
|
||
F[Changelly createTransaction plus payin tx]
|
||
G[Atomic user Exchange]
|
||
H[Native BTC UTXO payout]
|
||
end
|
||
A --> B --> C --> D --> E
|
||
E --> F --> H
|
||
E --> G --> H
|
||
```
|
||
|
||
---
|
||
|
||
## 4. What you still implement in software
|
||
|
||
| Piece | Changelly path | Atomic path |
|
||
|--------|----------------|-------------|
|
||
| Bridge + swap planner | Required | Required |
|
||
| Secure Changelly JSON-RPC client | Required | N/A |
|
||
| Treasury mainnet wallet + gas | Required | User wallet |
|
||
| Job store + idempotency + status UI | Required | Optional / manual |
|
||
| BTC address validation | Via Changelly + local checks | User |
|
||
|
||
---
|
||
|
||
## 5. Env placeholders
|
||
|
||
See **`CHANGELLY_*`** in [`.env.master.example`](../../.env.master.example). Do not commit private keys; use a secrets manager or encrypted PEM path on servers.
|