# 链密钥比特币 (ckBTC) 集成 ## 这是什么 ckBTC 是一种 1:1 BTC 支持的代币，原生于互联网计算机。没有桥梁，没有包装，没有第三方托管人。 ckBTC 铸币罐保存真实的 BTC 并铸造/销毁 ckBTC 代币。转账在 1-2 秒内完成，费用为 10 聪（比特币 L1 则需要几分钟和数千聪）。 ## 先决条件 * `icp-cli` >= 0.1.0（安装：`brew install dfinity/tap/icp-cli`） * 对于 Motoko：mops.toml 中的 `mops` 包管理器、`core = "2.0.0"` * 对于 Rust：`ic-cdk`、`icrc-ledger-types`、`candid`、`serde` * 受资助的 ICP 身份（用于主网部署周期） ## 容器 ID ### 比特币主网罐|身份证号 ---|--- ckBTC 账本 | `mxzaz-hqaaa-aaaar-qaada-cai` ckBTC 铸币厂 | `mqygn-kiaaa-aaaar-qaadq-cai` ckBTC 指数 | `n5wcd-faaaa-aaaar-qaaea-cai` ckBTC 检查器 | `oltsj-fqaaa-aaaar-qal5q-cai` ### 比特币测试网4 罐|身份证号 ---|--- ckBTC 账本 | `mc6ru-gyaaa-aaaar-qaaaq-cai` ckBTC 铸币厂 | `ml52i-qaaa-aaaar-qaaba-cai` ckBTC 指数 | `mm444-5iaaa-aaaar-qaabq-cai` ## 它是如何工作的 ### 存款流程（BTC -> ckBTC） 1. 使用用户的主体+子账户在铸币厂上调用“get_btc_address”。这将返回由铸币者控制的唯一比特币地址。 2. 用户使用任何比特币钱包将 BTC 发送到该地址。 3.等待比特币确认（铸币者在铸币前需要确认）。 4. 在具有相同主体+子账户的铸币者上调用“update_balance”。铸币者检查新的 UTXO 并铸造等值的 ckBTC 到用户的 ICRC-1 账户。 ### 转账流程（ckBTC -> ckBTC）在 ckBTC 账本上调用“icrc1_transfer”。费用为 10 聪。 1-2 秒后稳定。 ### 提现流程（ckBTC -> BTC） 1. 在 ckBTC 账本上调用“icrc2_approve”，向铸币者授予可从您的账户中支出的津贴。 2. 使用“{address, amount, from_subaccount: null }”在铸币厂上调用“retrieve_btc_with_approval”。 3. 铸币者使用批准燃烧 ckBTC 并提交比特币交易。 4. 比特币确认后，BTC到达目的地址。 ### 子账户生成每个用户都会获得一个源自其本金的唯一存款地址 + 一个可选的 32 字节子账户。要为您的容器内的每个用户提供一个不同的存款地址，请从用户特定的标识符（其主体或连续 ID）派生子账户。 ## 破坏你的构建的错误 1. **使用错误的铸币罐 ID。** 铸币器 ID 为 `mqygn-kiaaa-aaaar-qaadq-cai`。不要将其与分类帐（`mxzaz-...`）或索引（`n5wcd-...`）混淆。 2. **忘记 10 聪的转账费用。** 每个 `icrc1_transfer` 都会在金额之外扣除 10 聪。如果用户正好有 1000 聪，而您转账 1000 聪，则会失败并显示“资金不足”。改为转移“余额 - 10”。 3. **在 BTC 充值后不调用 `update_balance`。** 在您调用 `update_balance` 之前，将 BTC 发送到充值地址不会执行任何操作。造币厂不会自动检测存款。您的应用程序必须调用此函数。 4. **使用账户标识符代替 ICRC-1 账户。** ckBTC 使用 ICRC-1 标准：“{ 所有者：委托人，子账户：？Blob }”。请勿使用 ICP 分类账中的旧版“AccountIdentifier”（十六进制字符串）。 5. **子账户必须正好是 32 字节或为空。** 传递短于或长于 32 字节的子账户会导致陷阱。如果派生自较短的值，则用前导零填充。 6. **以低于最低金额的金额调用`retrieve_btc`。** 造币厂有最低提现金额（目前为 50,000 聪 / 0.0005 BTC）。在此之下，您会得到“AmountTooLow”。 7. **不检查 `retrieve_btc` 响应是否有错误。** 该响应是一个变体：“Ok”包含“{ block_index }”，“Err”包含特定错误，例如“MalformedAddress”、“InsufficientFunds”、“TemporarilyUnavailable”。始终匹配双臂。 8. **在`get_btc_address`参数中忘记`owner`。**如果省略`owner`，Candid子类型分配为空，并且铸币者返回调用者（罐）而不是用户的存款地址。 ## 实施 ### 元子 #### mops.toml [包装] 名称 =“ckbtc-app” 版本=“0.1.0” [依赖项] 核心=“2.0.0” icrc2-类型=“1.1.0” #### icp.yaml（使用ckBTC进行本地开发）对于本地测试，请拉出 ckBTC 容器：默认值：构建： packtool：拖把源罐：后端：类型：元子主要：src/backend/main.mo 依赖项：[] 网络：本地：绑定：127.0.0.1:4943 对于主网，您的容器通过委托人直接调用 ckBTC 账本和铸币机。 #### src/backend/main.mo 导入主体“mo：核心/主体”；导入 Blob“mo:core/Blob”；导入 Nat "mo:core/Nat"; 导入 Nat8 "mo:core/Nat8"; 导入 Nat64 "mo:core/Nat64"; 导入数组“mo：核心/数组”；导入结果“mo：核心/结果”；导入错误“mo：核心/错误”；导入运行时“mo：核心/运行时”；持久的演员自我{ // -- 类型 -- 输入帐户 = { 所有者：校长；子帐户：？Blob； }; 类型 TransferArgs = { from_subaccount : ?Blob; 至：账户；数量：自然；费用：？Nat；备忘录：？Blob；创建时间：？Nat64； }; 类型传输结果 = { #好的：纳特； // 块索引 #Err：传输错误； }; 类型传输错误 = { #BadFee：{预期费用：Nat}； #BadBurn : { min_burn_amount : Nat }; #InsufficientFunds : { 余额 : Nat }; #太旧了； #CreatedInFuture : { ledger_time : Nat64 }; #Duplicate：{duplicate_of：Nat}； #暂时不可用； #GenericError : { 错误代码 : Nat;消息：文本}； }; 类型更新余额结果 = { #好的：[UtxoStatus]； #Err：更新平衡错误； }; 类型 UtxoStatus = { #ValueTooSmall：Utxo； #Tainted：Utxo； #检查：Utxo； #Minted : { block_index : Nat64; minted_amount ：Nat64； utxo : utxo }; }; 输入 Utxo = { 出点：{ txid：Blob； vout : Nat32 }; 值：Nat64；高度：Nat32； }; 类型更新余额错误 = { #NoNewUtxos：{ 必需的确认：Nat32；挂起_utxos : ?[PendingUtxo]; 当前确认：？Nat32； }; #已经处理； #暂时不可用：文本； #GenericError : { error_code : Nat64;错误消息：文本}； }; 类型 PendingUtxo = { 出点：{ txid：Blob； vout : Nat32 }; 值：Nat64；确认：Nat32； }; 类型 ApproveArgs = { from_subaccount : ?Blob; 支出者：账户；数量：自然；预期津贴：？Nat；过期时间：？Nat64；费用：？Nat；备忘录：？Blob；创建时间：？Nat64； }; 类型批准错误 = { #BadFee：{预期费用：Nat}； #InsufficientFunds : { 余额 : Nat }; #AllowanceChanged : { current_allowance : Nat }; #Expired : { ledger_time : Nat64 }; #太旧了； #CreatedInFuture : { ledger_time : Nat64 }; #Duplicate：{duplicate_of：Nat}； #暂时不可用； #GenericError : { 错误代码 : Nat;消息：文本}； }; 类型 RetrieveBtcWithApprovalArgs = { 地址：文本；数量：Nat64； from_subaccount : ?Blob; }; 类型 RetrieveBtcResult = { #好的：{ block_index：Nat64 }; #Err：检索BtcError； }; 类型 RetrieveBtcError = { #MalformedAddress：文本； #已经处理； #AmountTooLow：Nat64； #InsufficientFunds : { 余额 : Nat64 }; #InsufficientAllowance：{津贴：Nat64}； #暂时不可用：文本； #GenericError : { error_code : Nat64;错误消息：文本}； }; // -- 远程容器引用（主网）-- 瞬态让 ckbtcLedger : 演员 { icrc1_transfer : 共享 (TransferArgs) -> 异步 TransferResult; icrc1_balance_of ：共享查询（帐户）-> 异步 Nat； icrc1_fee : 共享查询 () -> 异步 Nat; icrc2_approve : 共享 (ApproveArgs) -> 异步 { #Ok : Nat; #Err：批准错误}； } = 演员“mxzaz-hqaaa-aaaar-qaada-cai”；瞬态让 ckbtcMinter : 演员 { get_btc_address ：共享（{ 业主：？校长；子帐户：？Blob； }) -> 异步文本； update_balance ：共享（{ 业主：？校长；子帐户：？Blob； }) -> 异步 UpdateBalanceResult; retrieve_btc_with_approval ：共享（RetrieveBtcWithApprovalArgs）->异步RetrieveBtcResult； } = 演员“mqygn-kiaaa-aaaar-qaadq-cai”； // -- 子账户派生 -- // 从每个用户存款地址的主体派生一个 32 字节的子账户。 funcprincipalToSubaccount(p : 委托人) : Blob { 让字节 = Blob.toArray(Principal.toBlob(p)); 让大小 = bytes.size(); // 第一个字节是长度，剩余的填充为 32 字节让 sub = Array.tabulate(32, func(i : Nat) : Nat8 { if (i == 0) { Nat8.fromNat(大小) } 否则 if (i <= size) { bytes[i - 1] } 否则{0} }); Blob.fromArray(子) }; // -- 充值：获取用户的BTC充值地址 -- 公共共享（{调用者}）func getDepositAddress（）：异步文本{ if (Principal.isAnonymous(caller)) { Runtime.trap("需要身份验证") }; 让子帐户=principalToSubaccount（调用者）；等待 ckbtcMinter.get_btc_address({ 所有者 = ?Principal.fromActor(Self); 子账户=？子账户； }) }; // -- 存款：检查新的 BTC 并铸造 ckBTC -- 公共共享（{调用者}）func updateBalance（）：异步UpdateBalanceResult { if (Principal.isAnonymous(caller)) { Runtime.trap("需要身份验证") }; 让子帐户=principalToSubaccount（调用者）；等待 ckbtcMinter.update_balance({ 所有者 = ?Principal.fromActor(Self); 子账户=？子账户； }) }; // -- 检查用户的ckBTC余额-- 公共共享（{调用者}）func getBalance（）：async Nat { if (Principal.isAnonymous(caller)) { Runtime.trap("需要身份验证") }; 让子帐户=principalToSubaccount（调用者）；等待 ckbtcLedger.icrc1_balance_of({ 所有者=Principal.fromActor(Self); 子账户=？子账户； }) }; // -- 将 ckBTC 转移给另一个用户 -- 公共共享（{调用者}）func转移（至：委托人，金额：Nat）：异步TransferResult { if (Principal.isAnonymous(caller)) { Runtime.trap("需要身份验证") }; 让 fromSubaccount =principalToSubaccount(caller); 等待 ckbtcLedger.icrc1_transfer({ from_subaccount = ?fromSubaccount; 到 = { 所有者 = 到;子账户 = null }; 金额=金额；费用 = ?10； // 10 聪备忘录=空；创建时间=空； }) }; // -- 提现：将 ckBTC 转换回 BTC -- 公共共享（{来电者}）funcwithdraw（btcAddress：文本，金额：Nat64）：asyncRetrieveBtcResult{ if (Principal.isAnonymous(caller)) { Runtime.trap("需要身份验证") }; // 步骤1：批准铸币者从用户的子账户中花费ckBTC 让 fromSubaccount =principalToSubaccount(caller); 让approveResult =等待ckbtcLedger.icrc2_approve({ from_subaccount = ?fromSubaccount; 花钱者={ 所有者 = Primary.fromText("mqygn-kiaaa-aaaar-qaadq-cai"); 子账户=空； }; 金额 = Nat64.toNat(金额) + 10; // 金额 + 铸币者燃烧费用预期津贴=空；过期时间 = null; 费用 = ?10；备忘录=空；创建时间=空； }); 开关（批准结果）{ case (#Err(e)) { return #Err(#GenericError({ error_code = 0; error_message = "批准铸币机失败" })) }; 案例（#好的（_））{}； }; // 步骤2：在铸币者上调用retrieve_btc_with_approval 等待 ckbtcMinter.retrieve_btc_with_approval({ 地址=btc地址；金额=金额； from_subaccount = ?fromSubaccount; }) }; }; ### 铁锈 #### Cargo.toml [包装] 名称=“ckbtc_backend” 版本=“0.1.0” 版本=“2021” [库] 板条箱类型 = ["cdylib"] [依赖项] ic-cdk =“0.19” ic-cdk-定时器=“1.0” 坦率=“0.10” serde = {版本=“1”，功能=[“派生”]} serde_bytes =“0.11” 红十字委员会分类账类型 = "0.1" #### src/lib.rs 使用 candid::{CandidType、反序列化、Nat、Principal}；使用 ic_cdk::update; 使用 ic_cdk::call::Call；使用 icrc_ledger_types::icrc1::account::Account；使用 icrc_ledger_types::icrc1::transfer::{TransferArg, TransferError}; 使用 icrc_ledger_types::icrc2::approve::{ApproveArgs, ApproveError}； // -- 容器 ID -- const CKBTC_LEDGER: &str = "mxzaz-hqaaa-aaaar-qaada-cai"; const CKBTC_MINTER: &str = "mqygn-kiaaa-aaaar-qaadq-cai"; // -- 铸造者类型 -- #[derive(CandidType, 反序列化, 调试)] 结构 GetBtcAddressArgs { 所有者：选项<委托人>，子账户: Option>, } #[derive(CandidType, 反序列化, 调试)] 结构更新平衡参数{ 所有者：选项<委托人>，子账户: Option>, } #[derive(CandidType, 反序列化, 调试)] 结构 RetrieveBtcWithApprovalArgs { 地址：字符串，金额：u64， from_subaccount: 选项>, } #[derive(CandidType, 反序列化, 调试)] 结构 RetrieveBtcOk { 块索引：u64， } #[derive(CandidType, 反序列化, 调试)] 枚举 RetrieveBtcError { 格式错误的地址（字符串），已经处理中，金额太低（u64），资金不足{余额：u64}， InsufficientAllowance { 津贴: u64 }, 暂时不可用（字符串）， GenericError { error_code: u64, error_message: String }, } #[derive(CandidType, 反序列化, 调试)] 结构体 Utxo { 出点：出点，值：u64，身高：u32， } #[derive(CandidType, 反序列化, 调试)] 结构出点{ txid：Vec，输出：u32， } #[derive(CandidType, 反序列化, 调试)] 结构 PendingUtxo { 出点：出点，值：u64，确认：u32， } #[derive(CandidType, 反序列化, 调试)] 枚举 UtxoStatus { 值太小（Utxo），被污染（Utxo），检查（Utxo），铸造{ 块索引：u64，铸造量：u64， utxo: utxo, }, } #[derive(CandidType, 反序列化, 调试)] 枚举更新平衡错误{ 没有NewUtxos { 必需的确认：u32， ending_utxos: 选项>, current_confirmations：选项， }, 已经处理中，暂时不可用（字符串）， GenericError { error_code: u64, error_message: String }, } 类型 UpdateBalanceResult = Result, UpdateBalanceError>; 类型 RetrieveBtcResult = Result; // -- 子账户派生 -- // 从每个用户存款地址的主体派生一个 32 字节的子账户。 fnprincipal_to_subaccount(principal: &Principal) -> [u8; 32]{ 让 mut 子帐户 = [0u8; 32]；让principal_bytes =principal.as_slice(); subaccount[0] =principal_bytes.len() as u8; 子帐户[1..1 +principal_bytes.len()].copy_from_slice(principal_bytes); 子账户 } fn ledger_id() -> 委托人 { 主体::from_text(CKBTC_LEDGER).unwrap() } fn minter_id() -> 校长 { 主体::from_text(CKBTC_MINTER).unwrap() } // -- 充值：获取用户的BTC充值地址 -- #[更新] async fn get_deposit_address() -> String { 让调用者 = ic_cdk::api::msg_caller(); assert_ne!(caller, Primary::anonymous(), "需要身份验证"); 让子帐户=principal_to_subaccount(&caller); 让args = GetBtcAddressArgs { 所有者：一些（ic_cdk :: api :: canister_self（）），子账户：一些(subaccount.to_vec()), }; let (address,): (String,) = Call::unbounded_wait(minter_id(), "get_btc_address") .with_arg(参数) .await .expect("获取BTC地址失败") .candid_tuple() .expect("解码响应失败"); 地址 } // -- 存款：检查新的 BTC 并铸造 ckBTC -- #[更新] 异步 fn update_balance() -> UpdateBalanceResult { 让调用者 = ic_cdk::api::msg_caller(); assert_ne!(caller, Primary::anonymous(), "需要身份验证"); 让子帐户=principal_to_subaccount(&caller); 让 args = UpdateBalanceArgs { 所有者：一些（ic_cdk :: api :: canister_self（）），子账户：一些(subaccount.to_vec()), }; let (结果,): (UpdateBalanceResult,) = Call::unbounded_wait(minter_id(), "update_balance") .with_arg(参数) .await .expect("调用update_balance失败") .candid_tuple() .expect("解码响应失败"); 结果 } // -- 检查用户的ckBTC余额-- #[更新] async fn get_balance() -> Nat { 让调用者 = ic_cdk::api::msg_caller(); assert_ne!(caller, Primary::anonymous(), "需要身份验证"); 让子帐户=principal_to_subaccount(&caller); 让帐户=帐户{ 所有者： ic_cdk::api::canister_self(), 子账户：部分（子账户）， }; let (balance,): (Nat,) = Call::unbounded_wait(ledger_id(), "icrc1_balance_of") .with_arg(帐户) .await .expect("无法获得平衡") .candid_tuple() .expect("解码响应失败"); 平衡 } // -- 将 ckBTC 转移给另一个用户 -- #[更新] 异步 fn 转账（至：本金，金额：Nat）-> Result { 让调用者 = ic_cdk::api::msg_caller(); assert_ne!(caller, Primary::anonymous(), "需要身份验证"); 让 from_subaccount =principal_to_subaccount(&caller); 让args = TransferArg { from_subaccount：一些（from_subaccount），至：帐户{ 业主: 到, 子账户：无， }, 金额，费用: Some(Nat::from(10u64)), // 10 聪备注：无，创建时间：无， }; let (结果,): (结果,) = Call::unbounded_wait(ledger_id(), "icrc1_transfer") .with_arg(参数) .await .expect("调用icrc1_transfer失败") .candid_tuple() .expect("解码响应失败"); 结果 } // -- 提现：将 ckBTC 转换回 BTC -- #[更新] async fnwithdraw(btc_address: String, amount: u64) -> RetrieveBtcResult { 让调用者 = ic_cdk::api::msg_caller(); assert_ne!(caller, Primary::anonymous(), "需要身份验证"); // 步骤1：批准铸币者从用户的子账户中花费ckBTC 让 from_subaccount =principal_to_subaccount(&caller); 让approve_args = ApproveArgs { from_subaccount：一些（from_subaccount），支出者：账户{ 所有者： minter_id(), 子账户：无， }, amount: Nat::from(amount) + Nat::from(10u64), // amount + 铸币者销毁费用预期津贴：无，过期时间：无，费用：一些（Nat::from(10u64)），备注：无，创建时间：无， }; let (approve_result,): (Result,) = Call::unbounded_wait(ledger_id(), "icrc2_approve") .with_arg(approve_args) .await .expect("调用icrc2_approve失败") .candid_tuple() .expect("解码响应失败"); 如果让 Err(e) =approve_result { 返回 Err(RetrieveBtcError::GenericError { 错误代码：0， error_message: format!("批准铸币机失败: {:?}", e), }); } // 步骤2：在铸币者上调用retrieve_btc_with_approval 让 args = RetrieveBtcWithApprovalArgs { 地址：btc_地址，金额， from_subaccount：一些（from_subaccount.to_vec（））， }; 让（结果，）：（RetrieveBtcResult，）= Call :: unbounded_wait（minter_id（），“retrieve_btc_with_approval”） .with_arg(参数) .await .expect("调用retrieve_btc_with_approval失败") .candid_tuple() .expect("解码响应失败"); 结果 } // -- 导出 Candid 接口 -- ic_cdk::export_candid!(); ## 部署和测试 ### 本地发展本地没有 ckBTC 铸币商。对于本地测试，模拟 minter 接口或针对主网/测试网进行测试。 ### 部署到主网 # 部署您的后端容器 icp部署后端-e ic # 您的容器通过委托人直接调用主网 ckBTC 容器 ### 使用icp直接与ckBTC交互 # 检查账户的 ckBTC 余额 icp 容器调用 mxzaz-hqaaa-aaaar-qaada-cai icrc1_balance_of \ '(记录 { 所有者 = 主体 "YOUR-PRINCIPAL"; 子账户 = null })' \ -e集成电路 # 获取充值地址 icp 容器调用 mqygn-kiaaa-aaaar-qaadq-cai get_btc_address \ '(记录 { 所有者 = opt 主体 "YOUR-PRINCIPAL"; 子账户 = null })' \ -e集成电路 # 检查新存款并铸造 ckBTC icp 容器调用 mqygn-kiaaa-aaaar-qaadq-cai update_balance \ '(记录 { 所有者 = opt 主体 "YOUR-PRINCIPAL"; 子账户 = null })' \ -e集成电路 # 转账 ckBTC（e8s 中的金额 — 1 ckBTC = 100_000_000） icp 容器调用 mxzaz-hqaaa-aaaar-qaada-cai icrc1_transfer \ '（记录{ to = 记录 { 所有者 = 主体“RECIPIENT-PRINCIPAL”;子账户 = null }; 金额=100_000；费用=选择10；备忘录=空； from_subaccount = null; 创建时间=空； })' -e ic # 提取ckBTC到BTC地址（金额以satoshis为单位，最少50_000） # 注意：在生产中，使用 icrc2_approve +retrieve_btc_with_approval （参见上面的提现函数） icp 容器调用 mqygn-kiaaa-aaaar-qaadq-cairetrieve_btc_with_approval \ '(记录{ 地址 = "bc1q...your-btc-address"; 金额 = 50_000; from_subaccount = null })' \ -e集成电路 #查看转账费用 icp 容器调用 mxzaz-hqaaa-aaaar-qaada-cai icrc1_fee '()' -e ic ## 验证它是否有效 ### 检查余额 icp 容器调用 mxzaz-hqaaa-aaaar-qaada-cai icrc1_balance_of \ '(记录 { 所有者 = 主体 "YOUR-PRINCIPAL"; 子账户 = null })' \ -e集成电路 # 预期：(AMOUNT : nat) — 余额聪 (e8s) ### 验证传输 # 转账1000聪 icp 容器调用 mxzaz-hqaaa-aaaar-qaada-cai icrc1_transfer \ '（记录{ to = 记录 { 所有者 = 委托人“RECIPIENT”;子账户 = null }; 金额 = 1_000；费用=选择10；备忘录=空； from_subaccount = null; 创建时间=空； })' -e ic # 预期：(variant { Ok = BLOCK_INDEX : nat }) # 验证收件人已收到 icp 容器调用 mxzaz-hqaaa-aaaar-qaada-cai icrc1_balance_of \ '(记录 { 所有者 = 主体 "RECIPIENT"; 子帐户 = null })' \ -e集成电路 # 预期：余额增加 1000 ### 验证存款流程 # 1. 获取充值地址 icp 容器调用您的容器 getDepositAddress -e ic # 预期：“bc1q...”或“3...”——有效的比特币地址 # 2. 将 BTC 发送到该地址（外部钱包） # 3. 检查新存款 icp 容器调用 YOUR-CANISTER updateBalance -e ic # 预期：(variant { Ok = vec {variant { Minted = record { ... } } } }) # 4.检查ckBTC余额 icp 容器调用 YOUR-CANISTER getBalance -e ic # 预期：余额反映铸造的 ckBTC ### 验证提现 icp 容器调用 YOUR-CANISTER 撤回 '("bc1q...destination", 50_000 : nat64)' -e ic # 预期：(variant { Ok = record { block_index = BLOCK_INDEX : nat64 } }) # 比特币确认后，BTC将到达目的地址

比特币

包含技能