メインコンテンツまでスキップ

TRON（tron-sign-request）

ur:tron-sign-requestur:tron-signatureraw_data protobufTIP-191

BitTool Signer は、公開されている Keystone の TRON 用 UR 型を使います。TronLink や TokenPocket のアクション JSON、URL スキーム、旧来の keystone-sign-request は送らないでください。これらは拒否されます。

tron-sign-request​

キーフィールド型内容
1request-id37(bytes)ちょうど 16 バイトのランダム値
2sign-databytesdata-type 1：raw_data の protobuf バイト列 · data-type 2：メッセージのバイト列
3data-typeuint1 トランザクション · 2 パーソナルメッセージ
4derivation-path304(crypto-keypath)m/44'/195'/0'/0/i とマスターフィンガープリント
5addressbytes (21)0x41 ‖ 20 バイトのアカウント ID。テキストではなく、Base58Check でデコードしたアドレス
6origintextユーザーに表示される

data-type 1：トランザクション​

sign-data は、トランザクションの protobuf としてシリアライズした raw_data です。つまり TronWeb や /wallet/createtransaction、/wallet/triggersmartcontract API が返す raw_data_hex のバイト列です。（raw_data と signature を包む）Transaction メッセージ全体でも、16 進テキストでも、txID でもありません。

署名デバイスは txID = SHA-256(raw_data) を計算し、そのダイジェストに署名します。ルールは次のとおりです。

ルール詳細
コントラクトは 1 つraw_data.contract のエントリはちょうど 1 つ。
時刻関連フィールドref_block_bytes（2 バイト）、ref_block_hash（8 バイト）、timestamp > 0、かつ expiration > timestamp。
手数料上限TriggerSmartContract では必須（> 0）。手数料上限が高い場合は警告が表示されます。
パーミッションPermission_id は 0（owner）またはアクティブパーミッションの ID。1（witness）は拒否されます。
厳密な protobuf未知のフィールド、重複フィールド、非正準な varint は拒否されます。
TRC-10非対応。コントラクト呼び出し内の call_token_value も含みます。

対応するコントラクト：

タイプコントラクト確認内容
1TransferContractTRX の金額と受取人
31TriggerSmartContractTRC-20、TRC-721、TRC-1155 の送金と承認はデコードされます（例：USDT の transfer）。その他の呼び出しは生の calldata として表示され、明示的な同意が必要です
46AccountPermissionUpdateContractowner/active パーミッション、鍵、重み、しきい値。常に高リスク
54–59Stake 2.0 とリソース：FreezeBalanceV2、UnfreezeBalanceV2、WithdrawExpireUnfreeze、DelegateResource、UnDelegateResource、CancelAllUnfreezeV2金額、リソースの種類、受取人、ロック

data-type 2：メッセージ​

sign-data はメッセージのバイト列（1〜8,192 バイト）です。署名デバイスは、TronWeb の signMessageV2 の方式である TIP-191 に従います。

digest = Keccak-256( 0x19 ‖ "TRON Signed Message:\n" ‖ decimal(length of message) ‖ message )

テキストはテキストとして表示されます。それ以外のバイト列は不透明なデータとして 16 進で表示され、明示的な同意が必要です。

tron-signature​

tron-signature = {
  1: 37(request-id bytes),
  2: signature                 ; 65 bytes: r (32) ‖ s (32) ‖ recovery id (0 or 1)
}

リカバリーバイトは 27/28 ではなく 0 または 1 です。トランザクションの場合は、65 バイトを 16 進にしてトランザクションの signature 配列に追加し、raw_data と raw_data_hex は変更せずに、/wallet/broadcasttransaction（TronWeb では trx.sendRawTransaction）でブロードキャストします。

メッセージの場合、多くの TRON ツール（TronWeb の verifyMessageV2、WalletConnect 経由の dApp）は末尾のバイトが 27/28 であることを想定しています。署名を渡すときに 27 を加えてください。トランザクション署名のフォーマットは変更しないでください。

