본문으로 건너뛰기

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는 트랜잭션의 raw_data를 protobuf로 직렬화한 바이트입니다. 즉 TronWeb이나 /wallet/createtransaction, /wallet/triggersmartcontract API가 반환하는 raw_data_hex의 바이트입니다. raw_data와 signature를 감싸는 Transaction 메시지 전체도, hex 텍스트도, txID도 아닙니다.

서명 기기는 txID = SHA-256(raw_data)를 계산해 그 다이제스트에 서명합니다. 규칙은 다음과 같습니다.

규칙세부 내용
컨트랙트 하나raw_data.contract에 항목이 정확히 하나여야 합니다.
시간 필드ref_block_bytes(2바이트), ref_block_hash(8바이트), timestamp > 0, expiration > timestamp.
수수료 한도TriggerSmartContract에는 필수(> 0)입니다. 높은 수수료 한도는 경고로 표시됩니다.
권한Permission_id 0(owner) 또는 active 권한 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 )

텍스트는 텍스트로 표시합니다. 그 밖의 바이트는 hex로 보여 주고 해석 불가(opaque)로 표시하며, 명시적 동의가 필요합니다.

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바이트를 hex로 트랜잭션의 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는 합성 데이터이며, 트랜잭션은 브로드캐스트된 적이 없습니다.

TJRabPrwbZy45sbavfcjinPJC18kjpRTv8로 1.5 TRX(1,500,000 sun)를 보냅니다.

서명되지 않은 트랜잭션 (노드 또는 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 (hex)
a601d825505f1e9b2c7d3a4e6f8a0b1c2d3e4f5a080258850a02a1b222080123456789abcdef40e0fc9cf094345a67080112630a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412320a1541c8599111f29c1e1e061265b4af93ea1f274ad78a1215415cbdd86a2fa8dc4bddd8a8f69dba48572eec07fb18e0c65b7080a899f09434030104d90130a2018a182cf518c3f500f500f400f4021a73c5da0a055541c8599111f29c1e1e061265b4af93ea1f274ad78a066e426974546f6f6c2057616c6c6574

응답 (BitTool Signer → 내 지갑)

디코딩된 응답 · ur:tron-signature
{
  "request-id": {
    "uuid": "5f1e9b2c7d3a4e6f8a0b1c2d3e4f5a08"
  },
  "signature": "32c82fe12ddef67b967c836692f7a729003481e6b0f070b1ac6ee7742ac27e18611174e6a54efb7f5f5e14adfbb9118bb137f064881777316ed593ea5da4a25d01"
}
QR 텍스트와 원본 CBOR 보기
QR 텍스트 · ur:tron-signature
UR:TRON-SIGNATURE/OEADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTAYAOHDFPEYSPDLVYDPUEYNKGMTKELSIYMOYLOSDTAEEELYVAPFWTJOPAPSJTVDJYDRSAKBCSHSBYJYVAONGLZOLBHEHYBBPMZORHBYLUPAEMWTIELOCHKTEHJTTLMUWDHLOXOEHLADEEFEIELE
UR CBOR (hex)
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만 봅니다. 이미 수집한 서명을 보관하고, 새 서명을 추가하고, 중복을 제거하고, 브로드캐스트하기 전에 온체인 권한(구성원, 가중치, 임계값, 작업)을 확인하는 것은 지갑의 몫입니다. 서명 기기는 오프라인에서 현재 온체인 권한을 확인할 수 없습니다.