URI de Bitcoin

Um URI de Bitcoin é um link, e clicar nele abre sua carteira com o pagamento já preenchido. O BIP21 fixou o formato em 29 de janeiro de 2012: o esquema bitcoin:, um endereço e, depois, parâmetros opcionais após um ponto de interrogação. Receber um URI em vez de um endereço puro retira o valor da lista de coisas que você precisa copiar corretamente.

Como funciona

A gramática do BIP21 é deliberadamente pequena, e essa é a principal razão de o formato ter sobrevivido sem alterações por mais de uma década.

Um URI completo se parece com bitcoin:bc1q...w5mdq?amount=0.00042&label=Coffee%20Shop&message=Order%20118. Tudo o que fica entre os dois pontos e o ponto de interrogação é o endereço de destino. Tudo o que vem depois é um conjunto de pares name=value unidos por &, e o BIP21 define apenas três:

• amount é um número decimal de bitcoin, nunca de satoshis, escrito com ponto e sem vírgulas nem símbolo de moeda. amount=0.01 significa um centésimo de bitcoin, ou seja, 1.000.000 satoshis.
• label nomeia quem recebe o pagamento, como uma loja ou uma pessoa.
• message diz para que serve o pagamento.

Os dois campos de texto usam codificação percentual em UTF-8, então um espaço vira %20 e um & dentro de um rótulo vira %26.

Duas regras mantêm o formato extensível. Parâmetros desconhecidos são ignorados, o que permite a uma carteira antiga ler um URI novo sem travar. Parâmetros com o prefixo req- são a exceção: uma carteira que não entende um deles deve rejeitar o URI inteiro em vez de adivinhar o que ele pretendia fazer. Essa única regra é todo o mecanismo de atualização, e desde então ele absorveu todas as extensões sem quebrar o software mais antigo.

É nessas extensões que o formato realmente vive hoje:

• r=, adicionado pelo BIP72, apontava para uma solicitação de pagamento BIP70. Esse caminho está morto.
• pj=, do BIP78, nomeia um endpoint de PayJoin para que pagador e recebedor construam juntos uma transação colaborativa.
• lightning= carrega uma fatura BOLT11 junto ao endereço on-chain. As carteiras que o entendem pagam pela Lightning, as que não entendem recorrem ao endereço, e as páginas de pagamento dos comerciantes imprimem o resultado como um único código QR unificado.
• O BIP353 publica um URI inteiro dentro de um registro TXT assinado com DNSSEC sob o rótulo _bitcoin-payment, de modo que um nome legível por humanos se resolve em instruções de pagamento.

O endereço em si é opcional. A gramática do BIP21 permite zero caracteres de endereço, que é como bitcoin:?r=... funcionava e como funciona hoje um URI que só leva uma oferta.

Por que isso importa quando você compra bitcoin

O momento em que um URI de Bitcoin mais importa é o saque, quando os bitcoins saem de uma corretora que você não controla e chegam a um lugar que você controla.

Quase toda corretora abordada neste site, da Kraken e da River até a Relai e a Bitpanda, oferece uma simples caixa de texto para o endereço de destino. Essa caixa quer o endereço, não o URI. Cole bitcoin:bc1q... nela e você normalmente receberá um erro de validação e, às vezes, um campo truncado sem aviso e um saque que falhou. Pegue o que fica entre os dois pontos e o ponto de interrogação e cole apenas isso.

O tráfego também corre no sentido contrário. A tela de recebimento da sua própria carteira de hardware, a página de pagamento de um comerciante e uma negociação ponto a ponto entregam a você URIs em vez de endereços puros. Um URI é mais seguro em exatamente um aspecto: o valor viaja com ele, então você não pode digitar o total errado. Ele não é mais seguro no aspecto que mais importa. Nada em um URI é assinado. O campo label é texto livre escolhido por quem montou a sequência de caracteres, então uma página de phishing pode escrever label=Kraken%20Withdrawal e sua carteira exibirá essas palavras sem comentário algum.

Por isso a tela da carteira de hardware é o controle que conta. Diga o que disser um URI, um dispositivo de assinatura mostra o endereço que ele está prestes a pagar em uma tela que o malware de área de transferência não pode reescrever. Compare os caracteres iniciais e finais ali, no dispositivo, não na aba do navegador que gerou o link.

Um exemplo prático: pagar a fatura de uma cafeteria

Suponha que um caixa imprima um código QR e seu celular leia bitcoin:bc1q...w5mdq?amount=0.00042&label=Kaffeehaus&message=Table%207.

Sua carteira extrai dali três fatos: pagar 0,00042 bitcoin, enviá-lo para aquele endereço e mostrar as palavras Kaffeehaus e Table 7 na tela de confirmação. Depois ela faz várias coisas que o URI nunca pediu. Escolhe quais das suas saídas não gastas usar, estima uma taxa a partir da sua própria visão da mempool, adiciona uma saída de troco e espera sua aprovação.

O que ela não faz é verificar nada sobre o destinatário. Não conferiu que a loja controla o endereço, que 0,00042 bitcoin é o preço combinado nem que o rótulo é honesto. Essas verificações são suas. Em um café, o prejuízo é um café perdido. Em uma transferência de cinco dígitos, vale a pena ler o endereço no dispositivo de assinatura, em grupos de quatro caracteres, antes de aprovar.

URI de Bitcoin vs endereço

Um endereço é o destino por si só, sem instruções anexadas. Um endereço bech32 moderno chega a 42 caracteres para uma saída segwit de chave única e a 62 para uma saída taproot, e não diz nada sobre quanto enviar nem para quem. Um URI é um contêiner: um endereço mais um valor, um rótulo e uma mensagem opcionais. Você sempre pode recuperar o endereço de um URI lendo o texto entre o esquema e o primeiro ponto de interrogação. Não dá para ir no sentido contrário, porque um endereço nunca levou um valor.

URI de Bitcoin vs fatura BOLT11

Uma fatura BOLT11 é o equivalente na Lightning, e se comporta de forma diferente em três aspectos que importam. Ela é de uso único, se compromete com um hash de pagamento em vez de um endereço e expira, por padrão em 3.600 segundos quando o comerciante não define valor algum. Um URI de Bitcoin nunca expira e pode ser pago duas vezes, o que é uma vantagem em uma página de doações e um perigo em uma fatura. O código QR unificado evita ter que escolher ao colocar uma sequência BOLT11 dentro do parâmetro lightning= de um URI comum, deixando cada carteira usar o meio que aceita.