AnchorPy

AnchorPy genera clientes de Python a partir de IDLs de Anchor para que los backends y bots puedan llamar a programas en la cadena con constructores de instrucciones tipados. Se dirige a la semántica de IDL de Anchor 0.32.1 y se ejecuta sobre solders + solana-py contra el RPC de Agave 4.1.1.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

pip install anchorpy
 
from anchorpy import Program, Provider, Wallet
from solana.rpc.async_api import AsyncClient
 
PROGRAM_ID = "<TU_PUBKEY_DEL_PROGRAMA>"
 
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

Cuándo recurrir a esto:

Los servicios de Python deben invocar instrucciones de programas de Anchor 0.32.1.
Ya publicas una IDL de Anchor desde anchor build.
Los bots necesitan resolución de cuentas tipada en lugar de datos de instrucciones empaquetados manualmente.
Los scripts de investigación llaman a vistas de programas sin un frontend de TypeScript.

Ejemplo de trabajo

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)
 
        # Ejemplo: obtener una cuenta definida en la IDL
        # state = await program.account["MyAccount"].fetch(pda)
 
        # Ejemplo: enviar una instrucción
        # sig = await program.rpc["initialize"](ctx=..., signer=wallet.payer)
 
        print("Programa cargado:", program.program_id)
 
asyncio.run(main())

Lo que esto demuestra:

La JSON de la IDL se carga explícitamente para una generación de cliente reproducible.
Provider acopla el cliente RPC, la billetera y las opciones de transacción predeterminadas.
Program.at resuelve el ID del programa y adjunta metadatos de la IDL.
Los espacios de nombres de cuentas y RPC reflejan los clientes de TypeScript de Anchor.

Inmersión Profunda

Cómo funciona

anchor build de Anchor emite target/idl/<program>.json que coincide con anchor-lang 0.32.1.
AnchorPy analiza la IDL en tipos de Python y codificadores de instrucciones (diseño Borsh).
Wallet.local() lee ANCHOR_WALLET o ~/.config/solana/id.json como la cadena de herramientas TS.
Las transacciones se construyen con tipos solders y se envían a través de solana-py async RPC.

AnchorPy vs Cliente TypeScript

Preocupación	AnchorPy	`@coral-xyz/anchor` TS
Fuente de IDL	Misma JSON de Anchor 0.32.1	Misma
Entorno de ejecución	Servicios asyncio de Python	Navegador / Node
Tipos	Stubs de Python generados	TS generado
Mejor para	Bots, disparadores ETL, backends	Frontends de dApp

Notas de Python

# Fijar la IDL en el repositorio - regenerar en CI cuando cambie el programa
# anchor build && cp target/idl/my_program.json clients/python/
 
# Usar keypair explícito en producción
from solders.keypair import Keypair
from anchorpy import Wallet
 
secret = Keypair.from_bytes(bytes(json.load(open("bot.json"))))
wallet = Wallet(secret)
 
# Obtener múltiples cuentas concurrentemente
# accounts = await program.account["Position"].all()

Trampas

Desfase de IDL - el programa desplegado se actualiza sin refrescar la IDL, lo que rompe los codificadores. Solución: versionar la IDL junto con el hash binario del programa.
ID de programa de clúster incorrecta - las ID de devnet vs mainnet difieren. Solución: tabla de configuración por entorno.
Falta de firmante en llamadas rpc - las cuentas de Anchor necesitan firmantes explícitos. Solución: pasar ctx con cuentas Signer.
RPC bloqueante en código asíncrono - usar AsyncClient en todas partes. Solución: no usar Client síncrono dentro de bucles asyncio.
Asumir que AnchorPy despliega programas - es solo para clientes. Solución: usar Anchor CLI 0.32.1 / Solana CLI 3.0.10 para el despliegue.

Alternativas

Alternativa	Usar cuando	No usar cuando
`Instruction` empaquetada manualmente	Conjunto de instrucciones pequeño y estable	Superficie de IDL grande
`@solana/kit` + Codama TS	Frontend + tipos compartidos	Equipo solo de Python
Cliente Rust `declare_program!`	Servicios Rust fuera de la cadena	Pila de Python
CPI crudo desde otro programa	Composición en la cadena	Automatización fuera de la cadena

Preguntas Frecuentes

¿AnchorPy soporta Anchor 0.32.1?

Sí - usar IDLs generadas por Anchor CLI 0.32.1 / anchor-lang 0.32.1.

¿Cómo genero tipos de Python?

Usar la CLI anchorpy para la generación de código a partir de la IDL cuando quieras stubs verificados; Program.at también funciona dinámicamente.

¿Puedo llamar a programas que no son de Anchor?

No a través de ayudantes de IDL - construir instrucciones crudas con solders en su lugar.

Derivación de PDA?

AnchorPy expone ayudantes de semillas program_id alineados con las convenciones de Anchor.

Eventos y logs?

Analizar logs de transacciones o usar analizadores de eventos de IDL donde estén disponibles.

Pruebas?

Apuntar el proveedor a un validador local o a una bifurcación de Surfpool 0.12.0.

¿Múltiples programas?

Instanciar un Program por ID de programa / par de IDL.

¿Error al decodificar?

Mapear códigos de error personalizados usando la tabla de errores de la IDL - reflejar los patrones del cliente TS.

¿Claves de Mainnet?

Usar envoltorios de hardware o HSM en la nube alrededor de Wallet - nunca confirmar secretos.

¿Funciona con Token-2022?

Sí, si tu programa Anchor y tu IDL incluyen esos tipos de cuenta.

Relacionado

Conceptos básicos de Python para Solana - introducción a la sección
Construcción de transacciones en Python - ensamblaje de transacciones crudas
La IDL de Anchor - formato de IDL
Generación de clientes TS - ruta TS paralela

