Multi-party Compute 用户指南

预览

此产品受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版产品“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

本指南将详细介绍 Multi-party Compute API 的用户体验历程，以便管理分布式密钥、用户、团队和政策。它适用于学习关键用户体验历程的预览版客户。

概览

MPC API 可管理实例、团队、用户、密钥环、分布式密钥和阈值签名仪式的生命周期，并通过三个政策层强制执行内置加密治理：

• 管理政策（角色法定人数）：管理员负责用户和团队的入职，并且需要达到管理员法定人数（EnableUserRole 和 ApproveRoleChange）才能授予或撤消管理员和政策作者角色。授予签名者角色只需一位管理员即可立即生效，因为仅凭签名者角色无法访问现有密钥；只有在密钥生成期间，签名者被包含在密钥环的密钥政策中时，才会收到密钥共享。
• 密钥政策 (KeyRing.keyPolicy)：管理员在创建 KeyRing 时定义 KeyRing 的 KeyPolicy，指定哪些签名者（签名者，分组到团队中）持有密钥共享，以及授权签名所需的 K-of-N 签名者批准（CreateTransaction 和 RecordSignerDecision）。
• 交易政策（TransactionPolicy 和 KeyList）：政策作者 (POLICY_AUTHOR) 的法定人数提议、批准或停用 Cedar permit 和 forbid 规则 (TransactionPolicy) 以及 KeyList 地址许可清单。每个 CreateTransaction 请求在签名之前都会根据有效的交易政策（PERMIT 或 DENY）进行评估。

前提条件

开始之前，请确保您满足以下方面的要求：

1. Google Cloud 项目。请参阅创建项目以创建一个项目。
2. 如果未使用 Cloud Shell，则需要安装 gcloud CLI 并进行身份验证。

3. 已启用所需 API（如果尚未启用）。您需要两个 API：本指南中使用的 MPC API，以及 Cloud Key Management Service（如果使用它来生成和签署授权密钥）。

     gcloud services enable mpc.googleapis.com cloudkms.googleapis.com
   

   如需查看已启用的 API，请执行以下操作：

     gcloud services list --enabled
   

4. 已安装 Python 3.9+ 和教程辅助库：

     pip install embit eth-account eth-utils requests
   

5. （可选）如果您的组织使用外部身份提供方（例如 Okta 或 Microsoft Entra ID）进行身份验证，而不使用 Google 账号，请参阅配置员工身份联合 (BYOID)，以使用联合身份配置应用默认凭据 (ADC)。

提示： 我们建议使用 Cloud Shell 运行本指南中的命令。Cloud Shell 预配置了 Google Cloud SDK (gcloud)、openssl、jq和其他工具，并会自动处理身份验证。如需打开 Cloud Shell，请点击 Google Cloud 控制台顶部导航栏中的终端图标。

注意： 虽然 MPC API 支持动态 K-of-N 密钥共享（允许跨团队和用户设置任意阈值），但本指南演示的是单个团队内的 2-of-3 签名者设置。此外，政策要求至少两名政策作者（2-of-2 仲裁）才能生效，而角色变更（ADMIN 和 POLICY_AUTHOR）需要 2-of-2 管理员仲裁。

设置

更新以下变量，以填充本指南中的命令。

重要提示： 如果您离开或刷新此页面，这些输入字段可能会重置为默认值。

必需设置

您必须自定义这些参数。如果使用占位值，本指南将无法正常运行。

注意： 单人模拟与多用户模拟：在实际环境中，此系统依赖于多个角色（管理员、政策作者和签名者）之间严格的职责分离，每个角色都有不同的主账号、加密授权密钥和 IAM 权限。由于 API 强制要求每个 User 绑定到唯一的主体，并且无法自行批准角色或法定人数操作，因此，如需完整遵循本指南，您需要多个用户账号。我们计划在未来版本中添加支持，以简化单用户测试。每个 User 主账号可以是 Google Cloud 邮箱或员工身份联合 (BYOID) 主账号；本指南使用 Google Cloud 邮箱示例（例如 [e-mail]）。

参数	值	说明
项目 ID	my-project	MPC 实例的使用方项目 ID。
实例 ID	my-mpc-instance	MPC 实例的 ID ([a-z]([a-z0-9-]{0,61}[a-z0-9])?)。
位置	us-central1	部署位置（例如 us-central1）。
Admin 1 主账号	[e-mail]	实例中第一个 ADMIN 用户的Google Cloud 电子邮件地址或 BYOID 主账号。
管理员 2 主账号	[e-mail]	Google Cloud 实例中第二个 ADMIN 用户的电子邮件或 BYOID 主账号。
Signer 1 Principal	[e-mail]	签名者 1 (Alice) 的Google Cloud 电子邮件或 BYOID 主账号。
签署者 2 主账号	[e-mail]	签名者 2 (Bob) 的Google Cloud 电子邮件或 BYOID 主账号。
Signer 3 Principal	[e-mail]	Google Cloud 签署者 3 (Charlie) 的电子邮件或 BYOID 主账号。
Policy Author 1 Principal	[e-mail]	Google Cloud 政策作者 1 (Dave) 的电子邮件地址或 BYOID 主账号。
Policy Author 2 Principal	[e-mail]	Google Cloud 政策作者 2 (Eve) 的电子邮件地址或 BYOID 主账号。

在终端会话中对每个账号进行一次身份验证，以便 gcloud auth print-access-token "<principal>" 可以检索任何角色的令牌，而无需在教程中切换账号（ADMIN_1_PRINCIPAL 最后进行身份验证，因此它仍然是 IAM 和 Cloud KMS 命令的活跃 gcloud CLI 账号）：

for PRINCIPAL in \
  "[e-mail]" \
  "[e-mail]" \
  "[e-mail]" \
  "[e-mail]" \
  "[e-mail]" \
  "[e-mail]" \
  "[e-mail]"; do
  gcloud auth login "$PRINCIPAL"
done

教程资源标签

这些是本教程中使用 Cloud KMS 创建的授权密钥的本地标识符。默认值有效，可以保留，以尽可能减少设置过程中的阻碍。请注意，Team、User、TransactionPolicy、KeyRing、Key、KeyList 和 Transaction 资源的资源 ID 是在创建每个资源时由服务器生成并捕获到 shell 变量（TEAM_NAME、SIGNER_1_NAME、POLICY_NAME、KEY_RING_NAME、KEY_NAME、KEY_LIST_NAME、TRANSACTION_NAME）中的。

参数	值	说明
Cloud KMS 密钥环 ID	mpc-assent-keys	Cloud Key Management Service 密钥环，用于存储在 Cloud KMS 中的外部授权密钥。
Cloud KMS Admin 1 ID	admin-1	MPC 管理员 1 授权密钥标签。
Cloud KMS Admin 2 ID	admin-2	MPC Admin 2 授权密钥标签。
Cloud KMS 签名者 1 ID	signer-alice	MPC 签名者 1 授权密钥标签。
Cloud KMS 签名者 2 ID	signer-bob	MPC 签名者 2 授权密钥标签。
Cloud KMS 签名者 3 ID	signer-charlie	MPC 签名者 3 授权密钥标签。
Cloud KMS Policy Author 1 ID	author-dave	政策作者 1 授权密钥标签。
Cloud KMS Policy Author 2 ID	author-eve	政策作者 2 授权密钥标签。

---

第 1 步：创建 MPC 实例