コード​

TRON には広く使われている UR レジストリライブラリがないため、このサンプルでは keypath ヘルパー を使い、cborg で CBOR を直接書き出しています。

examples/tron.mjs
import { randomBytes } from 'node:crypto';
import { UR, UREncoder, URDecoder } from '@ngraveio/bc-ur';
import { base58check } from '@scure/base';
import { sha256 } from '@noble/hashes/sha2.js';
import { encode, decode, Tagged } from 'cborg';
import { SigningKey, computeAddress } from 'ethers';
import { keypath } from './keypath.mjs';

const b58 = base58check(sha256);

// `tx` is an unsigned transaction from TronWeb / the TRON HTTP API: { txID, raw_data, raw_data_hex }
export function buildTronRequest(tx, { path, masterFingerprint, address }) {
  const requestId = randomBytes(16);
  const cbor = encode(new Map([
    [1, new Tagged(37, requestId)],                           // request-id (uuid)
    [2, Buffer.from(tx.raw_data_hex, 'hex')],          // raw_data protobuf bytes
    [3, 1],                                            // data-type: 1 transaction, 2 message
    [4, keypath(path, masterFingerprint)],             // "m/44'/195'/0'/0/0"
    [5, b58.decode(address)],                          // 21 bytes: 0x41 ‖ 20-byte account ID
    [6, 'BitTool Wallet'],                             // origin
  ]));
  const encoder = new UREncoder(new UR(Buffer.from(cbor), 'tron-sign-request'), 400);
  const frames = [];
  for (let i = 0; i < encoder.fragmentsLength; i++) frames.push(encoder.nextPart().toUpperCase());
  return { requestId, frames };
}
examples/tron.mjs
const tags = { 37: (decode) => decode() };                // tag 37 (uuid): keep the raw bytes

export function attachTronSignature(frames, tx, { requestId, address }) {
  const decoder = new URDecoder();
  for (const frame of frames) decoder.receivePart(frame);
  if (!decoder.isSuccess()) throw new Error('Incomplete or invalid QR');
  const ur = decoder.resultUR();
  if (ur.type !== 'tron-signature') throw new Error(`Expected tron-signature, got ${ur.type}`);
  const response = decode(ur.cbor, { useMaps: true, tags, strict: true });
  if (!Buffer.from(response.get(1)).equals(requestId)) throw new Error('Signature is for another request');

  const sig = Buffer.from(response.get(2));                // r (32) ‖ s (32) ‖ recovery id (0 or 1)
  if (sig.length !== 65 || sig[64] > 1) throw new Error('Unexpected signature format');
  const txID = Buffer.from(sha256(Buffer.from(tx.raw_data_hex, 'hex'))).toString('hex');
  if (txID !== tx.txID) throw new Error('txID does not match raw_data');

  const evmStyle = { r: '0x' + sig.subarray(0, 32).toString('hex'), s: '0x' + sig.subarray(32, 64).toString('hex'), v: 27 + sig[64] };
  const recovered = computeAddress(SigningKey.recoverPublicKey('0x' + txID, evmStyle));  // 0x + 20 bytes
  if (b58.encode(Buffer.from('41' + recovered.slice(2), 'hex')) !== address) throw new Error('Signed by an unexpected key');

  return { ...tx, signature: [...(tx.signature ?? []), sig.toString('hex')] };   // broadcast with sendRawTransaction
}

テストベクター​

すべてテストフレーズの m/44'/195'/0'/0/0（TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH）から生成しています。参照ブロック、タイムスタンプ、txID は合成したもので、トランザクションは一度もブロードキャストされていません。

1.5 TRX（1,500,000 sun）を TJRabPrwbZy45sbavfcjinPJC18kjpRTv8 に送金します。

