Geração de Carteira Bitcoin Bech32 (Testnet) em Python

Luciano Magalhães   |    Agosto, 2025   | Desenvolvimento / Blockchain

Banner do Projeto BTC


1. Contexto

Este projeto foi desenvolvido para atender à necessidade de geração de carteiras Bitcoin compatíveis com a rede de testes (testnet), utilizadas em ambientes de simulação, validação de transações e integração com scripts de monitoramento. A proposta é garantir reprodutibilidade, segurança e clareza na geração de credenciais criptográficas, com foco em carteiras Bech32 (padrão BIP84), amplamente utilizadas em aplicações modernas de Bitcoin. O projeto é executado em ambiente Python, com estrutura modular e encapsulamento dos dados gerados, permitindo uso direto em notebooks de simulação de transações e verificação de saldo.

2. Objetivo

O objetivo principal deste trabalho é gerar, em Python, uma carteira Bitcoin Bech32 para uso exclusivo em ambiente de testes (testnet), contemplando:

  • Criação de frase mnemônica conforme o padrão BIP39.
  • Derivação da seed criptográfica a partir da mnemônica e aplicação do caminho BIP84.
  • Derivação da chave privada e do endereço público no padrão BIP84, resultando em endereço Bech32 (tb1...).
  • Encapsulamento dos dados gerados em estrutura imutável, garantindo integridade e reprodutibilidade.
  • Compatibilidade com notebooks de geração e verificação de saldo em ambiente de testes.

3. Metodologia

A metodologia adotada segue os princípios de modularidade, clareza algorítmica e separação de responsabilidades. O projeto foi estruturado em etapas sequenciais e independentes, permitindo rastreabilidade e validação de cada componente:

  • Geração da mnemônica: Utilização do padrão BIP39 com 12 palavras.
  • Derivação da seed: Conversão da mnemônica em bytes para uso criptográfico.
  • Aplicação do caminho BIP84: Derivação da chave privada e do endereço público Bech32 (tb1...).
  • Encapsulamento dos dados: Uso de dataclass imutável para representar a carteira gerada.
  • Importação modular: A função principal gerar_carteira_bech32() é exposta via pacote btc_wallet_testnet, permitindo uso direto em notebooks e scripts externos.

Levantamento de Requisitos — Gerar Carteira Bitcoin (Testnet)

4 — Configura caminho para importação do pacote

In [1]:
# 4 — Ajuste de caminho para importação do pacote
import sys
import os

# Caminho absoluto para a pasta src/
caminho_src = os.path.abspath(os.path.join(os.getcwd(), "..", "src"))
if caminho_src not in sys.path:
    sys.path.insert(0, caminho_src)

5. Importação de Módulos

Nesta etapa, importamos as funções e classes necessárias para a execução do projeto a partir do pacote btc_wallet_testnet. Especificamente, utilizaremos a função gerar_carteira_bech32, responsável por criar a carteira Bitcoin na testnet, e a classe Wallet, que encapsula de forma imutável os dados da carteira gerada.

In [2]:
# 05 — Importação de Módulos

from btc_wallet_testnet import gerar_carteira_bech32, Carteira
× 
''' 
Arquivo __init__.py

Pacote btc_wallet_testnet

Este pacote apresenta:
- Função para geração de carteira
- Utilitários para mnemônicos

Autor: Luciano Magalhães / BH / MG / Brasil
Versão: 1.0
Data: 2025 julho
'''

from .create_wallet import (
    Wallet,
    gerar_carteira_bech32,
    generate_mnemonic,
    main
)

__all__ = [
    "Wallet",
    "gerar_carteira_bech32",
    "generate_mnemonic",
    "main"
]
× 
"""
Arquivo: create_wallet.py

- Geração de frase mnemônica BIP39
- Derivação de chave privada e endereço Bech32 (tb1...)

Autor: Luciano Magalhães / BH / MG / Brasil
Versão: 1.0
Data: 2025 agosto
"""

from __future__ import annotations
from dataclasses import dataclass
from typing import Optional

from bip_utils import (
    Bip39MnemonicGenerator,
    Bip39SeedGenerator,
    Bip39WordsNum,
    Bip84,
    Bip84Coins,
    Bip44Changes,
)

DEFAULT_PATH = "m/84'/1'/0'/0/0"