MPC Instance 表示您的专用、隔离式 MPC 环境。如需创建和管理实例，您需要拥有项目的多方计算管理员 (roles/mpc.admin) IAM 角色。您以管理员身份在控制平面端点 (https://mpc.googleapis.com) 上使用 MPCInstanceService 创建和检查 Instance，并将所有后续资源请求发送到实例的专用数据平面网址 (INSTANCE_URL)。

A. 创建实例

首先，确保您的管理员主账号（[e-mail] 和 [e-mail]）对项目拥有 roles/mpc.admin 权限，并以管理员 1 的身份调用 instances.create (CreateInstance) 来预配 MPC 实例：

curl

grant_iam_role() {
  local principal=$1
  local iam_role=$2
  local member="user:${principal}"

  # BYOID principals already start with "principal://"
  if [[ "$principal" == principal://* ]]; then
    member="${principal}"
  fi

  echo "Granting ${iam_role} to ${member}..."
  gcloud projects add-iam-policy-binding "my-project" \
    --member="${member}" \
    --role="${iam_role}" \
    --condition=None > /dev/null
}

for ADMIN_PRINCIPAL in "[e-mail]" "[e-mail]"; do
  grant_iam_role "$ADMIN_PRINCIPAL" "roles/mpc.admin"
done

export INSTANCE_NAME="projects/my-project/locations/us-central1/instances/my-mpc-instance"

# Check existence
if curl -s -f -o /dev/null -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "https://mpc.googleapis.com/v1beta/${INSTANCE_NAME}"; then
  echo "Instance 'my-mpc-instance' already exists. Skipping creation."
else
  echo "Instance 'my-mpc-instance' not found. Creating..."
  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d '{
      "displayName": "Tutorial MPC Instance"
    }' \
    "https://mpc.googleapis.com/v1beta/projects/my-project/locations/us-central1/instances?instanceId=my-mpc-instance" | jq
fi

此操作会返回一个长时间运行的操作 (LRO)。您必须等待实例 state 变为 ACTIVE，然后才能调用其数据平面网址。

🕵️‍♂️ 检查实例状态（轮询）

轮询实例状态，直到 state 变为 ACTIVE，然后将其 url 字段保存到 INSTANCE_URL：

curl

INSTANCE_INFO=$(curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "https://mpc.googleapis.com/v1beta/${INSTANCE_NAME}")

echo "$INSTANCE_INFO" | jq
export INSTANCE_URL=$(echo "$INSTANCE_INFO" | jq -r '.url')
echo "Instance Data Plane URL: $INSTANCE_URL"

---

第 2 步：生成授权密钥

如需使用 MPC API，您必须为以下不同角色生成密钥对。请注意，这些是外部加密授权密钥 (User.authorizationKey)，这意味着您需要在 MPC 实例之外生成和保管这些密钥，因此它们与密钥创建期间生成的 MPC 密钥共享不同：

• 管理员：授权更改 ADMIN 和 POLICY_AUTHOR 用户角色，以及创建 Key。
• 政策作者：授权治理政策 (TransactionPolicy)。
• 签名者：为交易提供授权（AUTHORIZE 或 DENY）。

为签名者、政策作者和管理员生成 secp256k1 加密授权密钥。这些命令具有幂等性。

Cloud KMS

我们建议您在 Cloud Key Management Service 中管理授权密钥。确保您的身份有权创建密钥环、创建密钥、签名和查看公钥验证器（例如 roles/cloudkms.admin 和 roles/cloudkms.signerVerifier）。确保您已创建 KeyRing，然后为每个签名者、政策作者和管理员生成 secp256k1 密钥。

provision_keyring() {
  if gcloud kms keyrings describe "mpc-assent-keys" --location="us-central1" > /dev/null 2>&1; then
    echo "KeyRing 'mpc-assent-keys' already exists."
  else
    echo "KeyRing 'mpc-assent-keys' not found. Creating it..."
    gcloud kms keyrings create "mpc-assent-keys" --location="us-central1"
  fi
}

provision_kms_key() {
  local id=$1
  if gcloud kms keys describe "${id}-key" --keyring="mpc-assent-keys" --location="us-central1" > /dev/null 2>&1; then
    echo "KMS key '${id}-key' already exists."
  else
    echo "KMS key '${id}-key' not found. Creating it..."
    gcloud kms keys create "${id}-key" \
      --keyring="mpc-assent-keys" \
      --location="us-central1" \
      --purpose=asymmetric-signing \
      --default-algorithm=ec-sign-secp256k1-sha256 \
      --protection-level=hsm
  fi

  gcloud kms keys versions get-public-key 1 \
    --key="${id}-key" \
    --keyring="mpc-assent-keys" \
    --location="us-central1" \
    --output-file="${id}_pub.pem"

  echo "Retrieved public key from KMS and saved to ${id}_pub.pem:"
  cat "${id}_pub.pem"
}

# Run Setup
provision_keyring

# Generate Keys for Signers, Policy Authors, and Admins
for ID in \
  signer-alice \
  signer-bob \
  signer-charlie \
  author-dave \
  author-eve \
  admin-1 \
  admin-2; do
  echo "Generating KMS key for $ID..."
  provision_kms_key "$ID"
done

OpenSSL

您可以使用标准 OpenSSL 为每个签名者、政策作者和管理员生成 secp256k1 密钥。

provision_openssl_key() {
  local id=$1
  if [[ ! -f "${id}_priv.pem" ]]; then
    openssl ecparam -name secp256k1 -genkey -noout -out "${id}_priv.pem"
    openssl ec -in "${id}_priv.pem" -pubout -out "${id}_pub.pem"
    echo "Wrote private key to ${id}_priv.pem and public key to ${id}_pub.pem:"
    cat "${id}_pub.pem"
  else
    echo "Private key file '${id}_priv.pem' already exists. Skipping OpenSSL generation."
    echo "Using existing public key from '${id}_pub.pem':"
    cat "${id}_pub.pem"
  fi
}

for ID in \
  signer-alice \
  signer-bob \
  signer-charlie \
  author-dave \
  author-eve \
  admin-1 \
  admin-2; do
  echo "Generating OpenSSL key for $ID..."
  provision_openssl_key "$ID"
done

---

第 3 步：注册团队和用户

任何实体都必须先获得项目的 IAM 权限，并在实例中注册为应用级 User，然后才能参与交易签名（作为 SIGNER）或政策编写（作为 POLICY_AUTHOR）（如需了解 IAM 角色和 User 角色如何协同工作，请参阅安全和授权）。

注册需要管理员和用户之间的带外协调：

1. 实体（签名者或政策作者）在本地生成密钥对，并安全地将公钥传输给管理员。
2. 管理员向用户的账号授予项目的适当 IAM 角色（签名者和政策作者为 roles/mpc.editor；管理员为 roles/mpc.admin），并调用 MPC API 来注册用户的 principal 和 authorizationKey。

注意： 未来的预览版将用带内邀请流程取代这种带外密钥交接，其中管理员按主账号邀请用户，每个用户登录后直接注册自己的 authorizationKey 即可完成初始配置。

A. 创建签名者团队

每个具有 SIGNER 角色的 User 都必须属于一个 Team，而具有其他角色的所有其他 User 都不能属于 Team。以管理员 1 ([e-mail]) 的身份，创建一个“Treasury Signers”Team (CreateTeam) 来存放您的三个签名者，并捕获其服务器生成的资源 name：

curl

TEAM_RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Treasury Signers",
  }' \
  "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/teams?requestId=11111111-1111-4111-8111-111111111101")

echo "$TEAM_RESPONSE" | jq
export TEAM_NAME=$(echo "$TEAM_RESPONSE" | jq -r '.name')
echo "Created Team: $TEAM_NAME"

B. 授予 IAM 角色并注册签名者和政策作者

每个用户都需要一个项目级 IAM 角色（签名者和政策作者需要 roles/mpc.editor，管理员需要 roles/mpc.admin）来调用 MPC API，并且需要在实例中拥有一个应用级 User 资源。调用 users.create (CreateUser) 时，roles 字段只能为空或 ["SIGNER"]：

• 签名者：在 IAM 中授予 roles/mpc.editor，并使用 roles: ["SIGNER"] 和 team: "$TEAM_NAME" 创建。SIGNER 角色会立即变为 ACTIVE，无需管理员法定人数批准，因为仅拥有 SIGNER 角色并不会授予对任何现有密钥的访问权限；只有在密钥生成期间被纳入 KeyRing 的 KeyPolicy 中时，签名者才会收到密钥共享。

• 政策作者：在 IAM 中被授予 roles/mpc.editor，创建时没有初始角色，也没有 team，然后在第 3.C 步中使用管理员法定人数审批被授予 POLICY_AUTHOR 角色（因为 POLICY_AUTHOR 和 ADMIN 具有实例级治理权限）。

curl

provision_user() {
  local id=$1
  local display_name=$2
  local principal=$3
  local request_id=$4
  local team=$5
  local pubkey_b64
  local signer_fields=""

  # 1. Grant project-level IAM permission (roles/mpc.editor) to the User's principal
  grant_iam_role "$principal" "roles/mpc.editor" >&2

  # 2. Read the public key from the file generated in Step 2 (Base64-encoded PEM/DER bytes)
  pubkey_b64=$(openssl base64 -A -in "${id}_pub.pem")

  if [[ -n "$team" ]]; then
    signer_fields=", \"roles\": [\"SIGNER\"], \"team\": \"${team}\""
  fi

  # 3. Register the application-level User in the MPC instance as Admin 1
  curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d "{
      \"displayName\": \"${display_name}\",
      \"principal\": \"${principal}\",
      \"authorizationKey\": {
        \"publicKey\": \"${pubkey_b64}\",
        \"algorithm\": \"PUBLIC_KEY_SIGNATURE_ALGORITHM_ECDSA_SECP256K1\"
      }${signer_fields}
    }" \
    "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/users?requestId=${request_id}"
}

echo "Registering Signers..."
export SIGNER_1_NAME=$(provision_user "signer-alice" "Signer Alice" "[e-mail]" "11111111-1111-4111-8111-111111111001" "${TEAM_NAME}" | tee /dev/stderr | jq -r '.name')
export SIGNER_2_NAME=$(provision_user "signer-bob" "Signer Bob" "[e-mail]" "11111111-1111-4111-8111-111111111002" "${TEAM_NAME}" | tee /dev/stderr | jq -r '.name')
export SIGNER_3_NAME=$(provision_user "signer-charlie" "Signer Charlie" "[e-mail]" "11111111-1111-4111-8111-111111111003" "${TEAM_NAME}" | tee /dev/stderr | jq -r '.name')

echo "Registering Policy Authors..."
export POLICY_AUTHOR_1_NAME=$(provision_user "author-dave" "Author Dave" "[e-mail]" "11111111-1111-4111-8111-111111111004" | tee /dev/stderr | jq -r '.name')
export POLICY_AUTHOR_2_NAME=$(provision_user "author-eve" "Author Eve" "[e-mail]" "11111111-1111-4111-8111-111111111005" | tee /dev/stderr | jq -r '.name')

C. 授予 Policy Author 角色（管理员法定人数审批）

在 User 上启用或停用 POLICY_AUTHOR 或 ADMIN 角色需要达到管理员法定人数：

1. 管理员 1 调用 users.enableRole (EnableUserRole)，这会将角色移至 PENDING_ACTIVE，并将管理员 1 的签名记录为第一个批准。
2. 管理员 2 使用其签名调用 users.approveRoleChange (ApproveRoleChange)，将角色转换为 ACTIVE。

重要提示： 用户角色签名结构 (UserSigningPayload)：每位管理员都会对序列化的 google.cloud.mpc.v1beta.UserSigningPayload protobuf 消息（instance = 1、principal = 2、authorization_key = 3、role_changes = 4 以及 role = 1、action = 2、version = 3）进行签名，并在 authorizationInfo 中传递 "signature" 和 "signedPayload"。User无法请求或批准自己的角色更改 (PERMISSION_DENIED)。

Cloud KMS

1. 以管理员 1 (EnableUserRole) 的身份请求 POLICY_AUTHOR

sign_role_change() {
  local admin_id=$1
  local target_id=$2
  local principal=$3
  python3 -c 'import sys; inst, prin, pub = sys.argv[1], sys.argv[2], open(sys.argv[3], "rb").read(); v = lambda n: bytes([n & 127 | 128]) + v(n >> 7) if n > 127 else bytes([n]); f = lambda k, b: bytes([k << 3 | 2]) + v(len(b)) + b; open("role_payload.bin", "wb").write(f(1, inst.encode()) + f(2, prin.encode()) + f(3, f(1, pub) + b"\x10\x01") + f(4, b"\x08\x02\x10\x01\x18\x01"))' "${INSTANCE_NAME}" "${principal}" "${target_id}_pub.pem"
  gcloud kms asymmetric-sign \
    --version=1 \
    --key="${admin_id}-key" \
    --keyring="mpc-assent-keys" \
    --location="us-central1" \
    --digest-algorithm=sha256 \
    --input-file=role_payload.bin \
    --signature-file=role_sig.bin > /dev/null
  openssl base64 -A -in role_sig.bin
}

enable_policy_author() {
  local target_user=$1
  local target_id=$2
  local target_principal=$3

  echo "Admin 1 requesting POLICY_AUTHOR for ${target_user}..."
  local admin_1_sig=$(sign_role_change "admin-1" "${target_id}" "${target_principal}")
  local signed_payload_b64=$(openssl base64 -A -in role_payload.bin)

  curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d "{
      \"role\": \"POLICY_AUTHOR\",
      \"authorizationInfo\": {
        \"signature\": \"${admin_1_sig}\",
        \"signedPayload\": \"${signed_payload_b64}\"
      }
    }" \
    "${INSTANCE_URL}/v1beta/${target_user}:enableRole" | jq
}

enable_policy_author "${POLICY_AUTHOR_1_NAME}" "author-dave" "[e-mail]"
enable_policy_author "${POLICY_AUTHOR_2_NAME}" "author-eve" "[e-mail]"

2. 以管理员 2 (ApproveRoleChange) 的身份批准 POLICY_AUTHOR

approve_policy_author() {
  local target_user=$1
  local target_id=$2
  local target_principal=$3

  echo "Admin 2 approving POLICY_AUTHOR for ${target_user}..."
  local admin_2_sig=$(sign_role_change "admin-2" "${target_id}" "${target_principal}")
  local signed_payload_b64=$(openssl base64 -A -in role_payload.bin)

  curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d "{
      \"authorizationInfo\": {
        \"signature\": \"${admin_2_sig}\",
        \"signedPayload\": \"${signed_payload_b64}\"
      }
    }" \
    "${INSTANCE_URL}/v1beta/${target_user}:approveRoleChange" | jq
}

approve_policy_author "${POLICY_AUTHOR_1_NAME}" "author-dave" "[e-mail]"
approve_policy_author "${POLICY_AUTHOR_2_NAME}" "author-eve" "[e-mail]"

OpenSSL

1. 以管理员 1 (EnableUserRole) 的身份请求 POLICY_AUTHOR

sign_role_change() {
  local admin_id=$1
  local target_id=$2
  local principal=$3
  python3 -c 'import sys; inst, prin, pub = sys.argv[1], sys.argv[2], open(sys.argv[3], "rb").read(); v = lambda n: bytes([n & 127 | 128]) + v(n >> 7) if n > 127 else bytes([n]); f = lambda k, b: bytes([k << 3 | 2]) + v(len(b)) + b; open("role_payload.bin", "wb").write(f(1, inst.encode()) + f(2, prin.encode()) + f(3, f(1, pub) + b"\x10\x01") + f(4, b"\x08\x02\x10\x01\x18\x01"))' "${INSTANCE_NAME}" "${principal}" "${target_id}_pub.pem"
  openssl dgst -sha256 -sign "${admin_id}_priv.pem" -out role_sig.bin role_payload.bin
  openssl base64 -A -in role_sig.bin
}

