編寫 Cedar 規則

本頁面說明如何編寫 Cedar 政策規則，在多方運算 (MPC) 政策引擎中驗證交易。

政策引擎會在安全的受信任執行環境 (TEE) 中，解碼傳入的交易酬載，並將交易意圖屬性投射到 Cedar 評估情境。

Cedar 規則結構

為政策引擎編寫 Cedar 規則時，您可以使用一組巢狀條件指定規則：

  • 主體：多方運算工作區 (例如 User::"alice") 內交易要求者 (交易發起者) 的邏輯身分，而非呼叫 API 的 Google Cloud IAM 身分 (使用者或服務帳戶)。
  • 動作：要求的加密編譯動作 (例如 Action::"sign_transaction")。
  • 資源：要操作的目標資產或作業類別 (例如 Resource::"mpc_operation")。
  • Context：剖析後的交易中繼資料和參數 (可透過 context.transaction 存取)。

以太坊交易結構定義參考資料

這個框架與通訊協定無關，因此規則可以略過結構定義檢查，在不同的區塊鏈網路中重複使用。不過，如要明確將規則限制為以太坊交易酬載，請勾選：context.transaction.schema == "ethereum.transaction.v2"。

context.transaction 記錄支援下列屬性：

屬性 類型 說明
schema 字串 格式結構定義。如果是以太坊交易，這個值一律為 "ethereum.transaction.v2"。
operation 字串 交易作業類型。支援的值：
  • "NATIVE_TRANSFER"：直接轉移主鏈貨幣 (例如 ETH)。
  • "TOKEN_TRANSFER"：ERC-20 代幣轉移 (例如 USDC、USDT、DAI)。
  • "TOKEN_APPROVE"：ERC-20 代幣核准，允許合約使用代幣。
  • "CONTRACT_CALL"：一般智慧型合約互動 (例如質押或交換)。
chain_id 字串 目標區塊鏈網路 ID (例如以太坊主網的 "1"，或 Sepolia 測試網的 "11155111")。
asset_symbol 字串 轉移代幣的股票代號 (例如 "ETH"、"USDC"、"DAI" 或 "WBTC")。未列出的代幣會傳回 "UNKNOWN"。
asset_contract_address 字串 ERC-20 代幣的智慧型合約地址 (採用大小寫混合的 EIP-55 核對和格式)。如果是標準 ETH 轉帳，則會解析為空字串 ("")。
recipient 字串 目的地收款人地址 (採用大小寫混合的 EIP-55 核對和格式)。如果是代幣核准，這代表支出者地址。
spend_amount_scaled Long 代幣轉移金額會正規化為固定的 9 位小數精確度 (奈米幣格式)，因此編寫規則時，不必追蹤不同的代幣小數位數 (例如 6、8 或 18)。

計算方式：將人類可讀的資產金額 (例如 1.5 ETH 或 5,000 USDC) 乘以 1,000,000,000 (109)，即可得出規則的值：
  • 0.1 ETH → 100000000 (0.1 × 109)
  • 任何資產的 1.0 → 1000000000 (1.0 × 109)
  • 5,000 USDC → 5000000000000 (5,000 × 109)
spend_amount_dust Long 交易金額中低於 9 位小數精確度門檻的剩餘部分。如果資產的小數位數超過 9 位 (例如 ETH 有 18 位)，則會包含未經調整的 sub-Gwei 值 (剩餘的 Wei)。對於小數點後 9 位以下 (含) 的資產 (例如 USDC 或 WBTC)，這個值一律為 0。
max_fee_atomic Long 交易手續費總額上限 (乘以 109，代表 Gwei)。
gas_limit Long 執行交易時分配的 Gas 數量上限。
destination_type 字串 收件者地址的分類。支援的值："EOA" (標準使用者錢包)、"CONTRACT" (智慧型合約) 或 "INTERNAL_TREASURY" (內部保管箱)。
temporal_validity Long 交易帳戶 Nonce (用於防範交易重送攻擊)。

比特幣交易結構定義參考資料

如要明確限制規則，只適用於比特幣 BIP 174 PSBT 交易酬載，請檢查：context.transaction.schema == "bitcoin.transaction.v2"。

context.transaction 記錄支援下列屬性：

屬性 類型 說明
schema 字串 格式結構定義。如果是比特幣交易，這個值一律為 "bitcoin.transaction.v2"。
operation 字串 交易作業類型。支援的值：
  • "NATIVE_TRANSFER"：直接轉移比特幣 (BTC)。
  • "OP_RETURN"：無法花費的資料錨定 / 空值資料輸出。
