Skip to main content

Solana (sol-sign-request)

ur:sol-sign-requestur:sol-signatureEd25519legacy + v0 messages

sol-sign-request​

KeyFieldTypeContent
1request-id37(bytes)Exactly 16 random bytes
2sign-databytessign-type 1: the serialized message · sign-type 2: the text message bytes
3derivation-path304(crypto-keypath)One of the three preset paths, with master fingerprint
4addressbytes (32)The signer's public key: the Base58-decoded address, not the text
5origintextShown to the user
6sign-typeuint1 transaction · 2 message

Note the key order differs from eth- and tron-sign-request: the path is key 3 and the type is key 6.

Keystone's helper wants hex

SolSignRequest.constructSOLRequest() in @keystonehq/bc-ur-registry-sol takes the address as a hex string of the 32 key bytes, not Base58. Passing the Base58 address produces a wrong key 4 and the request will not match.

sign-type 1: transactions​

sign-data is the message part of the transaction, the bytes that signatures cover: transaction.serializeMessage() in @solana/web3.js v1, or message.serialize() for a VersionedTransaction. Not the full transaction (which starts with the signature count and slots) and not a hash.

RuleDetail
Message versionsLegacy and v0
Address lookup tablesNot supported. The signer cannot verify table contents offline. Compile v0 messages with static keys only; if the result is too large, do not send it.
SignerThe key in key 4 must be one of the message's required signers (any slot, not only the fee payer).
Size1–64 instructions; the signed transaction must fit the 1,232-byte packet limit.
Durable nonceAllowed, but flagged in the review (such a transaction stays valid indefinitely).

Decoded programs: System (transfer, create account, nonce, assign, allocate), SPL Token and Token-2022 (transfer, transferChecked, approve, mint, burn, close, set authority, sync native), Associated Token Account (with address checks), Compute Budget, Memo, Stake (delegate, split, withdraw, deactivate) and common NFT programs (Metaplex Token Metadata, Bubblegum, Core). Token-2022 extensions and Squads proposal instructions are partially decoded. Other programs are shown as raw instructions and need explicit consent.

sign-type 2: messages​

sign-data is UTF-8 text, 1–1,024 bytes, without control characters. Bytes that could be read as a transaction header are rejected, so a transaction can never be passed off as a "message". BitTool Signer signs the message bytes directly with Ed25519 (no prefix, no hash), which is what signMessage in Solana wallet adapters expects.

sol-signature​

sol-signature = {
  1: 37(request-id bytes),
  2: signature                  ; 64 bytes, Ed25519
}

It is a detached signature. To finish a transaction:

  1. Check the request ID and verify the signature over the exact message bytes with the expected public key.
  2. Find the signer's index among the message's required signers and put the signature in that slot. It is not always slot 0.
  3. Keep any signatures already in the other slots; serialize once every required slot is filled and broadcast.

If the blockhash expires before broadcasting, build a new message and a new request. A signature cannot be moved to a message with another blockhash.

Code​

With @solana/web3.js v1 and Keystone's @keystonehq/bc-ur-registry-sol:

examples/solana.mjs
import { randomUUID } from 'node:crypto';
import { PublicKey, Transaction, SystemProgram } from '@solana/web3.js';
import { SolSignRequest, SignType, SolSignature } from '@keystonehq/bc-ur-registry-sol';
import { URDecoder } from '@ngraveio/bc-ur';
import { ed25519 } from '@noble/curves/ed25519.js';

export function buildSolTransfer({ from, to, lamports, recentBlockhash }) {
  const tx = new Transaction({ feePayer: new PublicKey(from), recentBlockhash });
  tx.add(SystemProgram.transfer({ fromPubkey: new PublicKey(from), toPubkey: new PublicKey(to), lamports }));
  return tx;
}