enable_policy_author() {
  local target_user=$1
  local target_id=$2
  local target_principal=$3

  echo "Admin 1 requesting POLICY_AUTHOR for ${target_user}..."
  local admin_1_sig=$(sign_role_change "admin-1" "${target_id}" "${target_principal}")
  local signed_payload_b64=$(openssl base64 -A -in role_payload.bin)

  curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d "{
      \"role\": \"POLICY_AUTHOR\",
      \"authorizationInfo\": {
        \"signature\": \"${admin_1_sig}\",
        \"signedPayload\": \"${signed_payload_b64}\"
      }
    }" \
    "${INSTANCE_URL}/v1beta/${target_user}:enableRole" | jq
}

enable_policy_author "${POLICY_AUTHOR_1_NAME}" "author-dave" "[e-mail]"
enable_policy_author "${POLICY_AUTHOR_2_NAME}" "author-eve" "[e-mail]"

2. 以管理员 2 (ApproveRoleChange) 的身份批准 POLICY_AUTHOR

approve_policy_author() {
  local target_user=$1
  local target_id=$2
  local target_principal=$3

  echo "Admin 2 approving POLICY_AUTHOR for ${target_user}..."
  local admin_2_sig=$(sign_role_change "admin-2" "${target_id}" "${target_principal}")
  local signed_payload_b64=$(openssl base64 -A -in role_payload.bin)

  curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d "{
      \"authorizationInfo\": {
        \"signature\": \"${admin_2_sig}\",
        \"signedPayload\": \"${signed_payload_b64}\"
      }
    }" \
    "${INSTANCE_URL}/v1beta/${target_user}:approveRoleChange" | jq
}

approve_policy_author "${POLICY_AUTHOR_1_NAME}" "author-dave" "[e-mail]"
approve_policy_author "${POLICY_AUTHOR_2_NAME}" "author-eve" "[e-mail]"

---

第 4 步：配置交易政策

通过创建并批准 TransactionPolicy（以及可选的 KeyList）来配置交易政策。

A. 创建政策 (PENDING_ACTIVE)

创建 Cedar 政策规则，描述允许哪些事务。虽然您可以配置多项政策来管理不同的场景，但本指南仅演示如何为以太坊或比特币交易设置政策。默认情况下，交易政策评估为快速失败（默认屏蔽）；如果没有有效的 permit 政策与交易匹配，则政策评估决策为 DENY。如需详细了解 Cedar 属性，请参阅编写事务政策规则。

重要提示： 仲裁签名结构 (TransactionPolicySigningPayload)：在创建、批准或停用政策之前，具有有效 POLICY_AUTHOR 角色的 User 会对序列化的 google.cloud.mpc.v1beta.TransactionPolicySigningPayload protobuf 消息进行签名：instance = 1（对于 CreateTransactionPolicy）或 transaction_policy = 2（对于 ApproveTransactionPolicy 和 DisableTransactionPolicy）、action = 3（ACTIVATE = 1 或 DISABLE = 2）以及 rule = 4 (cedar_document = 1)。已签名载荷中的 cedar_document 字符串必须与 API 请求中的 transactionPolicy.rule.cedarDocument 逐字节匹配，否则签名验证会失败。

Ethereum、KMS

此规则允许向特定收款人地址 (0x1111111111111111111111111111111111111111) 进行较小金额的以太坊转账（<= 2 ETH，以 10^-9 ETH / Gwei 为单位，表示为 2,000,000,000）。

permit (principal, action, resource)
when {
  context.schema == "ETHEREUM_TX_V2" &&
  context.secondary_key == "0x1111111111111111111111111111111111111111" &&
  context has amount_token_scaled &&
  context.amount_token_scaled <= 2000000000
};

sign_policy() {
  local author_id=$1
  local resource_type=$2
  local resource_name=$3
  local action=$4
  local cedar_doc=$5
  python3 -c 'import sys; rt, rn, act, doc = sys.argv[1:]; v = lambda n: bytes([n & 127 | 128]) + v(n >> 7) if n > 127 else bytes([n]); f = lambda k, b: bytes([k << 3 | 2]) + v(len(b)) + b; open("policy_payload.bin", "wb").write(f(1 if rt == "instance" else 2, rn.encode()) + bytes([24, 1 if act == "ACTIVATE" else 2]) + f(4, f(1, doc.encode())))' "${resource_type}" "${resource_name}" "${action}" "${cedar_doc}"
  gcloud kms asymmetric-sign \
    --version=1 \
    --key="${author_id}-key" \
    --keyring="mpc-assent-keys" \
    --location="us-central1" \
    --digest-algorithm=sha256 \
    --input-file=policy_payload.bin \
    --signature-file=policy_sig.bin > /dev/null
  openssl base64 -A -in policy_sig.bin
}

export CEDAR_RULE='permit (principal, action, resource) when { context.schema == "ETHEREUM_TX_V2" && context.secondary_key == "0x1111111111111111111111111111111111111111" && context has amount_token_scaled && context.amount_token_scaled <= 2000000000 };'

# Sign as Policy Author 1
QUORUM_SIGNATURE=$(sign_policy "author-dave" "instance" "${INSTANCE_NAME}" "ACTIVATE" "${CEDAR_RULE}")
POLICY_PAYLOAD_B64=$(openssl base64 -A -in policy_payload.bin)

POLICY_RESPONSE=$(jq -n \
  --arg rule "$CEDAR_RULE" \
  --arg sig "$QUORUM_SIGNATURE" \
  --arg payload "$POLICY_PAYLOAD_B64" \
  '{
    transactionPolicy: {
      displayName: "Ethereum Transfer Permit Policy",
      rule: {cedarDocument: $rule}
    },
    authorizationInfo: {
      signature: $sig,
      signedPayload: $payload
    },
    requestId: "11111111-1111-4111-8111-111111111201"
  }' \
| curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d @- \
    "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/transactionPolicies")

echo "$POLICY_RESPONSE" | jq
export POLICY_NAME=$(echo "$POLICY_RESPONSE" | jq -r '.name')

Ethereum、OpenSSL

此规则允许向特定收款人地址 (0x1111111111111111111111111111111111111111) 进行较小金额的以太坊转账（<= 2 ETH，以 10^-9 ETH / Gwei 为单位，表示为 2,000,000,000）。

permit (principal, action, resource)
when {
  context.schema == "ETHEREUM_TX_V2" &&
  context.secondary_key == "0x1111111111111111111111111111111111111111" &&
  context has amount_token_scaled &&
  context.amount_token_scaled <= 2000000000
};

sign_policy() {
  local author_id=$1
  local resource_type=$2
  local resource_name=$3
  local action=$4
  local cedar_doc=$5
  python3 -c 'import sys; rt, rn, act, doc = sys.argv[1:]; v = lambda n: bytes([n & 127 | 128]) + v(n >> 7) if n > 127 else bytes([n]); f = lambda k, b: bytes([k << 3 | 2]) + v(len(b)) + b; open("policy_payload.bin", "wb").write(f(1 if rt == "instance" else 2, rn.encode()) + bytes([24, 1 if act == "ACTIVATE" else 2]) + f(4, f(1, doc.encode())))' "${resource_type}" "${resource_name}" "${action}" "${cedar_doc}"
  openssl dgst -sha256 -sign "${author_id}_priv.pem" -out policy_sig.bin policy_payload.bin
  openssl base64 -A -in policy_sig.bin
}

export CEDAR_RULE='permit (principal, action, resource) when { context.schema == "ETHEREUM_TX_V2" && context.secondary_key == "0x1111111111111111111111111111111111111111" && context has amount_token_scaled && context.amount_token_scaled <= 2000000000 };'

# Sign as Policy Author 1
QUORUM_SIGNATURE=$(sign_policy "author-dave" "instance" "${INSTANCE_NAME}" "ACTIVATE" "${CEDAR_RULE}")
POLICY_PAYLOAD_B64=$(openssl base64 -A -in policy_payload.bin)

POLICY_RESPONSE=$(jq -n \
  --arg rule "$CEDAR_RULE" \
  --arg sig "$QUORUM_SIGNATURE" \
  --arg payload "$POLICY_PAYLOAD_B64" \
  '{
    transactionPolicy: {
      displayName: "Ethereum Transfer Permit Policy",
      rule: {cedarDocument: $rule}
    },
    authorizationInfo: {
      signature: $sig,
      signedPayload: $payload
    },
    requestId: "11111111-1111-4111-8111-111111111201"
  }' \
| curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d @- \
    "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/transactionPolicies")

echo "$POLICY_RESPONSE" | jq
export POLICY_NAME=$(echo "$POLICY_RESPONSE" | jq -r '.name')

比特币、KMS

此规则允许使用 BITCOIN_TX_V2 架构 (BIP 174 PSBT v0) 进行比特币转账，前提是净出站转账金额不超过 250,000 聪（context.amount_token_scaled <= 2500000，或 0.0025 BTC，标准化为 10^-9 固定小数单位），且矿工费不超过 10,000 聪 (context.max_fee_atomic <= 100000)。

permit (principal, action, resource)
when {
  context.schema == "BITCOIN_TX_V2" &&
  context has amount_token_scaled &&
  context.amount_token_scaled <= 2500000 &&
  context.max_fee_atomic <= 100000
};

sign_policy() {
  local author_id=$1
  local resource_type=$2
  local resource_name=$3
  local action=$4
  local cedar_doc=$5
  python3 -c 'import sys; rt, rn, act, doc = sys.argv[1:]; v = lambda n: bytes([n & 127 | 128]) + v(n >> 7) if n > 127 else bytes([n]); f = lambda k, b: bytes([k << 3 | 2]) + v(len(b)) + b; open("policy_payload.bin", "wb").write(f(1 if rt == "instance" else 2, rn.encode()) + bytes([24, 1 if act == "ACTIVATE" else 2]) + f(4, f(1, doc.encode())))' "${resource_type}" "${resource_name}" "${action}" "${cedar_doc}"
  gcloud kms asymmetric-sign \
    --version=1 \
    --key="${author_id}-key" \
    --keyring="mpc-assent-keys" \
    --location="us-central1" \
    --digest-algorithm=sha256 \
    --input-file=policy_payload.bin \
    --signature-file=policy_sig.bin > /dev/null
  openssl base64 -A -in policy_sig.bin
}

export CEDAR_RULE='permit (principal, action, resource) when { context.schema == "BITCOIN_TX_V2" && context has amount_token_scaled && context.amount_token_scaled <= 2500000 && context.max_fee_atomic <= 100000 };'

# Sign as Policy Author 1
QUORUM_SIGNATURE=$(sign_policy "author-dave" "instance" "${INSTANCE_NAME}" "ACTIVATE" "${CEDAR_RULE}")
POLICY_PAYLOAD_B64=$(openssl base64 -A -in policy_payload.bin)

POLICY_RESPONSE=$(jq -n \
  --arg rule "$CEDAR_RULE" \
  --arg sig "$QUORUM_SIGNATURE" \
  --arg payload "$POLICY_PAYLOAD_B64" \
  '{
    transactionPolicy: {
      displayName: "Bitcoin PSBT Permit Policy",
      rule: {cedarDocument: $rule}
    },
    authorizationInfo: {
      signature: $sig,
      signedPayload: $payload
    },
    requestId: "11111111-1111-4111-8111-111111111202"
  }' \
| curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d @- \
    "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/transactionPolicies")

echo "$POLICY_RESPONSE" | jq
export POLICY_NAME=$(echo "$POLICY_RESPONSE" | jq -r '.name')

Bitcoin、OpenSSL

此规则允许使用 BITCOIN_TX_V2 架构 (BIP 174 PSBT v0) 进行比特币转账，前提是净出站转账金额不超过 250,000 聪（context.amount_token_scaled <= 2500000，或 0.0025 BTC，标准化为 10^-9 固定小数单位），且矿工费不超过 10,000 聪 (context.max_fee_atomic <= 100000)。

permit (principal, action, resource)
when {
  context.schema == "BITCOIN_TX_V2" &&
  context has amount_token_scaled &&
  context.amount_token_scaled <= 2500000 &&
  context.max_fee_atomic <= 100000
};