未署名トランザクション（ノードまたは TronWeb から取得）
{
  "txID": "b396c11e25482bc348d39e620000ef16290d0d17b7649cb94fee63d0203695eb",
  "raw_data": {
    "contract": [
      {
        "parameter": {
          "value": {
            "amount": 1500000,
            "owner_address": "41c8599111f29c1e1e061265b4af93ea1f274ad78a",
            "to_address": "415cbdd86a2fa8dc4bddd8a8f69dba48572eec07fb"
          },
          "type_url": "type.googleapis.com/protocol.TransferContract"
        },
        "type": "TransferContract"
      }
    ],
    "ref_block_bytes": "a1b2",
    "ref_block_hash": "0123456789abcdef",
    "expiration": 1792310460000,
    "timestamp": 1792310400000
  },
  "raw_data_hex": "0a02a1b222080123456789abcdef40e0fc9cf094345a67080112630a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412320a1541c8599111f29c1e1e061265b4af93ea1f274ad78a1215415cbdd86a2fa8dc4bddd8a8f69dba48572eec07fb18e0c65b7080a899f09434"
}

リクエスト（ウォレット → BitTool Signer）

tron-sign-request2 フレーム
UR:TRON-SIGN-REQUEST/1-2/LPADAOCSURCYBDFNCLLAHDJOOLADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTAYAOHDLPBKAOOYPRCPAYADCNFEIOLDPYSNWSFZVTZTNSWTMWEEHTIOAYADBGIABKDPJYKKJOIHDMIOJLJLIOJZIHHSJOINJKDMIAJLJNDLJOJPJLJYJLIAJLJZDMGHJPHSJTJKIYIHJPFXJLJTJYJPHSIAJYBGEYBKBZFPSPHKMEBYWZNSCKCKAMKIYKMUHK
1 / 2
CBOR フィールド
{
  "1 request-id": {
    "uuid (tag 37)": "5f1e9b2c7d3a4e6f8a0b1c2d3e4f5a08"
  },
  "2 sign-data": "0a02a1b222080123456789abcdef40e0fc9cf094345a67080112630a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412320a1541c8599111f29c1e1e061265b4af93ea1f274ad78a1215415cbdd86a2fa8dc4bddd8a8f69dba48572eec07fb18e0c65b7080a899f09434",
  "3 data-type": 1,
  "4 derivation-path": {
    "crypto-keypath (tag 304)": {
      "1 components": [
        44,
        true,
        195,
        true,
        0,
        true,
        0,
        false,
        0,
        false
      ],
      "2 source-fingerprint": 1942346250
    }
  },
  "5 address": "41c8599111f29c1e1e061265b4af93ea1f274ad78a",
  "6 origin": "BitTool Wallet"
}
QR テキストと生の CBOR を表示
QR テキスト · ur:tron-sign-request
UR:TRON-SIGN-REQUEST/1-2/LPADAOCSURCYBDFNCLLAHDJOOLADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTAYAOHDLPBKAOOYPRCPAYADCNFEIOLDPYSNWSFZVTZTNSWTMWEEHTIOAYADBGIABKDPJYKKJOIHDMIOJLJLIOJZIHHSJOINJKDMIAJLJNDLJOJPJLJYJLIAJLJZDMGHJPHSJTJKIYIHJPFXJLJTJYJPHSIAJYBGEYBKBZFPSPHKMEBYWZNSCKCKAMKIYKMUHK
UR:TRON-SIGN-REQUEST/2-2/LPAOAOCSURCYBDFNCLLAHDJOBGIHQZPEMUWDCTDIGETSLEBGBZFPHHRYTPIMDLPDUOGRUTTPPDYNNTRDFDHGDMWPATZOCSVTSWHPJOLAPDNLWTMWEEAXADAATAADDYOEADLECSDWYKCSSRYKAEYKAEWKAEWKAOCYJKSKTNBKAHGOFPSPHKMEBYWZNSCKCKAMBGIHQZPEMUWDCTDIGETSLEAMJTFWINJYGHJLJLJZCXHGHSJZJZIHJYAECEGYGWVW
UR CBOR（16 進）
a601d825505f1e9b2c7d3a4e6f8a0b1c2d3e4f5a080258850a02a1b222080123456789abcdef40e0fc9cf094345a67080112630a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412320a1541c8599111f29c1e1e061265b4af93ea1f274ad78a1215415cbdd86a2fa8dc4bddd8a8f69dba48572eec07fb18e0c65b7080a899f09434030104d90130a2018a182cf518c3f500f500f400f4021a73c5da0a055541c8599111f29c1e1e061265b4af93ea1f274ad78a066e426974546f6f6c2057616c6c6574