chain_id 字串 目標網路 Bech32 人類可讀部分 (HRP)："bc" (比特幣主網)、"tb" (測試網路 / Testnet4) 或 "bcrt" (Regtest)。
asset_symbol 字串 資產股票代號："BTC"。
recipient 字串 主要目的地地址。如果是 OP_RETURN 交易，則為 "unaddressable"。如果是內部合併掃描 (100% 找零)，則會解析為第一個找零地址。
spend_amount_scaled Long 淨流出轉移金額，正規化為固定 9 位小數精確度 (10-9 單位)。由於 1 聰等於 10 奈米幣單位 (1 聰 = 10 單位，1 比特幣 = 109 單位)，因此不含內部找零金額。如果是內部掃描 / 100% 找零交易，則會評估為 0。
max_fee_atomic Long 計算出的礦工手續費上限，正規化為 9 位小數精確度：(∑ 輸入 − ∑ 輸出) × 10。
destination_type 字串 收件者指令碼的分類。支援的值："P2WPKH" (原生隔離見證)、"P2TR" (Taproot)、"P2PKH" (舊版)、"P2SH" (巢狀隔離見證 / 指令碼雜湊)、"TREASURY_CHANGE" (內部變更掃描) 或 ""。
temporal_validity Long 交易 nLockTime 欄位。
outputs Set<Record> 所有交易輸出的正規化組合：[{ address: String, amount_scaled: Long, is_change: Bool }]。