sign_policy() {
  local author_id=$1
  local resource_type=$2
  local resource_name=$3
  local action=$4
  local cedar_doc=$5
  python3 -c 'import sys; rt, rn, act, doc = sys.argv[1:]; v = lambda n: bytes([n & 127 | 128]) + v(n >> 7) if n > 127 else bytes([n]); f = lambda k, b: bytes([k << 3 | 2]) + v(len(b)) + b; open("policy_payload.bin", "wb").write(f(1 if rt == "instance" else 2, rn.encode()) + bytes([24, 1 if act == "ACTIVATE" else 2]) + f(4, f(1, doc.encode())))' "${resource_type}" "${resource_name}" "${action}" "${cedar_doc}"
  openssl dgst -sha256 -sign "${author_id}_priv.pem" -out policy_sig.bin policy_payload.bin
  openssl base64 -A -in policy_sig.bin
}

export CEDAR_RULE='permit (principal, action, resource) when { context.schema == "BITCOIN_TX_V2" && context has amount_token_scaled && context.amount_token_scaled <= 2500000 && context.max_fee_atomic <= 100000 };'

# Sign as Policy Author 1
QUORUM_SIGNATURE=$(sign_policy "author-dave" "instance" "${INSTANCE_NAME}" "ACTIVATE" "${CEDAR_RULE}")
POLICY_PAYLOAD_B64=$(openssl base64 -A -in policy_payload.bin)

POLICY_RESPONSE=$(jq -n \
  --arg rule "$CEDAR_RULE" \
  --arg sig "$QUORUM_SIGNATURE" \
  --arg payload "$POLICY_PAYLOAD_B64" \
  '{
    transactionPolicy: {
      displayName: "Bitcoin PSBT Permit Policy",
      rule: {cedarDocument: $rule}
    },
    authorizationInfo: {
      signature: $sig,
      signedPayload: $payload
    },
    requestId: "11111111-1111-4111-8111-111111111202"
  }' \
| curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d @- \
    "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/transactionPolicies")

echo "$POLICY_RESPONSE" | jq
export POLICY_NAME=$(echo "$POLICY_RESPONSE" | jq -r '.name')

B. 批准政策（转换为 ACTIVE）

政策变更需要 2 个签名，因此第二位政策作者必须使用已签名的 TransactionPolicySigningPayload 调用 transactionPolicies.approve (ApproveTransactionPolicy)。

以太坊

# 1. Check the policy state
POLICY_INFO=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${POLICY_NAME}")

POLICY_STATE=$(echo "$POLICY_INFO" | jq -r '.state // "UNKNOWN"')

if [ "$POLICY_STATE" == "PENDING_ACTIVE" ]; then
  # 2. Sign as Policy Author 2 naming transaction_policy ($POLICY_NAME)
  QUORUM_SIGNATURE_2=$(sign_policy "author-eve" "transaction_policy" "${POLICY_NAME}" "ACTIVATE" "${CEDAR_RULE}")
  POLICY_PAYLOAD_2_B64=$(openssl base64 -A -in policy_payload.bin)

  # 3. Call ApproveTransactionPolicy as Policy Author 2
  curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d "{
      \"authorizationInfo\": {
        \"signature\": \"${QUORUM_SIGNATURE_2}\",
        \"signedPayload\": \"${POLICY_PAYLOAD_2_B64}\"
      }
    }" \
    "${INSTANCE_URL}/v1beta/${POLICY_NAME}:approve" | jq
elif [ "$POLICY_STATE" == "ACTIVE" ]; then
  echo "Policy '${POLICY_NAME}' is already ACTIVE. Skipping approval."
else
  echo "Policy '${POLICY_NAME}' is in an unexpected state: $POLICY_STATE"
fi

比特币

# 1. Check the policy state
POLICY_INFO=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${POLICY_NAME}")

POLICY_STATE=$(echo "$POLICY_INFO" | jq -r '.state // "UNKNOWN"')

if [ "$POLICY_STATE" == "PENDING_ACTIVE" ]; then
  # 2. Sign as Policy Author 2 naming transaction_policy ($POLICY_NAME)
  QUORUM_SIGNATURE_2=$(sign_policy "author-eve" "transaction_policy" "${POLICY_NAME}" "ACTIVATE" "${CEDAR_RULE}")
  POLICY_PAYLOAD_2_B64=$(openssl base64 -A -in policy_payload.bin)

  # 3. Call ApproveTransactionPolicy as Policy Author 2
  curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d "{
      \"authorizationInfo\": {
        \"signature\": \"${QUORUM_SIGNATURE_2}\",
        \"signedPayload\": \"${POLICY_PAYLOAD_2_B64}\"
      }
    }" \
    "${INSTANCE_URL}/v1beta/${POLICY_NAME}:approve" | jq
elif [ "$POLICY_STATE" == "ACTIVE" ]; then
  echo "Policy '${POLICY_NAME}' is already ACTIVE. Skipping approval."
else
  echo "Policy '${POLICY_NAME}' is in an unexpected state: $POLICY_STATE"
fi

C. 创建和管理 KeyList（可选）

KeyList (KeyListService) 是一个命名的区块链地址（manualEntry、MPC key 或 keyRing）列表，政策可以将其作为可信目标进行引用。管理员 (ADMIN) 可以使用 keyLists.create 创建 KeyList，并随时使用 keyLists.addEntries 和 keyLists.removeEntries 更新其条目：

curl

KEY_LIST_RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Approved Destinations",
    "description": "Trusted recipient addresses",
    "entries": [
      {
        "manualEntry": {
          "address": "0x1111111111111111111111111111111111111111",
          "source": "Treasury onboarding",
          "reason": "Approved recipient address"
        }
      }
    ]
  }' \
  "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/keyLists?requestId=11111111-1111-4111-8111-111111111301")

echo "$KEY_LIST_RESPONSE" | jq
export KEY_LIST_NAME=$(echo "$KEY_LIST_RESPONSE" | jq -r '.name')

---

第 5 步：创建密钥

以管理员 1 ([e-mail]) 的身份，创建一个包含内嵌 KeyPolicy 的 KeyRing，并生成分布式 MPC 密钥。

A. 使用内嵌 KeyPolicy 创建 KeyRing

KeyRing 是 MPC 密钥的逻辑分组，用于定义不可变的内嵌 KeyPolicy (keyRing.keyPolicy)，在 KeyRing 中创建的每个密钥都遵循该。KeyPolicy 是阈值规则 (PolicyNode) 的树，其子 subKeyShares 可以是 teamNode（Team 中 totalMembers 的 threshold）、userNode（特定 SIGNER User）或嵌套 policyNode。

在这里，我们针对 ${TEAM_NAME} 中的三个签名者（threshold: 2、totalMembers: 3，存储在 GCP_TEE 中）配置了三分之二阈值规则：

curl

KEY_RING_RESPONSE=$(jq -n \
  --arg team "${TEAM_NAME}" \
  '{
    displayName: "Treasury KeyRing",
    keyPolicy: {
      policy: {
        policyNodeId: "treasury-2-of-3",
        threshold: 1,
        subKeyShares: [
          {
            teamNode: {
              team: $team,
              threshold: 2,
              totalMembers: 3,
              storageInfo: {storageType: "GCP_TEE"}
            }
          }
        ]
      }
    }
  }' \
| curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d @- \
    "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/keyRings?requestId=11111111-1111-4111-8111-111111111401")

echo "$KEY_RING_RESPONSE" | jq
export KEY_RING_NAME=$(echo "$KEY_RING_RESPONSE" | jq -r '.name')
echo "Created KeyRing: $KEY_RING_NAME"

B. 生成分布式密钥 (DKG)

以管理员 1 的身份调用 keys.create (CreateKey)，在 KeyRing 的 KeyPolicy 选择的参与者之间运行分布式密钥生成 (DKG)。

CreateKey 是同步的，会返回 ACTIVE Key 资源，包括 publicKeyInfo.publicKey 和服务器派生的 publicKeyInfo.blockchainAddresses（以太坊和比特币为 EC_SIGN_SECP256K1，Solana 为 EC_SIGN_ED25519 [一旦受支持]）：

curl

KEY_RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "EC_SIGN_SECP256K1"
  }' \
  "${INSTANCE_URL}/v1beta/${KEY_RING_NAME}/keys?requestId=11111111-1111-4111-8111-111111111501")

echo "$KEY_RESPONSE" | jq
export KEY_NAME=$(echo "$KEY_RESPONSE" | jq -r '.name')
export PUBLIC_KEY_B64=$(echo "$KEY_RESPONSE" | jq -r '.publicKeyInfo.publicKey')

C. 派生区块链地址并定位 UTXO

CreateKey 完成后，响应中的 publicKeyInfo.blockchainAddresses 会自动包含派生地址（EC_SIGN_SECP256K1 的 secp256k1Addresses.ethereumAddress 和 secp256k1Addresses.bitcoinMainnetAddresses，或 EC_SIGN_ED25519 的 ed25519Addresses.solanaAddress）。您还可以使用以下脚本，从 65 字节的未压缩公钥 (0x04 || X || Y) 中独立验证或派生 Testnet 地址和锁定脚本，并找到交易所需的任何未花费资金。

以太坊

以太坊地址以 .publicKeyInfo.blockchainAddresses.secp256k1Addresses.ethereumAddress 格式返回，也可以从 64 字节未压缩公钥点 (pub_bytes[1:]) 的 Keccak-256 哈希值中派生，取最后 20 个字节。

地址派生脚本 (derive_address.py)

执行以下代码块，以创建并运行 derive_address.py：

cat <<'EOF' > derive_address.py
import base64
from eth_utils import keccak, to_checksum_address

# Insert your base64 publicKey from Step 5.B
PUBLIC_KEY_B64 = "your-public-key"

pub_bytes = base64.b64decode(PUBLIC_KEY_B64)
if len(pub_bytes) == 65 and pub_bytes[0] == 4:
    raw_addr = "0x" + keccak(pub_bytes[1:])[-20:].hex()
    checksummed_addr = to_checksum_address(raw_addr)
    print("Ethereum Address:", checksummed_addr)
else:
    print(f"Error: Expected 65-byte uncompressed key, got {len(pub_bytes)} bytes.")
EOF
python3 derive_address.py

为以太坊地址充值

在第 7 步中广播之前，请确保您的派生以太坊地址有足够的 Sepolia 测试网 ETH 来支付交易价值和 gas 费用。您可以将新派生的地址输入到 Ethereum Sepolia 水龙头中，申请免费的测试网 ETH。

比特币

比特币主网地址（p2wpkhAddress、p2shP2wpkhAddress 和 p2pkhAddress）以 .publicKeyInfo.blockchainAddresses.secp256k1Addresses.bitcoinMainnetAddresses 格式返回。从 65 字节的未压缩 secp256k1 EC 公钥 (0x04 || X || Y) 中，您还可以推导出 33 字节的压缩公钥、锁定脚本以及所有三种格式的 Testnet4 地址：

1. 原生隔离见证 (P2WPKH / BIP 173)：Bech32 地址（主网上的 bc1q...，Testnet4 上的 tb1q...），具有 22 字节的见证 scriptPubKey (0014<hash160>)。这是推荐的现代格式，交易费用最低。
2. 嵌套隔离见证 (P2SH-P2WPKH / BIP 49)：封装的隔离见证地址（主网上的 3...，Testnet4 上的 2...），具有 23 字节的 scriptPubKey (a914<hash160>87) 和 22 字节的 redeemScript (0014<hash160>)，与旧系统兼容。
3. Legacy (P2PKH / BIP 44)：原始 Pay-to-PubKey-Hash Base58 地址（主网上的 1...，Testnet4 上的 m/n...），具有 25 字节的 scriptPubKey (76a914<hash160>88ac)。

地址派生脚本 (derive_btc_address.py)

