cardanoSignTransaction

使用要求

固件版本要求
- UKey Lite 24 / UKey Lite 25: 1.1.0
- UKey Core 26: 1.1.0

Cardano：签名交易

使用指定 BIP32 路径派生的私钥对交易进行签名。签名前，用户需要在 Ukey Wallet 上核对交易目标、金额和费用等关键信息。

const response = await HardwareSDK.cardanoSignTransaction(
  connectId,
  deviceId,
  params,
);

参数

可选通用参数

CardanoSignTransaction 类型

signingMode - 必需 CardanoTxSigningMode，交易签名模式。
inputs - 必需 Array，CardanoInput 数组。
outputs - 必需 Array，CardanoOutput 数组。
fee - 必需 String，交易手续费。
protocolMagic - 必需 Integer，主网为 764824073，Preprod 测试网为 1，Preview 测试网为 2。
networkId - 必需 Integer，主网为 1，测试网为 0。
ttl - 可选 String，交易有效期。
validityIntervalStart - 可选 String，交易有效起始区间。
certificates - 可选 Array，CardanoCertificate 数组。
withdrawals - 可选 Array，CardanoWithdrawal 数组。
auxiliaryData - 可选 CardanoAuxiliaryData，辅助数据。
mint - 可选 CardanoMint，代币铸造信息。
scriptDataHash - 可选 String，脚本数据哈希。
collateralInputs - 可选 Array，CardanoCollateralInput 数组。
requiredSigners - 可选 Array，CardanoRequiredSigner 数组。
collateralReturn - 可选 CardanoOutput，抵押返还输出。
totalCollateral - 可选 String，总抵押金额。
referenceInputs - 可选 Array，CardanoReferenceInput 数组。
additionalWitnessRequests - 可选 Array，string | Array<number> 路径数组。用于多签和代币铸造见证请求，因为这些无法从交易参数中确定。
metadata - 已移除 - 请使用 auxiliaryData 代替
derivationType - 可选 CardanoDerivationType 枚举，用于指定派生类型；默认值为 ICARUS=1。
includeNetworkId - 可选 Boolean，决定是否将 networkId 显式序列化到交易体中；默认值为 false。

CardanoTxSigningMode

ORDINARY_TRANSACTION

表示用于转移资金、委托质押或提取奖励的普通用户交易。交易见证会使用 inputs、certificates 和 withdrawals 中指定路径派生出的密钥生成；如果交易包含代币铸造，还会使用 additionalWitnessRequests 中指定路径派生出的密钥生成对应见证。

该交易

应该为所有 inputs 提供有效的 path 属性
不能携带矿池注册证书
不能包含 collateralInputs、collateralReturn、totalCollateral 或 referenceInputs
必须在证书和提款中使用路径作为质押凭证（不能改用密钥哈希或脚本哈希）
可以只使用 1852 和 1855 路径
不能在没有铸造或销毁代币的交易中包含 1855 见证请求

质押池注册证书说明

Ukey Wallet 支持用户以矿池所有者身份签署质押池注册证书。此类交易中可能包含外部输入（例如矿池运营者持有的输入），但 Ukey Wallet 无法确认这些输入是否真的来自外部账户。如果允许使用支出密钥对此类交易签名，用户可能会因为误签不打算支出的输入而造成资金损失。若交易中还包含提款，也可能带来误签提款的风险。为降低这些风险，质押池注册交易需要遵循一组特殊验证规则，并且这些规则也会在 Ukey Wallet 设备端进行校验：

交易不能包含其他任何证书，也不能再包含另一个质押池注册证书
交易不能包含任何提款
所有交易输入都必须是外部输入，也就是 path 必须为 undefined 或 null
必须且只能有一个所有者通过质押路径传入，其余所有者需要以 bech32 编码的奖励地址形式传入

治理注册（Catalyst 和其他）

Ukey Wallet 支持签署包含治理注册的辅助数据的交易。治理注册曾经遵循 CIP-15，现已被 CIP-36 取代。目前，Ukey Wallet 支持 CIP-15 和 CIP-36 格式，可以在 format 字段中指定预期标准（默认为 CIP-15）。它们的区别如下：

CIP-36 支持通过 CardanoGovernanceRegistrationDelegation 将投票权分配给多个投票公钥，并且每个公钥可以拥有不同权重，不再局限于只提供一个投票公钥。请注意，Ukey Wallet 固件在单个治理注册中最多支持 32 个委托项。
CIP-36 注册中包含 votingPurpose 字段，其中 0 表示 Catalyst 投票，1 表示其他用途。如果使用 CIP-36 格式但未提供该字段，Ukey Wallet 会默认序列化为 0。

Ukey Wallet 当前暂不支持 1694 派生路径。

示例

普通交易