比特幣政策核心概念

  1. 通用 9 位小數點縮放數學： 比特幣政策中的金額使用標準化 9 位小數點奈米幣精確度 (1 sat = 10 單位，1 BTC = 109 單位)：

    金額縮放 = Satoshis × 10 = BTC × 109

    • 0.0005 BTC (50,000 聰) → 500000 (50,000 × 10)
    • 0.0025 BTC (250,000 聰) → 2500000 (250,000 × 10)
    • 1.0 BTC (100,000,000 聰) → 1000000000 (100,000,000 × 10)

  2. 找零輸出區隔：剖析器會檢查 BIP-32 衍生路徑 (m/.../1/*)，並關聯輸入指令碼，自動識別內部找零輸出。找零金額不計入 spend_amount_scaled，確保支出上限政策嚴格評估轉移至第三方的淨流出價值。

  3. 單一非變更收件者規則： 為防止不明確的多收件者轉送攻擊，包含多個不同外部第三方收件者的交易會失敗並關閉 (ErrUnsupportedTx)。

Cedar 規則範例

以下範例說明如何使用 Cedar 設定允許清單、限制規則和重播界限，以便處理以太幣和比特幣交易。

Ethereum 範例

以下規則說明以太坊和 ERC-20 交易的常見政策模式。

1. 直接轉移 ETH 的限制

這項規則允許 Alice 轉移基礎鏈 ETH，並檢查調整後的轉移金額是否不超過 1.0 ETH (1,000,000,000 調整後的 Gwei 單位)。

permit (
    principal == User::"alice",
    action == Action::"sign_transaction",
    resource == Resource::"mpc_operation"
)
when {
    context.transaction.operation == "NATIVE_TRANSFER" &&
    context.transaction.asset_symbol == "ETH" &&
    context.transaction.spend_amount_scaled <= 1000000000
};

2. ERC-20 代幣許可清單規則

這項規則允許轉移最多 5,000 USDC 代幣。這項政策會限制轉移作業，只允許轉移至許可清單中的收件者地址。請注意，Cedar 字串會區分大小寫，因此收款人地址必須符合大小寫混合的 EIP-55 格式。

permit (
    principal == User::"alice",
    action == Action::"sign_transaction",
    resource == Resource::"mpc_operation"
)
when {
    context.transaction.operation == "TOKEN_TRANSFER" &&
    context.transaction.asset_symbol == "USDC" &&
    context.transaction.recipient == "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B" &&
    context.transaction.spend_amount_scaled <= 5000000000000
};

3. 智慧合約和 DeFi 呼叫備用機制

這項規則允許一般合約互動 (例如質押或交換)，且沒有金額限制，前提是這些互動並非資產支出轉移操作。

permit (
    principal == User::"alice",
    action == Action::"sign_transaction",
    resource == Resource::"mpc_operation"
)
when {
    context.transaction.operation == "CONTRACT_CALL"
};

4. 嚴格重放攻擊防護機制 (鏈結 ID 邊界)

為防止交易重送攻擊 (即針對測試網鏈簽署的酬載在正式版主網上重新提交)，您可以將規則範圍限定在特定鏈 ID (例如 Sepolia 的 11155111)。

permit (
    principal == User::"alice",
    action == Action::"sign_transaction",
    resource == Resource::"mpc_operation"
)
when {
    context.transaction.chain_id == "11155111"
};

比特幣範例

下列規則說明比特幣 PSBT 交易的常見政策模式。

1. 支出上限和礦工費上限

這項規則允許直接轉移比特幣 (BTC)，前提是淨轉出金額不超過 0.0025 BTC (250,000 聰 → 2,500,000 縮放單位)，且礦工手續費不超過 10,000 聰 (100,000 基本單位)。

permit (
    principal == User::"alice",
    action == Action::"sign_transaction",
    resource == Resource::"mpc_operation"
)
when {
    context.transaction.operation == "NATIVE_TRANSFER" &&
    context.transaction.asset_symbol == "BTC" &&
    context.transaction.spend_amount_scaled <= 2500000 &&
    context.transaction.max_fee_atomic <= 100000
};

2. SegWit (P2WPKH) 和 Taproot (P2TR) 位址許可清單

這項規則會限制比特幣轉移至已核准的 SegWit 或 Taproot 目的地地址。

permit (
    principal == User::"alice",
    action == Action::"sign_transaction",
    resource == Resource::"mpc_operation"
)
when {
    context.transaction.schema == "bitcoin.transaction.v2" &&
    (context.transaction.destination_type == "P2WPKH" || context.transaction.destination_type == "P2TR") &&
    context.transaction.recipient == "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
};

3. UTXO 整合和資金清算

這項規則允許內部 UTXO 整合掃描，所有輸出都會返回內部找零地址 (destination_type == "TREASURY_CHANGE" 和 spend_amount_scaled == 0)，同時限制整合費用。

permit (
    principal == User::"alice",
    action == Action::"sign_transaction",
    resource == Resource::"mpc_operation"
)
when {
    context.transaction.schema == "bitcoin.transaction.v2" &&
    context.transaction.destination_type == "TREASURY_CHANGE" &&
    context.transaction.spend_amount_scaled == 0 &&
    context.transaction.max_fee_atomic <= 50000
};

4. 輸出內容集檢查

這項規則會驗證交易輸出組合是否包含特定目的地輸出和金額。

permit (
    principal == User::"alice",
    action == Action::"sign_transaction",
    resource == Resource::"mpc_operation"
)
when {
    context.transaction.outputs.contains({
        address: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
        amount_scaled: 500000,
        is_change: false
    })
};

5. 網路範圍 (主網與測試網)

這項規則會將授權範圍限定為比特幣測試網 (tb) 交易，防止在比特幣主網 (bc) 上執行。

permit (
    principal == User::"alice",
    action == Action::"sign_transaction",
    resource == Resource::"mpc_operation"
)
when {
    context.transaction.schema == "bitcoin.transaction.v2" &&
    context.transaction.chain_id == "tb"
};

6. OP_RETURN資料錨定

這項規則允許不可花費的 OP_RETURN 資料錨定交易 (spend_amount_scaled == 0 和 recipient == "unaddressable")，並強制執行嚴格的手續費上限。

permit (
    principal == User::"alice",
    action == Action::"sign_transaction",
    resource == Resource::"mpc_operation"
)
when {
    context.transaction.operation == "OP_RETURN" &&
    context.transaction.recipient == "unaddressable" &&
    context.transaction.spend_amount_scaled == 0 &&
    context.transaction.max_fee_atomic <= 10000
};

剖析器安全防護機制

為保護正式環境中的交易作業，政策引擎會嚴格剖析酬載，並在閘道層拒絕無效結構，然後才評估 Cedar 規則：

  • 強制執行零值基礎貨幣：剖析器會明確拒絕嘗試綁定非零基礎轉移資產的以太坊代幣轉移作業 (TOKEN_TRANSFER)。這可防止惡意酬載轉移標準基礎資產價值，同時將交易呈現為標準代幣轉移。
  • UTXO 和見證驗證：針對比特幣 PSBT 交易，剖析器會驗證所有輸入內容是否提供有效的 witness_utxo 資料，防止手續費計算詐騙或未經驗證的簽署。
  • 變更輸出指令碼驗證：內部變更輸出內容必須與輸入指令碼 pubkey 或已知的 BIP-32 變更路徑 (m/.../1/*) 相符。如果酬載嘗試將變更輸出內容假冒為第三方地址，則會失敗並關閉。
  • 單一外部收款人強制執行：如果比特幣酬載含有多個外部非找零目的地地址，系統會失敗關閉 (ErrUnsupportedTx)，避免授權不明確的多收款人政策。
  • 整數溢位和下溢保護：如果 Nonce、鎖定時間、Gas 或手續費上限，以及金額超出安全界限 (MaxInt64) 或產生下溢 (例如總輸出值超過總輸入值)，系統會立即拒絕。
  • 未驗證手續費：如果交易未定義適當的礦工費或 Gas 參數，系統會自動關閉交易。