执行以下代码块，以创建并运行 derive_btc_address.py：

cat <<'EOF' > derive_btc_address.py
"""Derives Bitcoin addresses (Native SegWit, Nested SegWit, Legacy) from an MPC public key using embit."""

import base64
from embit import ec, script
from embit.networks import NETWORKS

# Insert the Base64-encoded public key from Step 5.B (publicKeyInfo.publicKey, decodes to 65 raw bytes)
PUBLIC_KEY_B64 = "your-public-key"

raw_bytes = base64.b64decode(PUBLIC_KEY_B64)
if len(raw_bytes) != 65 or raw_bytes[0] != 4:
  raise ValueError(f"Expected 65-byte uncompressed public key (0x04...), got {len(raw_bytes)} bytes")

# 1. Parse and compress public key to 33 bytes
pub = ec.PublicKey.parse(raw_bytes)
pub.compressed = True
compressed_pubkey_hex = pub.sec().hex()

print("================================================================")
print(f"Compressed Public Key (33 bytes): {compressed_pubkey_hex}")
print("================================================================")

# 2. Native SegWit (P2WPKH - BIP 173)
p2wpkh = script.p2wpkh(pub)
print("\n[1. Native SegWit (P2WPKH / Bech32 - BIP 173)]")
print(f"  ScriptPubKey:           {p2wpkh.data.hex()}")
print(f"  Testnet4 Address (tb):  {p2wpkh.address(NETWORKS['test'])}")
print(f"  Mainnet Address (bc):   {p2wpkh.address(NETWORKS['main'])}")

# 3. Nested SegWit (P2SH-P2WPKH - BIP 49)
p2sh_p2wpkh = script.p2sh(p2wpkh)
print("\n[2. Nested SegWit (P2SH-P2WPKH / Base58 - BIP 49)]")
print(f"  RedeemScript:           {p2wpkh.data.hex()}")
print(f"  ScriptPubKey:           {p2sh_p2wpkh.data.hex()}")
print(f"  Testnet4 Address (2):   {p2sh_p2wpkh.address(NETWORKS['test'])}")
print(f"  Mainnet Address (3):    {p2sh_p2wpkh.address(NETWORKS['main'])}")

# 4. Legacy (P2PKH - BIP 44)
p2pkh = script.p2pkh(pub)
print("\n[3. Legacy (P2PKH / Base58 - BIP 44)]")
print(f"  ScriptPubKey:           {p2pkh.data.hex()}")
print(f"  Testnet4 Address (m/n): {p2pkh.address(NETWORKS['test'])}")
print(f"  Mainnet Address (1):    {p2pkh.address(NETWORKS['main'])}")
EOF

python3 derive_btc_address.py

定位未花费的输出 (UTXO)

与基于账号的区块链不同，比特币交易会花费特定的未花费交易输出 (UTXO)。在第 6 步中构建事务之前：

1. 为派生的原生隔离见证地址充值（例如，使用测试网水龙头）。
2. 使用您的比特币节点 (bitcoin-cli listunspent 1 9999999 "[\"tb1q...\"]") 或区块浏览器 API 查询您地址的未花费 UTXO。
3. 请注意第 6 步中的以下 4 个参数：
   • txid：未花费输出的 32 字节交易哈希。
   • vout：从零开始的输出索引（例如 0 或 1）。
   • value：未花费的金额，以聪为单位（例如，200000 聪 = 0.002 BTC）。
   • scriptPubKey：锁定脚本十六进制（例如 0014...）。

---

第 6 步：执行 MPC 操作

当 SIGNER 调用 transactions.create (CreateTransaction) 时，系统会同时进行政策评估和签名启动。实例会根据 schema 解码 payload，评估所有有效的交易政策，将结果记录在 policyEvaluationRecord 中，并记录发起签名者的 AUTHORIZE 决定。

A. 创建交易（评估政策并启动签名）

重要提示： 交易决策签名结构 (TransactionSigningPayload)：发起签名者和每个共同签名者不会直接对原始 32 字节摘要进行签名，而是对序列化的 google.cloud.mpc.v1beta.TransactionSigningPayload protobuf 消息（key = 1 对应 CreateTransaction，transaction = 2 对应 RecordSignerDecision，decision = 3 对应 AUTHORIZE = 1 和 DENY = 2，digest = 4 对应 EC_SIGN_SECP256K1，raw_message = 5 对应 EC_SIGN_ED25519，metadata = 6 [如果已设置]）进行签名。确保 digest 字节与 payload 的哈希值匹配。

以签名者 1 ([e-mail]) 的身份提交交易，以进行政策评估和签名：

Ethereum、KMS

🛑 案例 A：拒绝（价值过高）

尝试创建一笔 3 ETH 的交易（超出 2 ETH 的政策限额）：

sign_tx_decision() {
  local signer_id=$1
  local resource_type=$2
  local resource_name=$3
  local decision=$4
  local digest_hex=$5
  python3 -c 'import sys; rt, rn, dec, dg = sys.argv[1:]; f = lambda k, b: bytes([k << 3 | 2, len(b)]) + b; open("tx_decision_payload.bin", "wb").write(f(1 if rt == "key" else 2, rn.encode()) + bytes([24, 1 if dec == "AUTHORIZE" else 2]) + f(4, bytes.fromhex(dg)))' "${resource_type}" "${resource_name}" "${decision}" "${digest_hex}"
  gcloud kms asymmetric-sign \
    --version=1 \
    --key="${signer_id}-key" \
    --keyring="mpc-assent-keys" \
    --location="us-central1" \
    --digest-algorithm=sha256 \
    --input-file=tx_decision_payload.bin \
    --signature-file=tx_decision_sig.bin > /dev/null
  openssl base64 -A -in tx_decision_sig.bin
}

# Payload for 3 ETH (amount_token_scaled = 3,000,000,000 > 2,000,000,000)
RAW_TX_BYTES_HEX="ef808504a817c8008252089411111111111111111111111111111111111111118829a2241af62c00008083aa36a78080"
PAYLOAD_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$RAW_TX_BYTES_HEX')).decode('utf-8'))")
DIGEST_HEX=$(python3 -c "from eth_utils import keccak; print(keccak(bytes.fromhex('$RAW_TX_BYTES_HEX')).hex())")
DIGEST_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$DIGEST_HEX')).decode('utf-8'))")

SIGNER_1_SIG_B64=$(sign_tx_decision "signer-alice" "key" "${KEY_NAME}" "AUTHORIZE" "${DIGEST_HEX}")
SIGNED_DECISION_PAYLOAD_B64=$(openssl base64 -A -in tx_decision_payload.bin)

curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  -H "Content-Type: application/json" \
  -d "{
    \"transaction\": {
      \"action\": \"Action::\\\"Transfer\\\"\",
      \"schema\": \"ETHEREUM_TX_V2\",
      \"payload\": \"${PAYLOAD_B64}\",
      \"digest\": \"${DIGEST_B64}\"
    },
    \"authorizationInfo\": {
      \"signature\": \"${SIGNER_1_SIG_B64}\",
      \"signedPayload\": \"${SIGNED_DECISION_PAYLOAD_B64}\"
    },
    \"requestId\": \"11111111-1111-4111-8111-111111111601\"
  }" \
  "${INSTANCE_URL}/v1beta/${KEY_NAME}/transactions" | jq

预期政策评估结果：decision: DENY (denyReason: NO_PERMIT_RULE_MATCHED)。

✅ 情况 B：批准（允许的值）

创建一笔 1 Gwei 的交易（在 2 ETH 限额内）：

# Payload for 1 Gwei
RAW_TX_BYTES_HEX="eb808504a817c800825208941111111111111111111111111111111111111111843b9aca008083aa36a78080"
PAYLOAD_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$RAW_TX_BYTES_HEX')).decode('utf-8'))")
export DIGEST_HEX=$(python3 -c "from eth_utils import keccak; print(keccak(bytes.fromhex('$RAW_TX_BYTES_HEX')).hex())")
export DIGEST_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$DIGEST_HEX')).decode('utf-8'))")

SIGNER_1_SIG_B64=$(sign_tx_decision "signer-alice" "key" "${KEY_NAME}" "AUTHORIZE" "${DIGEST_HEX}")
SIGNED_DECISION_PAYLOAD_B64=$(openssl base64 -A -in tx_decision_payload.bin)

RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  -H "Content-Type: application/json" \
  -d "{
    \"transaction\": {
      \"action\": \"Action::\\\"Transfer\\\"\",
      \"schema\": \"ETHEREUM_TX_V2\",
      \"payload\": \"${PAYLOAD_B64}\",
      \"digest\": \"${DIGEST_B64}\"
    },
    \"authorizationInfo\": {
      \"signature\": \"${SIGNER_1_SIG_B64}\",
      \"signedPayload\": \"${SIGNED_DECISION_PAYLOAD_B64}\"
    },
    \"requestId\": \"11111111-1111-4111-8111-111111111602\"
  }" \
  "${INSTANCE_URL}/v1beta/${KEY_NAME}/transactions")

echo "$RESPONSE" | jq
export TRANSACTION_NAME=$(echo "$RESPONSE" | jq -r '.name')

预期响应：state: PENDING_AUTHORIZATION 和 policyEvaluationRecord.decision: PERMIT。

Ethereum、OpenSSL

🛑 案例 A：拒绝（价值过高）

尝试创建一笔 3 ETH 的交易（超出 2 ETH 的政策限额）：

sign_tx_decision() {
  local signer_id=$1
  local resource_type=$2
  local resource_name=$3
  local decision=$4
  local digest_hex=$5
  python3 -c 'import sys; rt, rn, dec, dg = sys.argv[1:]; f = lambda k, b: bytes([k << 3 | 2, len(b)]) + b; open("tx_decision_payload.bin", "wb").write(f(1 if rt == "key" else 2, rn.encode()) + bytes([24, 1 if dec == "AUTHORIZE" else 2]) + f(4, bytes.fromhex(dg)))' "${resource_type}" "${resource_name}" "${decision}" "${digest_hex}"
  openssl dgst -sha256 -sign "${signer_id}_priv.pem" -out tx_decision_sig.bin tx_decision_payload.bin
  openssl base64 -A -in tx_decision_sig.bin
}

# Payload for 3 ETH (amount_token_scaled = 3,000,000,000 > 2,000,000,000)
RAW_TX_BYTES_HEX="ef808504a817c8008252089411111111111111111111111111111111111111118829a2241af62c00008083aa36a78080"
PAYLOAD_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$RAW_TX_BYTES_HEX')).decode('utf-8'))")
DIGEST_HEX=$(python3 -c "from eth_utils import keccak; print(keccak(bytes.fromhex('$RAW_TX_BYTES_HEX')).hex())")
DIGEST_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$DIGEST_HEX')).decode('utf-8'))")

SIGNER_1_SIG_B64=$(sign_tx_decision "signer-alice" "key" "${KEY_NAME}" "AUTHORIZE" "${DIGEST_HEX}")
SIGNED_DECISION_PAYLOAD_B64=$(openssl base64 -A -in tx_decision_payload.bin)

curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  -H "Content-Type: application/json" \
  -d "{
    \"transaction\": {
      \"action\": \"Action::\\\"Transfer\\\"\",
      \"schema\": \"ETHEREUM_TX_V2\",
      \"payload\": \"${PAYLOAD_B64}\",
      \"digest\": \"${DIGEST_B64}\"
    },
    \"authorizationInfo\": {
      \"signature\": \"${SIGNER_1_SIG_B64}\",
      \"signedPayload\": \"${SIGNED_DECISION_PAYLOAD_B64}\"
    },
    \"requestId\": \"11111111-1111-4111-8111-111111111601\"
  }" \
  "${INSTANCE_URL}/v1beta/${KEY_NAME}/transactions" | jq

预期政策评估结果：decision: DENY (denyReason: NO_PERMIT_RULE_MATCHED)。

