Script de Integração IceSecp256k1: Gere e Verifique WIFs Bitcoin
- O script integra a DLL IceSecp256k1 com fallback automático para Python puro, permitindo gerar e verificar WIFs mesmo sem a DLL nativa.
- Oferece 3 camadas de operação criptográfica — DLL, coincurve e ponto-a-ponto manual — garantindo funcionamento em qualquer ambiente Windows.
- Inclui conversão WIF/hex, hash160, derivação de endereço Bitcoin e verificação em lote, com correção recente de compatibilidade entre versões da lib base58.
ID de vídeo padrão usado — substituir antes de publicar
O que o script wif_ice_integration.py faz?
O wif_ice_integration.py é uma ferramenta desenvolvida em Python que integra a DLL IceSecp256k1 (criada por k3ntina/kTimesG) para realizar operações criptográficas da curva secp256k1 do Bitcoin. Ele converte chaves privadas para o formato WIF (Wallet Import Format), deriva endereços Bitcoin, calcula hash160 e verifica a validade de WIFs — tudo isso com fallback automático quando a DLL não está disponível.
Aqui no @CanalQb, validamos que esse tipo de script é essencial para quem trabalha com análise de carteiras, geração de chaves, testes de integração ou ferramentas de auditoria on-chain. O grande diferencial é a arquitetura de fallback em três camadas, que permite o script funcionar em qualquer máquina Windows mesmo sem a DLL compilada.
Para que serve o WIF no ecossistema Bitcoin?
WIF (Wallet Import Format) é o formato padrão usado para representar chaves privadas Bitcoin de forma compacta e segura, com checksum embutido via base58check. Uma chave privada em hex como 0000000000000000000000000000000000000000000000000000000000000001 vira o WIF KwDiBf89QgGbjEhKnhXJuH7LrciVrZi3qYjgd9M7rFU73sVHnoWn.
Esse formato é universal em carteiras Bitcoin: toda carteira que exporta ou importa chaves privadas usa WIF. Sem ele, você teria que lidar com hex bruto de 64 caracteres, sem proteção contra erros de digitação. O checksum embutido no base58check detecta erros de transcrição antes que você tente usar a chave.
O script permite circular entre os dois formatos livremente: priv_to_wif() converte hex para WIF e wif_to_priv() faz o caminho inverso. A utilidade prática aparece quando você precisa importar chaves geradas por ferramentas técnicas em carteiras comuns como Electrum, Bitcoin Core ou BlueWallet.
Como funciona a integração com a DLL IceSecp256k1?
A DLL ice_secp256k1.dll expõe funções otimizadas em C para operações na curva elíptica secp256k1. O script usa ctypes para carregá-la e configurar as assinaturas das funções manualmente, já que a DLL não tem arquivos de cabeçalho no estilo Windows padrão.
As funções da DLL que o script tenta usar são:
privatekey_loop_h160— loop de chave privada para hash160 (ideal para varredura em lote)hash160— SHA256 + RIPEMD160 em uma chamadahash_to_address— hash160 para endereço Bitcoinpriv_to_pub— multiplicação escalar na curva secp256k1
O carregamento é feito como singleton via IceSecp256k1DLL.load(), que só tenta carregar a DLL uma vez e armazena o resultado em cache. Se a DLL não existe ou falha ao carregar, o script armazena o erro e retorna None — momento em que todas as funções que dependem dela ativam o fallback automático.
hash160 da DLL tem um problema conhecido de convenção de chamada no Windows com ctypes, que pode causar access violation. O script já trata isso com try/except e fallback para o hash160 puro em Python.
Passo a passo: como usar o script
Passo 1: Instale as dependências
O script depende de duas bibliotecas Python: base58 e coincurve. A base58 é responsável pela codificação/decodificação no formato base58check, que é o que dá ao WIF sua representação compacta com checksum. A coincurve é uma binding Python otimizada para a libsecp256k1 do Bitcoin Core, usada como primeira alternativa à DLL.
Esse passo é necessário porque o script importa ambos os pacotes no topo. Sem eles, você receberá um ModuleNotFoundError antes mesmo de qualquer execução.
Comando para instalar:
Quando funcionar, você verá as bibliotecas sendo baixadas e instaladas, seguidas do prompt de comando novamente. Se já estiverem instaladas, o pip apenas confirma que os requisitos já foram atendidos.
pip install --user base58 coincurve ou execute o terminal como Administrador. Em ambientes virtuais, certifique-se de que o venv está ativado antes de instalar.
Passo 2: Coloque a DLL no diretório correto
A DLL ice_secp256k1.dll deve estar na pasta puzzlescript/ (um nível acima do script). O script constrói o caminho automaticamente com SCRIPT_DIR = Path(__file__).parent.parent, resultando em puzzlescript/ice_secp256k1.dll.
Esse passo é necessário porque o script verifica a existência do arquivo com DLL_PATH.exists() antes de tentar carregar. Se a DLL não estiver no local exato, o script carrega None e usa exclusivamente os fallbacks Python — o que funciona, mas perde a performance da implementação nativa em C.
Quando a DLL está no lugar certo, a saída na inicialização mostra:
Se a DLL não for encontrada, a mensagem será DLL not found e o script continua com os fallbacks.
DLL_PATH não vai encontrá-la. O script espera a estrutura puzzlescript/scripts/wif_ice_integration.py e puzzlescript/ice_secp256k1.dll. Verifique a árvore de diretórios antes de executar.
Passo 3: Execute o script
Navegue até a pasta scripts/ e execute o script com Python:
Esse comando executa o bloco if __name__ == "__main__" que está no final do arquivo. Ele testa a DLL, gera o WIF para a chave privada 1, deriva o endereço e exibe os resultados.
Resultado esperado com DLL carregada:
O endereço 1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH é o endereço Bitcoin conhecido para a chave privada 1 (compressed). Se você ver esse endereço, o script está funcionando perfeitamente.
wif_to_priv() retorna None porque a biblioteca base58 já remove o checksum de 4 bytes na decodificação, mas o código antigo esperava o checksum presente. A correção (já aplicada na versão atual do script) ajusta a verificação de tamanho para aceitar 33 ou 34 bytes (com checksum removido) ou 37/38 bytes (com checksum presente), garantindo compatibilidade com todas as versões da lib base58.
Passo 4 (opcional): Use as funções individualmente no seu código
O script foi projetado para ser importado como módulo. Você pode usar as funções principais em seus próprios scripts:
Esse passo é útil se você está construindo uma ferramenta maior, como um gerador de carteiras, um verificador de chaves ou um script de auditoria. Note que o parâmetro compress=True gera WIF comprimido (com sufixo 0x01), que é o padrão da maioria das carteiras modernas.
Análise do código: funções principais
priv_to_wif e wif_to_priv: conversão entre hex e WIF
Essas duas funções são simétricas. priv_to_wif() pega uma string hex de 64 caracteres, adiciona o prefixo 0x80 (mainnet), o sufixo 0x01 se comprimido, e codifica tudo em base58check. A biblioteca base58 cuida do checksum de 4 bytes (duplo SHA256) automaticamente.
O caminho inverso, wif_to_priv(), decodifica o base58check, remove prefixo e sufixo, e retorna apenas os 32 bytes da chave em hex. A correção que aplicamos aqui no @CanalQb foi crucial para compatibilidade: diferentes versões da lib base58 tratam o checksum de forma diferente (algumas removem, outras mantêm), e o código agora lida com ambas as situações.
coincurve_pub_compressed: chave pública a partir da privada
Esta função tenta usar a biblioteca coincurve (binding C otimizada) para derivar a chave pública comprimida. Se falhar, ativa o fallback _python_pub_compressed(), que implementa a multiplicação escalar na curva secp256k1 inteiramente em Python puro, usando o algoritmo de duplicação-e-soma (double-and-add) sobre as coordenadas do ponto G da curva.
O fallback em Python puro é lento — leva alguns segundos por chave — mas não depende de nenhuma biblioteca externa além do próprio Python. Para uma única verificação ocasional, é suficiente. Para processamento em lote, a DLL ou o coincurve são muito mais rápidos.
verify_wif: verificação completa de um WIF
Esta função amarra todo o fluxo: decodifica o WIF, deriva a chave pública, calcula o hash160, gera o endereço Bitcoin e retorna um dicionário completo com todos os dados. Se um endereço esperado for fornecido, ela compara e retorna um campo address_match booleano.
O dicionário de retorno inclui: wif, private_key_hex, public_key_compressed, hash160, address, valid e dll_used. Isso permite que você use o resultado em programas maiores sem precisar reprocessar nada.
O que podemos aprimorar no script?
O script atual é funcional e robusto, mas há várias melhorias possíveis para deixá-lo ainda mais útil:
1. Suporte a endereços SegWit e Bech32
Atualmente o script gera apenas endereços Legacy (P2PKH) começando com 1. Adicionar suporte a P2SH-P2WPKH (endereços 3) e Bech32 (endereços bc1) aumentaria muito a utilidade prática, já que a maioria das carteiras modernas usa SegWit.
2. Modo de varredura em lote com a DLL
A DLL expõe a função privatekey_loop_h160, que é otimizada para processar múltiplas chaves rapidamente. O script atual não usa essa função — seria um ganho enorme de performance implementar um loop que passe uma faixa de chaves privadas diretamente para a DLL, em vez de chamar a função de derivação uma vez por chave.
3. Exportação para CSV
Seria útil adicionar uma função que exporte os resultados da verificação em lote para um arquivo CSV, com colunas para WIF, chave privada, chave pública, hash160 e endereço. Isso facilitaria a análise em planilhas e a integração com outras ferramentas.
4. Testes automatizados
O script não tem testes unitários. Adicionar testes com pytest para as funções principais, usando chaves conhecidas (como a chave 1, 2 e a chave aleatória do Bitcoin Testnet), tornaria o código mais confiável para integração em projetos maiores.
5. Suporte a Testnet e Regtest
O prefixo 0x80 está hardcoded para mainnet. Adicionar um parâmetro de rede que altere o prefixo para 0xEF (testnet) ou 0x6F (regtest) permitiria usar o script em ambientes de teste sem risco de perder fundos reais.
6. Otimização do fallback Python puro
A implementação _python_pub_compressed() é didática mas lenta. Dá para otimizar usando janelas de janelas (window method) ou pré-computação de pontos para acelerar a multiplicação escalar em Python puro — útil para ambientes sem coincurve nem DLL.
Perguntas Frequentes (FAQ)
O que é WIF e por que usar em vez de hex bruto?
Preciso da DLL IceSecp256k1 para usar o script?
O erro "KeyError: 'address'" foi corrigido permanentemente?
wif_to_priv() verificava len(decoded) in (37, 38) para determinar se o WIF era válido, mas diferentes versões da biblioteca base58 se comportam de forma diferente: algumas removem o checksum de 4 bytes na decodificação (resultando em 33 ou 34 bytes), outras mantêm (resultando em 37 ou 38 bytes). A correção adicionou uma verificação que detecta qual versão está em uso e ajusta o tratamento adequadamente, tornando o script compatível com todas as versões da lib base58 sem exigir instalação de uma versão específica.
O script funciona no Linux ou macOS?
ice_secp256k1.dll é uma biblioteca compilada para Windows (formato PE). No entanto, todas as funções que não dependem da DLL — priv_to_wif, wif_to_priv, hashlib_hash160, coincurve_pub_compressed e o fallback Python puro — funcionam em qualquer sistema operacional onde o Python rode. Para usar em Linux ou macOS, basta remover ou condicionar a parte de carregamento da DLL e confiar no coincurve ou no fallback Python. O coincurve, inclusive, tem versões nativas para Linux e macOS.
Como verificar se um WIF corresponde a um endereço específico?
verify_wif(wif, expected_address) passando o WIF e o endereço como parâmetros. A função decodifica o WIF, deriva a chave pública, calcula o hash160, gera o endereço Bitcoin e compara com o endereço fornecido. O resultado inclui o campo address_match (True ou False) e o campo valid (True se a comparação for bem-sucedida ou se nenhum endereço foi fornecido). Para verificar múltiplos pares de uma vez, use batch_verify_wifs(lista_wifs, lista_enderecos), que itera sobre os pares e retorna uma lista de resultados.
Referências e links úteis
- BIP32 — Hierarchical Deterministic Wallets
- Bitcoin Wiki — Wallet Import Format
- Thread original IceSecp256k1 no Bitcointalk
- Base58 — Python library
- Coincurve — Python bindings para libsecp256k1
- Outros scripts Python sobre Bitcoin no @CanalQb
- Criptografia secp256k1 no @CanalQb
- Ferramentas Bitcoin no @CanalQb
Gostou do conteúdo?
Inscreva-se no @CanalQb no YouTube para mais tutoriais sobre Bitcoin, criptografia, automação e ferramentas práticas.
Feito com Master Rules Claude v9.0
Nota Jurídica: Este conteúdo pode estar sujeito a diferentes leis de privacidade dependendo da sua jurisdição. Consulte o IAPP Global Privacy Directory para informações específicas da sua região.
