AnchorPy

AnchorPy gera clientes Python a partir de IDLs Anchor para que backends e bots chamem programas on-chain com builders de instrução tipados. Mira semânticas de IDL Anchor 0.32.1 e roda sobre solders + solana-py contra RPC Agave 4.1.1.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

pip install anchorpy
 
from anchorpy import Program, Provider, Wallet
from solana.rpc.async_api import AsyncClient
 
PROGRAM_ID = "<YOUR_PROGRAM_PUBKEY>"
 
async def load_program():
    client = AsyncClient("https://api.devnet.solana.com")
    wallet = Wallet.local()
    provider = Provider(client, wallet)
    program = await Program.at(PROGRAM_ID, provider)
    return program

Quando usar isso:

• Serviços Python devem invocar instruções de programa Anchor 0.32.1.
• Você já publica IDL Anchor de anchor build.
• Bots precisam de resolução tipada de contas em vez de empacotar dados de instrução à mão.
• Scripts de pesquisa chamam views de programa sem frontend TypeScript.

Exemplo de Trabalho

import asyncio
import json
from pathlib import Path
 
from anchorpy import Program, Provider, Wallet, Idl
from solana.rpc.async_api import AsyncClient
 
PROGRAM_ID = "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS"
RPC = "https://api.devnet.solana.com"
 
async def main():
    idl_path = Path("target/idl/my_program.json")
    idl = Idl.from_json(idl_path.read_text())
 
    async with AsyncClient(RPC) as client:
        wallet = Wallet.local()
        provider = Provider(client, wallet, opts={"preflight_commitment": "confirmed"})
        program = await Program.at(PROGRAM_ID, provider, idl=idl)
 
        # Exemplo: buscar conta definida no IDL
        # state = await program.account["MyAccount"].fetch(pda)
 
        # Exemplo: enviar instrução
        # sig = await program.rpc["initialize"](ctx=..., signer=wallet.payer)
 
        print("Loaded program:", program.program_id)
 
asyncio.run(main())

O que isso demonstra:

• IDL JSON é carregado explicitamente para geração de cliente reproduzível.
• Provider acopla cliente RPC, carteira e opções padrão de transação.
• Program.at resolve program ID e anexa metadados IDL.
• Namespaces de conta e RPC espelham clientes TypeScript Anchor.

Deep Dive

Como Funciona

• anchor build emite target/idl/<program>.json correspondendo a anchor-lang 0.32.1.
• AnchorPy analisa IDL em tipos Python e encoders de instrução (layout Borsh).
• Wallet.local() lê ANCHOR_WALLET ou ~/.config/solana/id.json como toolchain TS.
• Transações são construídas com tipos solders e submetidas via RPC async solana-py.

AnchorPy vs Cliente TypeScript

Notas Python

# Fixe IDL no repo - regenere no CI quando programa mudar
# anchor build && cp target/idl/my_program.json clients/python/
 
# Use keypair explícito em produção
from solders.keypair import Keypair
from anchorpy import Wallet
 
secret = Keypair.from_bytes(bytes(json.load(open("bot.json"))))
wallet = Wallet(secret)
 
# Busque múltiplas contas concorrentemente
# accounts = await program.account["Position"].all()

Armadilhas

• Drift de IDL - programa atualizado sem refresh de IDL quebra encoders. Correção: versione IDL junto ao hash do binário do programa.
• Program ID de cluster errado - IDs devnet vs mainnet diferem. Correção: tabela de config por ambiente.
• Signer ausente em chamadas rpc - contas Anchor precisam signers explícitos. Correção: passe ctx com contas Signer.
• RPC bloqueante em código async - use AsyncClient em todo lugar. Correção: sem Client sync dentro de loops asyncio.
• Assumir que AnchorPy faz deploy - é apenas cliente. Correção: use Anchor CLI 0.32.1 / Solana CLI 3.0.10 para deploy.

Alternativas

FAQs

Relacionado

• Noções Básicas de Python para Solana - intro da seção
• Construindo Transações em Python - montagem de tx bruta
• O IDL Anchor - formato IDL
• Gerando Clientes TS - caminho TS paralelo

Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.