✅ 情况 B：批准（允许的值）

创建一笔 1 Gwei 的交易（在 2 ETH 限额内）：

# Payload for 1 Gwei
RAW_TX_BYTES_HEX="eb808504a817c800825208941111111111111111111111111111111111111111843b9aca008083aa36a78080"
PAYLOAD_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$RAW_TX_BYTES_HEX')).decode('utf-8'))")
export DIGEST_HEX=$(python3 -c "from eth_utils import keccak; print(keccak(bytes.fromhex('$RAW_TX_BYTES_HEX')).hex())")
export DIGEST_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$DIGEST_HEX')).decode('utf-8'))")

SIGNER_1_SIG_B64=$(sign_tx_decision "signer-alice" "key" "${KEY_NAME}" "AUTHORIZE" "${DIGEST_HEX}")
SIGNED_DECISION_PAYLOAD_B64=$(openssl base64 -A -in tx_decision_payload.bin)

RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  -H "Content-Type: application/json" \
  -d "{
    \"transaction\": {
      \"action\": \"Action::\\\"Transfer\\\"\",
      \"schema\": \"ETHEREUM_TX_V2\",
      \"payload\": \"${PAYLOAD_B64}\",
      \"digest\": \"${DIGEST_B64}\"
    },
    \"authorizationInfo\": {
      \"signature\": \"${SIGNER_1_SIG_B64}\",
      \"signedPayload\": \"${SIGNED_DECISION_PAYLOAD_B64}\"
    },
    \"requestId\": \"11111111-1111-4111-8111-111111111602\"
  }" \
  "${INSTANCE_URL}/v1beta/${KEY_NAME}/transactions")

echo "$RESPONSE" | jq
export TRANSACTION_NAME=$(echo "$RESPONSE" | jq -r '.name')

预期响应：state: PENDING_AUTHORIZATION 和 policyEvaluationRecord.decision: PERMIT。

比特币、KMS

在比特币 UTXO 模型中，交易会花费特定的未花费输出。在 SegWit (BIP 143) 中，计算签名哈希需要知道所花费输入的聪金额和锁定脚本。

比特币政策评估需要 BIP 174 PSBT v0 格式 (BITCOIN_TX_V2)，并为每个输入填充 PSBT_IN_WITNESS_UTXO。

重要提示： 找零输出和聪记账：在比特币中，任何未分配的差额 (InputSatoshis - RecipientSatoshis - MinerFeeSatoshis) 都会被矿工认领。为防止资金损失，交易必须明确分配一个找零输出，将未花费的余额返还给发送者自己的派生原生隔离见证地址。

PSBT 构建脚本 (build_psbt.py)

执行以下代码块，组装有效的 BIP 174 PSBT v0 载荷：

cat <<'EOF' > build_psbt.py
"""Constructs a BIP 174 PSBT v0 payload using embit for Bitcoin policy evaluation."""

from embit import script, transaction
from embit.psbt import PSBT

# 1. Inputs (From Step 5.C)
PREV_TXID_HEX = "8f594f33156993f1c980c2273dcae4a92cf2517fbc29264421395e63a63916d8"
PREV_VOUT = int("1")
INPUT_VALUE_SATS = int("200000")  # Total UTXO input value in satoshis
SENDER_SCRIPTPUBKEY_HEX = "0014eced05cd51d964102a20c856b09080ad620e9da2"

# 2. Output Allocations
RECIPIENT_SATS = int("50000")  # Recipient payment in satoshis
MINER_FEE_SATS = int("250")  # Miner fee in satoshis
RECIPIENT_SCRIPTPUBKEY_HEX = "0014751e76e8199196d454941c45d1b3a323f1433bd6"

# Change Output calculation: InputSats - RecipientSats - MinerFeeSats
CHANGE_SATS = INPUT_VALUE_SATS - RECIPIENT_SATS - MINER_FEE_SATS
if CHANGE_SATS <= 0:
  raise ValueError(f"Insufficient input satoshis ({INPUT_VALUE_SATS}) for payment and fee")

# 3. Construct Unsigned Transaction (Version 2, 1 input, 2 outputs, locktime 0)
tx = transaction.Transaction(
    version=2,
    vin=[transaction.TransactionInput(
        txid=bytes.fromhex(PREV_TXID_HEX),
        vout=PREV_VOUT,
        sequence=0xFFFFFFFF,
    )],
    vout=[
        transaction.TransactionOutput(
            value=RECIPIENT_SATS,
            script_pubkey=script.Script(bytes.fromhex(RECIPIENT_SCRIPTPUBKEY_HEX)),
        ),
        transaction.TransactionOutput(
            value=CHANGE_SATS,
            script_pubkey=script.Script(bytes.fromhex(SENDER_SCRIPTPUBKEY_HEX)),
        ),
    ],
    locktime=0,
)

# 4. Package into BIP 174 PSBT with Input Witness UTXO
psbt = PSBT(tx)
psbt.inputs[0].witness_utxo = transaction.TransactionOutput(
    value=INPUT_VALUE_SATS,
    script_pubkey=script.Script(bytes.fromhex(SENDER_SCRIPTPUBKEY_HEX)),
)

print(psbt.serialize().hex())
EOF

BTC_PSBT_HEX=$(python3 build_psbt.py)
echo "Generated PSBT Hex (${#BTC_PSBT_HEX} chars):"
echo "$BTC_PSBT_HEX"

🛑 Case A: Rejection (Fee Limit Exceeded)

尝试创建一笔矿工费超过 10,000 聪政策限额的交易。在此示例中，在 build_psbt.py 中设置 MINER_FEE_SATS = 15000（和 CHANGE_SATS = 135000）会扩缩到 max_fee_atomic = 150000（超出政策上限 100000），从而生成以下载荷，触发 DENY 政策评估决策。

sign_tx_decision() {
  local signer_id=$1
  local resource_type=$2
  local resource_name=$3
  local decision=$4
  local digest_hex=$5
  python3 -c 'import sys; rt, rn, dec, dg = sys.argv[1:]; f = lambda k, b: bytes([k << 3 | 2, len(b)]) + b; open("tx_decision_payload.bin", "wb").write(f(1 if rt == "key" else 2, rn.encode()) + bytes([24, 1 if dec == "AUTHORIZE" else 2]) + f(4, bytes.fromhex(dg)))' "${resource_type}" "${resource_name}" "${decision}" "${digest_hex}"
  gcloud kms asymmetric-sign \
    --version=1 \
    --key="${signer_id}-key" \
    --keyring="mpc-assent-keys" \
    --location="us-central1" \
    --digest-algorithm=sha256 \
    --input-file=tx_decision_payload.bin \
    --signature-file=tx_decision_sig.bin > /dev/null
  openssl base64 -A -in tx_decision_sig.bin
}

# Construct a PSBT payload with miner_fee_sats = 15000 -> max_fee_atomic = 150000 (exceeds 100000 limit)
REJECTED_PSBT_HEX="70736274ff0100710200000001d81639a6635e3921442629bc7f51f22ca9e4ca3d27c280c9f1936915334f598f0100000000ffffffff0250c3000000000000160014751e76e8199196d454941c45d1b3a323f1433bd6580f020000000000160014eced05cd51d964102a20c856b09080ad620e9da2000000000001011f400d030000000000160014eced05cd51d964102a20c856b09080ad620e9da2000000"
REJECTED_PAYLOAD_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$REJECTED_PSBT_HEX')).decode('utf-8'))")
REJECTED_DIGEST_HEX=$(python3 -c "from embit import script; from embit.psbt import PSBT; p=PSBT.parse(bytes.fromhex('$REJECTED_PSBT_HEX')); u=p.inputs[0].witness_utxo; sc=script.Script(b'\x76\xa9\x14'+u.script_pubkey.data[2:]+b'\x88\xac'); print(p.tx.sighash_segwit(0, sc, u.value).hex())")
REJECTED_DIGEST_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$REJECTED_DIGEST_HEX')).decode('utf-8'))")

SIGNER_1_SIG_B64=$(sign_tx_decision "signer-alice" "key" "${KEY_NAME}" "AUTHORIZE" "${REJECTED_DIGEST_HEX}")
SIGNED_DECISION_PAYLOAD_B64=$(openssl base64 -A -in tx_decision_payload.bin)

curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  -H "Content-Type: application/json" \
  -d "{
    \"transaction\": {
      \"action\": \"Action::\\\"Transfer\\\"\",
      \"schema\": \"BITCOIN_TX_V2\",
      \"payload\": \"${REJECTED_PAYLOAD_B64}\",
      \"digest\": \"${REJECTED_DIGEST_B64}\"
    },
    \"authorizationInfo\": {
      \"signature\": \"${SIGNER_1_SIG_B64}\",
      \"signedPayload\": \"${SIGNED_DECISION_PAYLOAD_B64}\"
    },
    \"requestId\": \"11111111-1111-4111-8111-111111111603\"
  }" \
  "${INSTANCE_URL}/v1beta/${KEY_NAME}/transactions" | jq

预期政策评估结果：decision: DENY (denyReason: NO_PERMIT_RULE_MATCHED)。

✅ 情况 B：批准（允许的比特币 PSBT）

使用之前构建的有效 PSBT 创建交易（RECIPIENT_SATS = 50000 映射到 amount_token_scaled = 500000 <= 2500000，MINER_FEE_SATS = 250 映射到 max_fee_atomic = 2500 <= 100000）：

PAYLOAD_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$BTC_PSBT_HEX')).decode('utf-8'))")
export DIGEST_HEX=$(python3 -c "from embit import script; from embit.psbt import PSBT; p=PSBT.parse(bytes.fromhex('$BTC_PSBT_HEX')); u=p.inputs[0].witness_utxo; sc=script.Script(b'\x76\xa9\x14'+u.script_pubkey.data[2:]+b'\x88\xac'); print(p.tx.sighash_segwit(0, sc, u.value).hex())")
export DIGEST_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$DIGEST_HEX')).decode('utf-8'))")

SIGNER_1_SIG_B64=$(sign_tx_decision "signer-alice" "key" "${KEY_NAME}" "AUTHORIZE" "${DIGEST_HEX}")
SIGNED_DECISION_PAYLOAD_B64=$(openssl base64 -A -in tx_decision_payload.bin)

RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  -H "Content-Type: application/json" \
  -d "{
    \"transaction\": {
      \"action\": \"Action::\\\"Transfer\\\"\",
      \"schema\": \"BITCOIN_TX_V2\",
      \"payload\": \"${PAYLOAD_B64}\",
      \"digest\": \"${DIGEST_B64}\"
    },
    \"authorizationInfo\": {
      \"signature\": \"${SIGNER_1_SIG_B64}\",
      \"signedPayload\": \"${SIGNED_DECISION_PAYLOAD_B64}\"
    },
    \"requestId\": \"11111111-1111-4111-8111-111111111604\"
  }" \
  "${INSTANCE_URL}/v1beta/${KEY_NAME}/transactions")

echo "$RESPONSE" | jq
export TRANSACTION_NAME=$(echo "$RESPONSE" | jq -r '.name')

预期响应：state: PENDING_AUTHORIZATION 和 policyEvaluationRecord.decision: PERMIT。

Bitcoin、OpenSSL

在比特币 UTXO 模型中，交易会花费特定的未花费输出。在 SegWit (BIP 143) 中，计算签名哈希需要知道所花费输入的聪金额和锁定脚本。

比特币政策评估需要 BIP 174 PSBT v0 格式 (BITCOIN_TX_V2)，并为每个输入填充 PSBT_IN_WITNESS_UTXO。

重要提示： 找零输出和聪记账：在比特币中，任何未分配的差额 (InputSatoshis - RecipientSatoshis - MinerFeeSatoshis) 都会被矿工认领。为防止资金损失，交易必须明确分配一个找零输出，将未花费的余额返还给发送者自己的派生原生隔离见证地址。