export function buildSolRequest(tx, { path, masterFingerprint, address }) {
  const requestId = randomUUID();
  const request = SolSignRequest.constructSOLRequest(
    tx.serializeMessage(),                                 // message bytes, not the whole transaction
    path,                                                  // "m/44'/501'/0'/0'"
    masterFingerprint,                                     // "73c5da0a"
    SignType.Transaction,                                  // 1 (2 = text message)
    requestId,
    new PublicKey(address).toBuffer().toString('hex'),     // this library wants hex, not Base58
    'BitTool Wallet',
  );
  const encoder = request.toUREncoder(400);
  const frames = [];
  for (let i = 0; i < encoder.fragmentsLength; i++) frames.push(encoder.nextPart().toUpperCase());
  return { requestId, frames };
}
examples/solana.mjs
export function attachSolSignature(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 !== 'sol-signature') throw new Error(`Expected sol-signature, got ${ur.type}`);
  const response = SolSignature.fromCBOR(ur.cbor);
  if (Buffer.from(response.getRequestId()).toString('hex') !== requestId.replace(/-/g, '')) throw new Error('Signature is for another request');

  const signature = Buffer.from(response.getSignature());   // 64-byte Ed25519 signature
  const signer = new PublicKey(address);
  if (!ed25519.verify(signature, tx.serializeMessage(), signer.toBytes())) throw new Error('Bad signature');
  tx.addSignature(signer, signature);                       // goes into this key's own slot
  return tx.serialize();                                    // throws if another required signature is missing
}

Test vectors​

All from the standard preset m/44'/501'/0'/0' (HAgk14JpMQLgt6rVgv7cBQFJWFto5Dqxi472uT3DKpqk). The blockhash is synthetic.

Send 0.25 SOL (250,000,000 lamports) with a legacy message: fee payer and signer, recipient, System Program.

Request (your wallet → BitTool Signer)

sol-sign-request2 frames
UR:SOL-SIGN-REQUEST/1-2/LPADAOCSZOCYLRESBDUEHDKBOLADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTBDAOHDMTADAEADAXWTENDIIDFGOSHPNTVLEENNTYDNBZVOEYYNGYMYSABSHESNGWCAIEVSCTNDTDHDYLKBLKAYLTHNRSUECAUTTKEYSELBCXNDLFFWWYGMPKWNEHZSSNLOTIWDDWJNBDAMWZAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAESFGAWZEETBWS
1 / 2
CBOR fields
{
  "1 request-id": {
    "uuid (tag 37)": "5f1e9b2c7d3a4e6f8a0b1c2d3e4f5a0b"
  },
  "2 sign-data": "01000103f036276246a75b9de3349ed42b15e232f6518fc20f5fcd4f1d64e81f9bd258f77e8c088760bfde1dddcf32c17f209b8242ee52aaf131facd88d0ea2c6d0b06f20000000000000000000000000000000000000000000000000000000000000000cc490e928cd2e3873bb343fc95da33179ca60f4dbf46c2c36e91299d55d4e6b901020200010c0200000080b2e60e00000000",
  "3 derivation-path": {
    "crypto-keypath (tag 304)": {
      "1 components": [
        44,
        true,
        501,
        true,
        0,
        true,
        0,
        true
      ],
      "2 source-fingerprint": 1942346250
    }
  },
  "4 address": "f036276246a75b9de3349ed42b15e232f6518fc20f5fcd4f1d64e81f9bd258f7",
  "5 origin": "BitTool Wallet",
  "6 sign-type": 1
}
Show the QR text and raw CBOR
QR text · ur:sol-sign-request
UR:SOL-SIGN-REQUEST/1-2/LPADAOCSZOCYLRESBDUEHDKBOLADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTBDAOHDMTADAEADAXWTENDIIDFGOSHPNTVLEENNTYDNBZVOEYYNGYMYSABSHESNGWCAIEVSCTNDTDHDYLKBLKAYLTHNRSUECAUTTKEYSELBCXNDLFFWWYGMPKWNEHZSSNLOTIWDDWJNBDAMWZAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAESFGAWZEETBWS
UR:SOL-SIGN-REQUEST/2-2/LPAOAOCSZOCYLRESBDUEHDKBBAMOLKTDVLLTFRQDFXZTMDTNEOCHNSOLBSGTRSFGSASRJTMEDTNTGOTYVARHADAOAOAEADBNAOAEAEAELAPRVABAAEAEAEAEAXTAADDYOEADLOCSDWYKCFADYKYKAEYKAEYKAOCYJKSKTNBKAAHDCXWTENDIIDFGOSHPNTVLEENNTYDNBZVOEYYNGYMYSABSHESNGWCAIEVSCTNDTDHDYLAHJTFWINJYGHJLJLJZCXHGHSJZJZIHJYAMADAEWYHKLNHH
UR CBOR (hex)
a601d825505f1e9b2c7d3a4e6f8a0b1c2d3e4f5a0b02589601000103f036276246a75b9de3349ed42b15e232f6518fc20f5fcd4f1d64e81f9bd258f77e8c088760bfde1dddcf32c17f209b8242ee52aaf131facd88d0ea2c6d0b06f20000000000000000000000000000000000000000000000000000000000000000cc490e928cd2e3873bb343fc95da33179ca60f4dbf46c2c36e91299d55d4e6b901020200010c0200000080b2e60e0000000003d90130a20188182cf51901f5f500f500f5021a73c5da0a045820f036276246a75b9de3349ed42b15e232f6518fc20f5fcd4f1d64e81f9bd258f7056e426974546f6f6c2057616c6c65740601