@dataclass(frozen=True)
class Wallet:
    address: str
    wif: str
    mnemonic: str
    path: str

def generate_mnemonic(words: int = 12) -> str:
    if words not in (12, 24):
        raise ValueError("Número de palavras deve ser 12 ou 24.")
    num_enum = Bip39WordsNum.WORDS_NUM_24 if words == 24 else Bip39WordsNum.WORDS_NUM_12
    return Bip39MnemonicGenerator().FromWordsNumber(num_enum)

def gerar_carteira_bech32(
    mnemonic: Optional[str] = None,
    passphrase: str = "",
    path: str = DEFAULT_PATH
) -> Wallet:
    mn = mnemonic or generate_mnemonic()
    seed = Bip39SeedGenerator(mn).Generate(passphrase)
    bip84 = Bip84.FromSeed(seed, Bip84Coins.BITCOIN_TESTNET)
    node = bip84.Purpose().Coin().Account(0).Change(Bip44Changes.CHAIN_EXT).AddressIndex(0)

    address = node.PublicKey().ToAddress()
    wif = node.PrivateKey().ToWif()

    if not address.startswith("tb1"):
        raise RuntimeError("Endereço gerado não é Bech32 testnet (tb1...).")

    return Wallet(address=address, wif=wif, mnemonic=mn, path=path)

def main() -> None:
    wallet = gerar_carteira_bech32()
    print("\n✅ Carteira gerada com sucesso:")
    print(f"- Endereço Bech32: {wallet.address}")
    print(f"- Chave privada WIF: {wallet.wif}")
    print(f"- Frase mnemônica: {wallet.mnemonic}")
    print(f"- Caminho derivado: {wallet.path}\n")

if __name__ == "__main__":
    main()

6. Execução da Geração da Carteira

Aqui executamos a função gerar_carteira_bech32, que realiza internamente a criação da frase mnemônica, derivação da chave privada no padrão BIP84 para a rede de testes e geração do endereço Bech32. O resultado é armazenado no objeto carteira para utilização posterior.

In [3]:
# 06 — Execução da Geração

carteira = gerar_carteira_bech32()

7. Visualização dos Resultados

Agora apresentamos os principais elementos da carteira gerada: endereço Bech32 (testnet), chave privada em formato WIF, frase mnemônica BIP39 e o caminho de derivação utilizado. Esta visualização é essencial para validar se a carteira foi criada corretamente e para documentar os dados de forma controlada durante os testes.

In [4]:
# 07 — Visualização dos Resultados

print("Endereço Bech32 (testnet):", carteira.address)
print("Chave privada (WIF):       ", carteira.wif)
print("Frase mnemônica:           ", carteira.mnemonic)
print("Caminho derivado:          ", carteira.path)

Endereço Bech32 (testnet): tb1qhfg0dcdxnlm0jq7tytyp2z5t3sml8k3ms2uxgx
Chave privada (WIF):        cMz5arjiGKDrqBQRha4XVTcLX65o5DC4SB6NSjWadUYfBcGD3ehP
Frase mnemônica:            enrich length embrace beef poet embrace miss wagon follow route series pottery
Caminho derivado:           m/84'/1'/0'/0/0

8. 🔐 Considerações sobre Segurança

As credenciais geradas neste projeto — como a chave privada e a frase mnemônica — são utilizadas exclusivamente em ambiente de testes (testnet) e não possuem valor real. Ainda assim, recomenda-se que essas informações não sejam reutilizadas em ambientes de produção, nem compartilhadas fora do contexto técnico deste projeto, evitando confusões ou uso indevido em aplicações reais.

9. 🔁 Integração com Simulação de Transação Bitcoin

A carteira gerada neste projeto — contendo chave privada, pública e endereço Bech32 — pode ser utilizada diretamente em ambientes de simulação para realizar transações reais na rede de testes (testnet). Para demonstrar essa aplicabilidade, desenvolvi um módulo complementar que realiza o envio de criptomoedas utilizando os dados da carteira gerada aqui.

Esse segundo projeto contempla:

  • Consulta de saldo e UTXOs disponíveis
  • Criação e assinatura da transação
  • Transmissão e validação do TXID
  • Monitoramento da confirmação via exploradores públicos

🔗 Acesse o notebook de simulação de transação para entender como a carteira gerada neste módulo pode ser utilizada em operações reais de teste.

© Copyright 2025 | Luciano Magalhães