PSBT 构建脚本 (build_psbt.py)

执行以下代码块，组装有效的 BIP 174 PSBT v0 载荷：

cat <<'EOF' > build_psbt.py
"""Constructs a BIP 174 PSBT v0 payload using embit for Bitcoin policy evaluation."""

from embit import script, transaction
from embit.psbt import PSBT

# 1. Inputs (From Step 5.C)
PREV_TXID_HEX = "8f594f33156993f1c980c2273dcae4a92cf2517fbc29264421395e63a63916d8"
PREV_VOUT = int("1")
INPUT_VALUE_SATS = int("200000")  # Total UTXO input value in satoshis
SENDER_SCRIPTPUBKEY_HEX = "0014eced05cd51d964102a20c856b09080ad620e9da2"

# 2. Output Allocations
RECIPIENT_SATS = int("50000")  # Recipient payment in satoshis
MINER_FEE_SATS = int("250")  # Miner fee in satoshis
RECIPIENT_SCRIPTPUBKEY_HEX = "0014751e76e8199196d454941c45d1b3a323f1433bd6"

# Change Output calculation: InputSats - RecipientSats - MinerFeeSats
CHANGE_SATS = INPUT_VALUE_SATS - RECIPIENT_SATS - MINER_FEE_SATS
if CHANGE_SATS <= 0:
  raise ValueError(f"Insufficient input satoshis ({INPUT_VALUE_SATS}) for payment and fee")

# 3. Construct Unsigned Transaction (Version 2, 1 input, 2 outputs, locktime 0)
tx = transaction.Transaction(
    version=2,
    vin=[transaction.TransactionInput(
        txid=bytes.fromhex(PREV_TXID_HEX),
        vout=PREV_VOUT,
        sequence=0xFFFFFFFF,
    )],
    vout=[
        transaction.TransactionOutput(
            value=RECIPIENT_SATS,
            script_pubkey=script.Script(bytes.fromhex(RECIPIENT_SCRIPTPUBKEY_HEX)),
        ),
        transaction.TransactionOutput(
            value=CHANGE_SATS,
            script_pubkey=script.Script(bytes.fromhex(SENDER_SCRIPTPUBKEY_HEX)),
        ),
    ],
    locktime=0,
)

# 4. Package into BIP 174 PSBT with Input Witness UTXO
psbt = PSBT(tx)
psbt.inputs[0].witness_utxo = transaction.TransactionOutput(
    value=INPUT_VALUE_SATS,
    script_pubkey=script.Script(bytes.fromhex(SENDER_SCRIPTPUBKEY_HEX)),
)

print(psbt.serialize().hex())
EOF

BTC_PSBT_HEX=$(python3 build_psbt.py)
echo "Generated PSBT Hex (${#BTC_PSBT_HEX} chars):"
echo "$BTC_PSBT_HEX"

🛑 Case A: Rejection (Fee Limit Exceeded)

尝试创建一笔矿工费超过 10,000 聪政策限额的交易。在此示例中，在 build_psbt.py 中设置 MINER_FEE_SATS = 15000（和 CHANGE_SATS = 135000）会扩缩到 max_fee_atomic = 150000（超出政策上限 100000），从而生成以下载荷，触发 DENY 政策评估决策。

sign_tx_decision() {
  local signer_id=$1
  local resource_type=$2
  local resource_name=$3
  local decision=$4
  local digest_hex=$5
  python3 -c 'import sys; rt, rn, dec, dg = sys.argv[1:]; f = lambda k, b: bytes([k << 3 | 2, len(b)]) + b; open("tx_decision_payload.bin", "wb").write(f(1 if rt == "key" else 2, rn.encode()) + bytes([24, 1 if dec == "AUTHORIZE" else 2]) + f(4, bytes.fromhex(dg)))' "${resource_type}" "${resource_name}" "${decision}" "${digest_hex}"
  openssl dgst -sha256 -sign "${signer_id}_priv.pem" -out tx_decision_sig.bin tx_decision_payload.bin
  openssl base64 -A -in tx_decision_sig.bin
}

# Construct a PSBT payload with miner_fee_sats = 15000 -> max_fee_atomic = 150000 (exceeds 100000 limit)
REJECTED_PSBT_HEX="70736274ff0100710200000001d81639a6635e3921442629bc7f51f22ca9e4ca3d27c280c9f1936915334f598f0100000000ffffffff0250c3000000000000160014751e76e8199196d454941c45d1b3a323f1433bd6580f020000000000160014eced05cd51d964102a20c856b09080ad620e9da2000000000001011f400d030000000000160014eced05cd51d964102a20c856b09080ad620e9da2000000"
REJECTED_PAYLOAD_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$REJECTED_PSBT_HEX')).decode('utf-8'))")
REJECTED_DIGEST_HEX=$(python3 -c "from embit import script; from embit.psbt import PSBT; p=PSBT.parse(bytes.fromhex('$REJECTED_PSBT_HEX')); u=p.inputs[0].witness_utxo; sc=script.Script(b'\x76\xa9\x14'+u.script_pubkey.data[2:]+b'\x88\xac'); print(p.tx.sighash_segwit(0, sc, u.value).hex())")
REJECTED_DIGEST_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$REJECTED_DIGEST_HEX')).decode('utf-8'))")

SIGNER_1_SIG_B64=$(sign_tx_decision "signer-alice" "key" "${KEY_NAME}" "AUTHORIZE" "${REJECTED_DIGEST_HEX}")
SIGNED_DECISION_PAYLOAD_B64=$(openssl base64 -A -in tx_decision_payload.bin)

curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  -H "Content-Type: application/json" \
  -d "{
    \"transaction\": {
      \"action\": \"Action::\\\"Transfer\\\"\",
      \"schema\": \"BITCOIN_TX_V2\",
      \"payload\": \"${REJECTED_PAYLOAD_B64}\",
      \"digest\": \"${REJECTED_DIGEST_B64}\"
    },
    \"authorizationInfo\": {
      \"signature\": \"${SIGNER_1_SIG_B64}\",
      \"signedPayload\": \"${SIGNED_DECISION_PAYLOAD_B64}\"
    },
    \"requestId\": \"11111111-1111-4111-8111-111111111603\"
  }" \
  "${INSTANCE_URL}/v1beta/${KEY_NAME}/transactions" | jq

预期政策评估结果：decision: DENY (denyReason: NO_PERMIT_RULE_MATCHED)。

✅ 情况 B：批准（允许的比特币 PSBT）

使用之前构建的有效 PSBT 创建交易（RECIPIENT_SATS = 50000 映射到 amount_token_scaled = 500000 <= 2500000，MINER_FEE_SATS = 250 映射到 max_fee_atomic = 2500 <= 100000）：

PAYLOAD_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$BTC_PSBT_HEX')).decode('utf-8'))")
export DIGEST_HEX=$(python3 -c "from embit import script; from embit.psbt import PSBT; p=PSBT.parse(bytes.fromhex('$BTC_PSBT_HEX')); u=p.inputs[0].witness_utxo; sc=script.Script(b'\x76\xa9\x14'+u.script_pubkey.data[2:]+b'\x88\xac'); print(p.tx.sighash_segwit(0, sc, u.value).hex())")
export DIGEST_B64=$(python3 -c "import base64; print(base64.b64encode(bytes.fromhex('$DIGEST_HEX')).decode('utf-8'))")

SIGNER_1_SIG_B64=$(sign_tx_decision "signer-alice" "key" "${KEY_NAME}" "AUTHORIZE" "${DIGEST_HEX}")
SIGNED_DECISION_PAYLOAD_B64=$(openssl base64 -A -in tx_decision_payload.bin)

RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  -H "Content-Type: application/json" \
  -d "{
    \"transaction\": {
      \"action\": \"Action::\\\"Transfer\\\"\",
      \"schema\": \"BITCOIN_TX_V2\",
      \"payload\": \"${PAYLOAD_B64}\",
      \"digest\": \"${DIGEST_B64}\"
    },
    \"authorizationInfo\": {
      \"signature\": \"${SIGNER_1_SIG_B64}\",
      \"signedPayload\": \"${SIGNED_DECISION_PAYLOAD_B64}\"
    },
    \"requestId\": \"11111111-1111-4111-8111-111111111604\"
  }" \
  "${INSTANCE_URL}/v1beta/${KEY_NAME}/transactions")

echo "$RESPONSE" | jq
export TRANSACTION_NAME=$(echo "$RESPONSE" | jq -r '.name')

预期响应：state: PENDING_AUTHORIZATION 和 policyEvaluationRecord.decision: PERMIT。

🕵️‍♂️ 检查交易状态（轮询）

定期运行以下命令，轮询事务状态：

curl

curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${TRANSACTION_NAME}" | jq

B. 记录签署者决定（授权）

由于第 6.A 步中的 CreateTransaction 已记录签名者 1 的 AUTHORIZE 决定（3 选 2 KeyPolicy 阈值所需的 2 个签名中的 1 个），因此只需另外一个持有密钥共享的共同签名者使用 transactions.recordSignerDecision (RecordSignerDecision) 授权交易即可。

注意： 步骤 6.B 和 6.C 在以太坊和比特币上的操作方式相同，因为 MPC 阈值密钥会对根据 payload 验证的 32 字节 digest 进行签名。

签署 TransactionSigningPayload，将 transaction (${TRANSACTION_NAME}) 和 recordSignerDecision 指定为签署者 2 ([e-mail])：

curl

# 1. Check state for Signer 2
TX_INFO=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${TRANSACTION_NAME}")

TX_STATE=$(echo "$TX_INFO" | jq -r '.state // "UNKNOWN"')

if [ "$TX_STATE" == "PENDING_AUTHORIZATION" ]; then
  # 2. Sign as Signer 2 naming transaction ($TRANSACTION_NAME)
  SIGNER_2_SIG_B64=$(sign_tx_decision "signer-bob" "transaction" "${TRANSACTION_NAME}" "AUTHORIZE" "${DIGEST_HEX}")
  SIGNER_2_PAYLOAD_B64=$(openssl base64 -A -in tx_decision_payload.bin)

  # 3. Call RecordSignerDecision as Signer 2
  echo "Recording AUTHORIZE decision for Signer 2..."
  curl -s -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
    -H "X-Goog-User-Project: my-project" \
    -H "Content-Type: application/json" \
    -d "{
      \"decision\": \"AUTHORIZE\",
      \"authorizationInfo\": {
        \"signature\": \"${SIGNER_2_SIG_B64}\",
        \"signedPayload\": \"${SIGNER_2_PAYLOAD_B64}\"
      }
    }" \
    "${INSTANCE_URL}/v1beta/${TRANSACTION_NAME}:recordSignerDecision" | jq
elif [ "$TX_STATE" == "SIGNING" ] || [ "$TX_STATE" == "SIGNING_SUCCEEDED" ]; then
  echo "Transaction is in state $TX_STATE. Skipping Signer 2."
else
  echo "Transaction is in an unexpected state: $TX_STATE"
fi

C. 提取最终签名

达到授权阈值后，检查交易状态并提取 finalSignature（对于 EC_SIGN_SECP256K1 密钥，还需提取 recoveryId）：

curl

curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${TRANSACTION_NAME}" | jq

当 state 为 SIGNING_SUCCEEDED 时，从返回的 JSON 中复制 finalSignature 字段，以便在第 7 步中使用。

---

第 7 步：将交易广播到区块链

当交易达到 SIGNING_SUCCEEDED 状态并且您已提取 finalSignature 后，最后一步是构建已签名的网络交易并将其广播到网络。

以太坊

恢复标识符派生和广播

MPC API 会在 finalSignature 中返回一个原始 64 字节 ECDSA 签名（包含规范低 S 形式的 32 字节 r 和 s 值，符合 EIP-2 标准），并在 recoveryId 中返回恢复奇偶校验位（0 或 1）。