HardwareSDK.cardanoSignTransaction(connectId, deviceId, {
  signingMode: CardanoTxSigningMode.ORDINARY_TRANSACTION,
  inputs: [
    {
      path: "m/1852'/1815'/1'/0/1",
      prev_hash:
        "4c51376222e9cc4d4d719ea6c4b1cf94572bdf43e8a44768ab2a4ac4bbe2d1c8",
      prev_index: 0,
    },
  ],
  outputs: [
    {
      address: "Ae2tdPwUPEZCanmBz5g2GEwFqKTKpNJcGYPKfDxoNeKZ8bRHr8366kseiK2",
      amount: "4203112",
    },
    {
      addressParameters: {
        addressType: CardanoAddressType.BASE,
        path: "m/1852'/1815'/1'/0/1",
        stakingPath: "m/1852'/1815'/1'/2/0",
      },
      amount: "8120787",
    },
    {
      format: CardanoTxOutputSerializationFormat.ARRAY_LEGACY,
      address:
        "addr1q84sh2j72ux0l03fxndjnhctdg7hcppsaejafsa84vh7lwgmcs5wgus8qt4atk45lvt4xfxpjtwfhdmvchdf2m3u3hlsd5tq5r",
      amount: "2500000",
      tokenBundle: [
        {
          policyId: "a6b3d1e9f42c8a7d5e0391bc6874fa20d95c1e7b34890a6c2d5f8e13",
          tokenAmounts: [
            {
              assetNameBytes: "556b6579436f696e",
              amount: "6578754",
            },
          ],
        },
      ],
    },
    {
      address: "addr1w9rhu54nz94k9l5v6d9rzfs47h7dv7xffcwkekuxcx3evnqpvuxu0",
      amount: "2",
      datumHash:
        "2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d",
    },
    {
      format: CardanoTxOutputSerializationFormat.MAP_BABBAGE,
      address: "addr1w9rhu54nz94k9l5v6d9rzfs47h7dv7xffcwkekuxcx3evnqpvuxu0",
      amount: "2",
      inlineDatum:
        "2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d",
      referenceScript:
        "2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d",
    },
  ],
  fee: "56",
  ttl: "18",
  validityIntervalStart: "28",
  certificates: [
    {
      type: CardanoCertificateType.STAKE_REGISTRATION,
      path: "m/1852'/1815'/1'/2/0",
    },
    {
      type: CardanoCertificateType.STAKE_DEREGISTRATION,
      path: "m/1852'/1815'/1'/2/0",
    },
    {
      type: CardanoCertificateType.STAKE_DELEGATION,
      path: "m/1852'/1815'/1'/2/0",
      pool: "a72f6c4d8b39e05a6f1c2d4b8e93a7510f6c2b9d4a813c5e7f9042ab",
    },
  ],
  withdrawals: [
    {
      path: "m/1852'/1815'/1'/2/0",
      amount: "1200",
    },
  ],
  auxiliaryData: {
    hash: "8b6f22d45a01e783f5c9ab21d3e4768091f5d2cb6a7e0f4358c14e90bd63a2f1",
  },
  scriptDataHash:
    "6a3f91c4b2e87d55a0184f9d7c3b0a6e5d214f8c90ab73e25d6f4189c2e0b7a3",
  protocolMagic: 764824073,
  networkId: 1,
  includeNetworkId: false,
});

质押池注册

HardwareSDK.cardanoSignTransaction(connectId, deviceId, {
  signingMode: CardanoTxSigningMode.POOL_REGISTRATION_AS_OWNER,
  inputs: [
    {
      // 注意此处不提供 path
      prev_hash:
        "2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d",
      prev_index: 0,
    },
  ],
  outputs: {
    address:
      "addr1q84sh2j72ux0l03fxndjnhctdg7hcppsaejafsa84vh7lwgmcs5wgus8qt4atk45lvt4xfxpjtwfhdmvchdf2m3u3hlsd5tq5r",
    amount: "1500000",
  },
  fee: "320000",
  ttl: "500000500",
  protocolMagic: 764824073,
  networkId: 1,
  includeNetworkId: false,
  certificates: [
    {
      type: CardanoCertificateType.STAKE_POOL_REGISTRATION,
      poolParameters: {
        poolId: "a72f6c4d8b39e05a6f1c2d4b8e93a7510f6c2b9d4a813c5e7f9042ab",
        vrfKeyHash:
          "35d9f1b67a402c8e91b6d5a30f8c72de49a1b0c5e73f26d8a94c0112be6f3458",
        pledge: "600000000", // lovelace 金额
        cost: "360000000", // lovelace 金额
        margin: {
          // numerator/denominator 应该 <= 1，然后转换为百分比
          numerator: "1",
          denominator: "3",
        },
        rewardAccount:
          "stake1uya87zwnmax0v6nnn8ptqkl6ydx4522kpsc3l3wmf3yswygwx45el", // bech32 编码的质押池奖励账户
        owners: [
          {
            stakingKeyPath: "m/1852'/1815'/1'/2/0", // 这是将在 Ukey Wallet 上签署交易的所有者密钥的路径
          },
          {
            stakingKeyHash:
              "4b8e10f2a6d3c95b7f1a0e2d9c6348b57123c4e6f8a9012b3c4d5e6f", // 其他所有者
          },
        ],
        relays: [
          {
            type: CardanoPoolRelayType.SINGLE_HOST_IP,
            ipv4Address: "192.168.1.10",
            ipv6Address: "2001:0db8:85a3:0000:0000:8a2e:0370:1234", // 完整形式的 ipv6 地址
            port: 2345,
          },
          {
            type: CardanoPoolRelayType.SINGLE_HOST_IP,
            ipv6Address: "2001:0db8:85a3:0000:0000:8a2e:0370:1234",
            port: 2345,
          },
          {
            type: CardanoPoolRelayType.SINGLE_HOST_IP,
            ipv4Address: "192.168.1.10",
            port: 2345,
          },
          {
            type: CardanoPoolRelayType.SINGLE_HOST_NAME,
            hostName: "pool.ukey.example",
            port: 2345,
          },
          {
            type: CardanoPoolRelayType.MULTIPLE_HOST_NAME,
            hostName: "relay.ukey.example", // 最长 64 个字符
          },
        ],
        metadata: {
          url: "https://pool.ukey.example", // 最长 64 个字符
          hash: "b28d64e1a70c9f4d83215b6e0f7a2c934a1d8e56c0b7492f3d5a6e7c8b901234",
        },
      },
    },
  ],
});