レスポンス（BitTool Signer → ウォレット）

デコードしたレスポンス · ur:tron-signature
{
  "request-id": {
    "uuid": "5f1e9b2c7d3a4e6f8a0b1c2d3e4f5a08"
  },
  "signature": "32c82fe12ddef67b967c836692f7a729003481e6b0f070b1ac6ee7742ac27e18611174e6a54efb7f5f5e14adfbb9118bb137f064881777316ed593ea5da4a25d01"
}
QR テキストと生の CBOR を表示
QR テキスト · ur:tron-signature
UR:TRON-SIGNATURE/OEADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTAYAOHDFPEYSPDLVYDPUEYNKGMTKELSIYMOYLOSDTAEEELYVAPFWTJOPAPSJTVDJYDRSAKBCSHSBYJYVAONGLZOLBHEHYBBPMZORHBYLUPAEMWTIELOCHKTEHJTTLMUWDHLOXOEHLADEEFEIELE
UR CBOR（16 進）
a201d825505f1e9b2c7d3a4e6f8a0b1c2d3e4f5a0802584132c82fe12ddef67b967c836692f7a729003481e6b0f070b1ac6ee7742ac27e18611174e6a54efb7f5f5e14adfbb9118bb137f064881777316ed593ea5da4a25d01

ウォレット側で組み立てた結果

signedTransaction
{
  "txID": "b396c11e25482bc348d39e620000ef16290d0d17b7649cb94fee63d0203695eb",
  "raw_data": {
    "contract": [
      {
        "parameter": {
          "value": {
            "amount": 1500000,
            "owner_address": "41c8599111f29c1e1e061265b4af93ea1f274ad78a",
            "to_address": "415cbdd86a2fa8dc4bddd8a8f69dba48572eec07fb"
          },
          "type_url": "type.googleapis.com/protocol.TransferContract"
        },
        "type": "TransferContract"
      }
    ],
    "ref_block_bytes": "a1b2",
    "ref_block_hash": "0123456789abcdef",
    "expiration": 1792310460000,
    "timestamp": 1792310400000
  },
  "raw_data_hex": "0a02a1b222080123456789abcdef40e0fc9cf094345a67080112630a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412320a1541c8599111f29c1e1e061265b4af93ea1f274ad78a1215415cbdd86a2fa8dc4bddd8a8f69dba48572eec07fb18e0c65b7080a899f09434",
  "signature": [
    "32c82fe12ddef67b967c836692f7a729003481e6b0f070b1ac6ee7742ac27e18611174e6a54efb7f5f5e14adfbb9118bb137f064881777316ed593ea5da4a25d01"
  ]
}

マルチシグアカウント​

マルチシグのパーミッションを持つアカウントでは、各メンバーが個別に署名します。

  • キー 4 と 5 には メンバー のパスとアドレスを入れてください。owner_address のアカウントは別のアドレスである場合があり、BitTool Signer は owner やパーミッションのメンバーとして記載されているという理由だけで署名者を選ぶことはありません。
  • コントラクトの Permission_id には、使用するパーミッションを設定してください。
  • BitTool Signer が参照するのは raw_data だけです。ウォレット側で収集済みの署名を保持し、新しい署名を追加して重複を取り除き、ブロードキャストする前にオンチェーンのパーミッション（メンバー、重み、しきい値、操作）を確認してください。署名デバイスはオフラインのため、現在のオンチェーンのパーミッションを検証できません。