Versiones de la pila: Esta página se escribió 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, y LiteSVM 0.6.x.

AnchorPy

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

pip install anchorpy
 
from anchorpy import Program, Provider, Wallet
from solana.rpc.async_api import AsyncClient
 
PROGRAM_ID = "<TU_PUBKEY_DEL_PROGRAMA>"
 
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

Cuándo recurrir a esto:

Los servicios de Python deben invocar instrucciones de programas de Anchor 0.32.1.
Ya publicas una IDL de Anchor desde anchor build.
Los bots necesitan resolución de cuentas tipada en lugar de datos de instrucciones empaquetados manualmente.
Los scripts de investigación llaman a vistas de programas sin un frontend de TypeScript.

Ejemplo de trabajo

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)
 
        # Ejemplo: obtener una cuenta definida en la IDL
        # state = await program.account["MyAccount"].fetch(pda)
 
        # Ejemplo: enviar una instrucción
        # sig = await program.rpc["initialize"](ctx=..., signer=wallet.payer)
 
        print("Programa cargado:", program.program_id)
 
asyncio.run(main())

Lo que esto demuestra:

La JSON de la IDL se carga explícitamente para una generación de cliente reproducible.
Provider acopla el cliente RPC, la billetera y las opciones de transacción predeterminadas.
Program.at resuelve el ID del programa y adjunta metadatos de la IDL.
Los espacios de nombres de cuentas y RPC reflejan los clientes de TypeScript de Anchor.

Inmersión Profunda

Cómo funciona

anchor build de Anchor emite target/idl/<program>.json que coincide con anchor-lang 0.32.1.
AnchorPy analiza la IDL en tipos de Python y codificadores de instrucciones (diseño Borsh).
Wallet.local() lee ANCHOR_WALLET o ~/.config/solana/id.json como la cadena de herramientas TS.
Las transacciones se construyen con tipos solders y se envían a través de solana-py async RPC.

AnchorPy vs Cliente TypeScript

Preocupación	AnchorPy	`@coral-xyz/anchor` TS
Fuente de IDL	Misma JSON de Anchor 0.32.1	Misma
Entorno de ejecución	Servicios asyncio de Python	Navegador / Node
Tipos	Stubs de Python generados	TS generado
Mejor para	Bots, disparadores ETL, backends	Frontends de dApp

Notas de Python

# Fijar la IDL en el repositorio - regenerar en CI cuando cambie el programa
# anchor build && cp target/idl/my_program.json clients/python/
 
# Usar keypair explícito en producción
from solders.keypair import Keypair
from anchorpy import Wallet
 
secret = Keypair.from_bytes(bytes(json.load(open("bot.json"))))
wallet = Wallet(secret)
 
# Obtener múltiples cuentas concurrentemente
# accounts = await program.account["Position"].all()

Trampas

Desfase de IDL - el programa desplegado se actualiza sin refrescar la IDL, lo que rompe los codificadores. Solución: versionar la IDL junto con el hash binario del programa.
ID de programa de clúster incorrecta - las ID de devnet vs mainnet difieren. Solución: tabla de configuración por entorno.
Falta de firmante en llamadas rpc - las cuentas de Anchor necesitan firmantes explícitos. Solución: pasar ctx con cuentas Signer.
RPC bloqueante en código asíncrono - usar AsyncClient en todas partes. Solución: no usar Client síncrono dentro de bucles asyncio.
Asumir que AnchorPy despliega programas - es solo para clientes. Solución: usar Anchor CLI 0.32.1 / Solana CLI 3.0.10 para el despliegue.

Alternativas

Alternativa	Usar cuando	No usar cuando
`Instruction` empaquetada manualmente	Conjunto de instrucciones pequeño y estable	Superficie de IDL grande
`@solana/kit` + Codama TS	Frontend + tipos compartidos	Equipo solo de Python
Cliente Rust `declare_program!`	Servicios Rust fuera de la cadena	Pila de Python
CPI crudo desde otro programa	Composición en la cadena	Automatización fuera de la cadena

Preguntas Frecuentes

¿AnchorPy soporta Anchor 0.32.1?

Sí - usar IDLs generadas por Anchor CLI 0.32.1 / anchor-lang 0.32.1.

¿Cómo genero tipos de Python?

Usar la CLI anchorpy para la generación de código a partir de la IDL cuando quieras stubs verificados; Program.at también funciona dinámicamente.

¿Puedo llamar a programas que no son de Anchor?

No a través de ayudantes de IDL - construir instrucciones crudas con solders en su lugar.

Derivación de PDA?

AnchorPy expone ayudantes de semillas program_id alineados con las convenciones de Anchor.

Eventos y logs?

Analizar logs de transacciones o usar analizadores de eventos de IDL donde estén disponibles.

Pruebas?

Apuntar el proveedor a un validador local o a una bifurcación de Surfpool 0.12.0.

¿Múltiples programas?

Instanciar un Program por ID de programa / par de IDL.

¿Error al decodificar?

Mapear códigos de error personalizados usando la tabla de errores de la IDL - reflejar los patrones del cliente TS.

¿Claves de Mainnet?

Usar envoltorios de hardware o HSM en la nube alrededor de Wallet - nunca confirmar secretos.

¿Funciona con Token-2022?

Sí, si tu programa Anchor y tu IDL incluyen esos tipos de cuenta.

Relacionado

Conceptos básicos de Python para Solana - introducción a la sección
Construcción de transacciones en Python - ensamblaje de transacciones crudas
La IDL de Anchor - formato de IDL
Generación de clientes TS - ruta TS paralela

Versiones de la pila: Esta página se escribió 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, y LiteSVM 0.6.x.

AnchorPy

Buscar en la documentación

AnchorPy