Response (BitTool Signer → your wallet)

Decoded response · ur:sol-signature
{
  "request-id": {
    "uuid": "5f1e9b2c7d3a4e6f8a0b1c2d3e4f5a0b"
  },
  "signature": "99b9a42fcb8eead46ae74c5e792098c247c21ab4d791af70a26d8392986d714fd4543af8f121c355ca32f747f321d52fc3856cf8b4ae678045a34648d924940c"
}
Show the QR text and raw CBOR
QR text · ur:sol-signature
UR:SOL-SIGNATURE/OEADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTBDAOHDFZNLRHOXDLSBMNWDTYIMVDGSHYKKCXMKSAFLSACYQZTSMEPEJOOEJNLSMOMKJNJSGWTYGHFTYAWNCLSRGOSGEYYLFLWFCLTLDLSRLPJZYAQZPLIOLAFEOTFGFDTADKMWBNDTZCBGGE
UR CBOR (hex)
a201d825505f1e9b2c7d3a4e6f8a0b1c2d3e4f5a0b02584099b9a42fcb8eead46ae74c5e792098c247c21ab4d791af70a26d8392986d714fd4543af8f121c355ca32f747f321d52fc3856cf8b4ae678045a34648d924940c

Assembled by your wallet

signatureBase58
45G7cB2HaLBrWEuZxiWR2dFYu52Cje6d2vv5GnCaZ7YSc6ifhFVdFTGpJSk1PU7tSTPHjg3H4uufoe3XPmTRQiJP
signedTransactionBase64
AZm5pC/LjurUaudMXnkgmMJHwhq015GvcKJtg5KYbXFP1FQ6+PEhw1XKMvdH8yHVL8OFbPi0rmeARaNGSNkklAwBAAED8DYnYkanW53jNJ7UKxXiMvZRj8IPX81PHWToH5vSWPd+jAiHYL/eHd3PMsF/IJuCQu5SqvEx+s2I0OosbQsG8gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAzEkOkozS44c7s0P8ldozF5ymD02/RsLDbpEpnVXU5rkBAgIAAQwCAAAAgLLmDgAAAAA=

Multi-signer transactions​

When a transaction needs several signers (an SPL multisig, a Squads proposal approval, a fee payer that is not the sender), send one request per BitTool Signer key, each with that key's path and address. Each response fills one slot. Squads is a program-level multisig: the signer sees the instruction that approves a proposal, not the proposal's contents, and says so in the review.