以下 Python 脚本使用您的 finalSignature 构建已签名的交易，根据 MPC 密钥的以太坊地址验证恢复的发件人地址，并将其广播到网络。

广播脚本：

在终端中执行以下可复制粘贴的代码块，以编写并运行 broadcast_eth.py：

cat <<'EOF' > broadcast_eth.py
"""Broadcasts an Ethereum transaction using a normalized MPC signature."""

import base64
import os
import requests
from eth_account import Account
try:
    from eth_account._utils.transactions import encode_transaction, serializable_unsigned_transaction_from_dict
except ImportError:
    from eth_account._utils.legacy_transactions import encode_transaction, serializable_unsigned_transaction_from_dict

# ==========================================
# 1. INPUTS
# ==========================================
FINAL_SIGNATURE_B64 = "your-final-signature"
RPC_URL = "https://ethereum-sepolia-rpc.publicnode.com"
EXPECTED_SENDER = "0xyour-mpc-key-address"

if not FINAL_SIGNATURE_B64 or FINAL_SIGNATURE_B64 == "your-final-signature":
    raise ValueError("FINAL_SIGNATURE_B64 is not set. Please provide a valid signature.")

# ==========================================
# 2. TRANSACTION PARAMETERS
# ==========================================
CHAIN_ID = 11155111  # Sepolia Testnet
tx_dict = {
    "nonce": int("0"),
    "gasPrice": int("20000000000"),  # 20 Gwei
    "gas": int("21000"),
    "to": "0x1111111111111111111111111111111111111111",
    "value": int("1000000000"),  # 1 Gwei
    "data": b"",
    "chainId": CHAIN_ID,
}

# ==========================================
# 3. DECODE & SPLIT SIGNATURE
# ==========================================
missing_padding = len(FINAL_SIGNATURE_B64) % 4
if missing_padding:
    FINAL_SIGNATURE_B64 += "=" * (4 - missing_padding)

sig_bytes = base64.b64decode(FINAL_SIGNATURE_B64)
r = int.from_bytes(sig_bytes[:32], byteorder="big")
s = int.from_bytes(sig_bytes[32:], byteorder="big")

# ==========================================
# 4. RECOVERY IDENTIFIER (V) DERIVATION
# ==========================================
chain_v_base = (CHAIN_ID * 2) + 35

# ==========================================
# 5. GENERATE UNSIGNED TX & RECOVER SENDER ADDRESS
# ==========================================
unsigned_tx = serializable_unsigned_transaction_from_dict(tx_dict)

derived_sender = None
encoded_tx = None
final_v = chain_v_base

EXPECTED_SENDER_PLACEHOLDER = "0xyour-mpc-key-address"
is_valid_expected = EXPECTED_SENDER and EXPECTED_SENDER != EXPECTED_SENDER_PLACEHOLDER

for parity in [0, 1]:
    try_v = chain_v_base + parity
    try:
        tx_candidate = encode_transaction(unsigned_tx, vrs=(try_v, r, s))
        addr = Account.recover_transaction("0x" + tx_candidate.hex())

        if is_valid_expected and EXPECTED_SENDER.lower() == addr.lower():
            derived_sender = addr
            final_v = try_v
            encoded_tx = tx_candidate
            break

        if not is_valid_expected and derived_sender is None:
            derived_sender = addr
            final_v = try_v
            encoded_tx = tx_candidate
            print(f"Warning: EXPECTED_SENDER not provided or is placeholder. Assuming first recovered address: {addr}")

    except Exception:
        continue

if encoded_tx is None:
    if is_valid_expected:
        raise ValueError(f"Could not recover address matching EXPECTED_SENDER: {EXPECTED_SENDER}")
    else:
        raise ValueError("Could not derive broadcastable transaction. Ensure signature matches payload.")

if derived_sender:
    print(f"Derived Sender Address: {derived_sender}")
else:
    print("Derived Sender Address: Could not recover (ensure signature matches current transaction payload)")

valid_tx_hex = "0x" + encoded_tx.hex()
print(f"Broadcastable Transaction Hex:\n{valid_tx_hex}\n")

# ==========================================
# 6. BROADCAST TO NETWORK
# ==========================================
payload = {
    "jsonrpc": "2.0",
    "method": "eth_sendRawTransaction",
    "params": [valid_tx_hex],
    "id": 1,
}

print(f"Broadcasting to {RPC_URL}...")
response = requests.post(RPC_URL, json=payload)
resp_json = response.json()
print("RPC Response:", resp_json)
if "result" in resp_json:
    tx_hash = resp_json["result"]
    print(f"View transaction on Sepolia Etherscan: https://sepolia.etherscan.io/tx/{tx_hash}")
EOF

python3 broadcast_eth.py

问题排查常见错误

• invalid sender: recovery failed 或 invalid transaction v, r, s values：如果脚本中的交易参数与已签名的载荷不完全匹配，就会发生这种情况。确保 value、nonce 和 to 字段与第 6 步中处理的内容一致。
• insufficient funds for gas * price + value：您的交易在加密方面有效，并且已被节点接受，但您的 MPC 密钥的以太坊地址没有足够的测试网 ETH 来支付操作费用。您需要先为地址充值，然后才能广播。

比特币

SegWit 线路交易组装和广播

对于比特币原生隔离见证交易 (BIP 141)，必须将原始 64 字节 (r, s) MPC 签名格式化为规范的低 S ASN.1 DER，附加 0x01 (SIGHASH_ALL)，并与 33 字节压缩公钥一起组装到 2 元素隔离见证堆栈中：[DER signature || 0x01, compressed public key]。

广播脚本：

执行以下代码块，以创建并运行 broadcast_btc.py：

cat <<'EOF' > broadcast_btc.py
"""Assembles a signed Bitcoin Native SegWit transaction from an MPC signature using embit and broadcasts it."""

import base64
import urllib.request
from embit import ec, script, transaction

# ==========================================
# 1. INPUTS
# ==========================================
FINAL_SIGNATURE_B64 = "your-final-signature"
COMPRESSED_PUBKEY_HEX = "03deb76948c14003446a8c1d79e88fb3607c9bbc1f5143b186aa7b61d6b1facc36"

PREV_TXID_HEX = "8f594f33156993f1c980c2273dcae4a92cf2517fbc29264421395e63a63916d8"
PREV_VOUT = int("1")

RECIPIENT_SATS = int("50000")
RECIPIENT_SCRIPTPUBKEY_HEX = "0014751e76e8199196d454941c45d1b3a323f1433bd6"

CHANGE_SATS = int("149750")
CHANGE_SCRIPTPUBKEY_HEX = "0014eced05cd51d964102a20c856b09080ad620e9da2"

BROADCAST_API_URL = "https://mempool.space/testnet4/api/tx"

# ==========================================
# 2. CONVERT RAW (r, s) SIGNATURE TO CANONICAL LOW-S ASN.1 DER + SIGHASH_ALL
# ==========================================
sig_bytes = base64.b64decode(FINAL_SIGNATURE_B64)
internal_sig = ec.secp256k1.ecdsa_signature_parse_compact(sig_bytes)
ec.secp256k1.ecdsa_signature_normalize(internal_sig, internal_sig)
der_sig = ec.secp256k1.ecdsa_signature_serialize_der(internal_sig) + b"\x01"  # 0x01 = SIGHASH_ALL

# ==========================================
# 3. BUILD TRANSACTION & ATTACH SEGWIT WITNESS STACK
# ==========================================
tx = transaction.Transaction(
    version=2,
    vin=[transaction.TransactionInput(
        txid=bytes.fromhex(PREV_TXID_HEX),
        vout=PREV_VOUT,
        sequence=0xFFFFFFFF,
    )],
    vout=[
        transaction.TransactionOutput(
            value=RECIPIENT_SATS,
            script_pubkey=script.Script(bytes.fromhex(RECIPIENT_SCRIPTPUBKEY_HEX)),
        ),
        transaction.TransactionOutput(
            value=CHANGE_SATS,
            script_pubkey=script.Script(bytes.fromhex(CHANGE_SCRIPTPUBKEY_HEX)),
        ),
    ],
    locktime=0,
)

pubkey_bytes = bytes.fromhex(COMPRESSED_PUBKEY_HEX)
tx.vin[0].witness = transaction.Witness([der_sig, pubkey_bytes])

signed_tx_hex = tx.serialize().hex()
print("--- Signed Bitcoin SegWit Wire Transaction Hex ---")
print(signed_tx_hex)

# ==========================================
# 4. BROADCAST TO NETWORK
# ==========================================
if BROADCAST_API_URL:
  print(f"\nBroadcasting to {BROADCAST_API_URL}...")
  try:
    req = urllib.request.Request(
        BROADCAST_API_URL,
        data=signed_tx_hex.encode("utf-8"),
        headers={"Content-Type": "text/plain"},
        method="POST",
    )
    with urllib.request.urlopen(req) as resp:
      txid_result = resp.read().decode("utf-8").strip()
      print(f"✅ Broadcast Successful! Transaction ID (txid): {txid_result}")
      print(f"Track in Mempool Explorer: https://mempool.space/testnet4/tx/{txid_result}")
  except Exception as e:
    print(f"Broadcast response: {e}")
EOF

python3 broadcast_btc.py

问题排查常见错误

• mandatory-script-verify-flag-failed (Signature must be zero for failed CHECK(MULTI)SIG operation) / non-mandatory-script-verify-flag (Non-canonical DER signature)：确保签名的 s 组件采用规范的 low-s 形式 (s <= N/2)，并经过正确的 DER 编码。
• bad-txns-in-belowout / bad-txns-fee-negative：总输出超过输入值。确保您的变化量计算结果 (InputSatoshis - PaymentSatoshis - MinerFee) 严格为正数。

📖 附录：运维实战宝典（查询和检查）

您可以使用这些命令随时检查和管理资源的状态。

---

🏢 1. 实例

检查和管理项目和位置中的 MPC 实例。

A. 列出所有实例

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "https://mpc.googleapis.com/v1beta/projects/my-project/locations/us-central1/instances" | jq

B. 获取特定实例的详细信息

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "https://mpc.googleapis.com/v1beta/${INSTANCE_NAME}" | jq

---

👥 2. 团队和用户

检查实例中的团队和用户。

A. 列出所有团队

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/teams" | jq

B. 获取特定团队的详细信息

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${TEAM_NAME}" | jq

C. 列出所有注册用户

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/users" | jq

D. 获取特定用户的详细信息

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${SIGNER_1_NAME}" | jq

---

📜 3. 事务政策和 KeyList

检查交易政策和密钥列表。

A. 列出所有事务政策

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/transactionPolicies" | jq

B. 获取特定交易政策的详细信息

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${POLICY_NAME}" | jq

C. 列出和获取 KeyList

curl

# List all KeyLists
curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/keyLists" | jq

# Get a specific KeyList
curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${KEY_LIST_NAME}" | jq

---

🔑 4. 密钥和密钥环

检查密钥环和分布式密钥。

A. 列出所有 KeyRing

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/keyRings" | jq

B. 列出密钥环中的所有密钥

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${KEY_RING_NAME}/keys" | jq

C. 获取特定分布式密钥的详细信息

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${KEY_NAME}" | jq

---

📝 5. 交易（签名操作）

检查交易和签名状态。

A. 列出某个密钥（或所有密钥）的所有交易

curl

# List transactions for a specific Key
curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${KEY_NAME}/transactions" | jq

# List transactions across all KeyRings and Keys using the '-' wildcard
curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${INSTANCE_NAME}/keyRings/-/keys/-/transactions" | jq

B. 获取特定交易的详细信息或状态

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token "[e-mail]")" \
  -H "X-Goog-User-Project: my-project" \
  "${INSTANCE_URL}/v1beta/${TRANSACTION_NAME}" | jq