治理投票密钥注册

HardwareSDK.cardanoSignTransaction(connectId, deviceId, {
  signingMode: CardanoTxSigningMode.ORDINARY_TRANSACTION,
  inputs: [
    {
      path: "m/1852'/1815'/1'/0/1",
      prev_hash:
        "2b09fb1c8650aa0364e0949a5f74b3c1adc267d944cb29d4495321274a74ed0d",
      prev_index: 0,
    },
  ],
  outputs: [
    {
      address:
        "addr1q84sh2j72ux0l03fxndjnhctdg7hcppsaejafsa84vh7lwgmcs5wgus8qt4atk45lvt4xfxpjtwfhdmvchdf2m3u3hlsd5tq5r",
      amount: "4203112",
    },
  ],
  fee: "56",
  ttl: "18",
  auxiliaryData: {
    governanceRegistrationParameters: {
      votingPublicKey:
        "4c51376222e9cc4d4d719ea6c4b1cf94572bdf43e8a44768ab2a4ac4bbe2d1c8",
      stakingPath: "m/1852'/1815'/1'/2/0",
      rewardAddressParameters: {
        addressType: CardanoAddressType.REWARD,
        stakingPath: "m/1852'/1815'/1'/2/0",
      },
      nonce: "33845924",
    },
  },
  protocolMagic: 764824073,
  networkId: 1,
  includeNetworkId: false,
});

返回结果

受设备内存限制影响，Ukey Wallet 的 Cardano 签名流程采用交易流式传输。CardanoSignTransaction 调用结果不会直接返回完整的序列化交易，而是返回交易哈希、交易见证以及辅助数据补充；完整的序列化交易需要由客户端自行组装。

CardanoSignedTxData 类型

{
    success: true,
    payload: {
        hash: string,
        witnesses: CardanoSignedTxWitness[],
        auxiliaryDataSupplement?: CardanoAuxiliaryDataSupplement,
    }
}

示例：

{
    success: true,
    payload: {
        hash: "8f21c9a64b7d302ee5a18c9360f4bb287d6a45c3e91f2a0b74d8c5e1293f6a0c",
        witnesses: [
            {
                type: CardanoTxWitnessType.BYRON_WITNESS,
                pubKey: '7a1438d2e9c560b1f3d98a4e2c6710b58f24ed1398ab6c2f0d45e7a8932bc611',
                signature:
                    'b91c7d4285e6a3f01c2b984d7e0a6c43f52198d0be47a612c8f3d5490a1b7ce224c9a6f31d058be47c2935b8a160e4d27c9f183ab65d0e91f2c378a4b52d00',
                chainCode:
                    '4e35a2c9187f0b6d5a1c39e84270fd6b91c3e52a8b6d04f719c5e2380a6b4d9f',
            },
            {
                type: CardanoTxWitnessType.SHELLEY_WITNESS,
                pubKey: '8c6d1f2a9b3450e7c8f1324d6a59b0e3f7c821d4a0965e2b13c78f45d9a60b2c',
                signature:
                    'a7c2e4915b6f308d24c9a0e73f5b1d84c6e20a9f7d34b8612c5e098a4f63d127e90a5c3b8f16d4a2e7c093b65f81d240c7e9a358b146d0e52f3a789c1b600',
                chainCode: null,
            },
        ],
        auxiliaryDataSupplement: {
            type: 1,
            auxiliaryDataHash:
                'd4e27a905c1b6f38a9e0427c5d8316b0f2a94e67c3185d0b7f6a1c3e8924b5d0',
            governanceSignature:
                '9f6a3c1d8e2450b7a92f4c6d1e83b507a4c9d6e20f18b35c7a9412e6d8f0b3c241d7e90a5c3b8f16d4a2e7c093b65f81d240c7e9a358b146d0e52f3a789',
        },
    }
}

错误

{
    success: false,
    payload: {
        error: string, // 错误消息
        code: number // 错误码
    }
}

使用要求​

Cardano：签名交易 ​

参数 ​

CardanoTxSigningMode ​

质押池注册证书说明 ​

治理注册（Catalyst 和其他） ​

示例 ​

返回结果 ​

示例：​