Solana Pay, Actions y Blinks
Solana Pay, Actions y Blinks son el stack de interacciones incrustables para Solana: formas de solicitar valor o firmas fuera de un shell de dApp personalizado completo.
Comparten una idea. Un cliente (billetera, proveedor de Blink o escáner QR) descubre una intención, opcionalmente obtiene una transacción creada por el servidor y pide al usuario que firme. Tú posees el endpoint HTTPS y las instrucciones; la billetera posee las claves y la pantalla de aprobación.
Esta página es el paraguas de la sección. Las páginas hermanas cubren URLs de pago, solicitudes de transacciones, el contrato HTTP de Actions, Blinks, implementación y verificación.
Resumen
- Solana Pay comienza como URLs orientadas al pago y flujos QR; las solicitudes de transacciones extienden eso a transacciones creadas por el servidor; Actions generaliza el patrón a una API estándar de metadatos + transacciones; Blinks empaqueta Actions como enlaces compartibles e incrustables.
- Por Qué Importa: La mayor parte del crecimiento de productos no es "abrir nuestra SPA y conectar". POS, facturas, CTAs sociales, votos de gobernanza y mints de un toque necesitan intenciones portátiles que cualquier billetera compatible pueda completar sin un nuevo esquema de deep-link por cliente.
- Conceptos Clave: solicitud de transferencia, solicitud de transacción, cuenta de referencia, Action GET/POST, metadatos de Action, Blink, desplegar (unfurl), CORS, transacción en el cable (wire transaction) base64, simulación, verificación de liquidación.
- Cuándo Usar: Checkout y donaciones, QR en persona, CTAs sociales o de campaña, botones ligeros en la cadena (votar, mintear, intercambiar), y cualquier flujo donde el comerciante o protocolo deba construir la transacción que el usuario firma.
- Limitaciones / Compensaciones: Cambias la experiencia de usuario completa dentro de la aplicación por alcance. El hosting, TLS, CORS, límites de tasa y resistencia al phishing se convierten en requisitos del producto. Los usuarios aún deben entender lo que firman; las billeteras y los clientes de Blink no pueden inventar confianza para un dominio malicioso.
- Temas Relacionados: Conceptos Básicos de Solana Pay, Solicitudes de Transacciones, Actions (la especificación), Blinks, Construir una Action, Seguridad y Verificación.
Fundamentos
Comienza con Solana Pay como la capa de pago.
Una solicitud de transferencia codifica el destinatario, la cantidad (y el mint SPL opcional), la etiqueta, el mensaje y las claves públicas de referencia opcionales en una URL que las billeteras entienden. Los comerciantes la renderizan como un QR para punto de venta o la comparten para checkout remoto. La billetera pre-rellena una transferencia; el usuario firma; la cadena liquida.
Las referencias impulsan la contabilidad. Una clave pública de referencia única por pedido permite a tu servidor observar RPC o websockets para una transacción coincidente y marcar la factura como pagada sin confiar solo en una devolución de llamada del navegador. La cantidad y el mint aún necesitan verificaciones del lado del servidor; una referencia coincidente es correlación, no prueba completa por sí sola.
Las solicitudes de transacciones elevan el mismo patrón "la billetera obtiene la intención de HTTPS" más allá de las transferencias simples. El endpoint del comerciante recibe la cuenta del cliente, construye una transacción versionada con esa cuenta como pagador de tarifas o firmante requerido, y devuelve una transacción serializada que la billetera puede previsualizar y firmar. El checkout puede intercambiar, mintear o llamar a un programa personalizado en una sola aprobación.
Solana Actions generaliza los endpoints que producen transacciones más allá del pago comercial clásico. La especificación de Actions define cómo los clientes descubren metadatos legibles por humanos (title, icon, description, label, y campos relacionados) y cómo obtienen una transacción codificada en base64 para una account conectada. Las billeteras, los portales de Blink y los desplegadores sociales hablan el mismo contrato.
Blinks (enlaces de blockchain) son la capa de distribución. Un Blink es una URL de Action presentada a través de un cliente o proxy compatible con Blink para que se despliegue en una tarjeta enriquecida: icono, copia y un botón que ejecuta el flujo POST de Action. La Action sigue siendo tu API HTTPS; el Blink es cómo los usuarios la encuentran y comparten en X, Discord, sitios asociados y superficies de Blink.
Este sitio construye código de cliente y servidor con @solana/kit 7.0.0, implementa programas bajo Agave 4.1.1 / Solana CLI 3.0.10, y a menudo compone instrucciones de programas de Anchor 0.32.1 en Rust 1.91.1. Los pagos y Actions son principalmente TypeScript y HTTP; los programas que invocas aún obedecen las reglas de cuenta y CU de Sealevel.
Mecánicas e Interacciones
Ruta de transferencia de Solana Pay
- El comerciante crea una URL de transferencia (
@solana/payencodeURLo campos construidos manualmente según la especificación de Pay). - El cliente escanea un QR o abre el enlace en una billetera.
- La billetera muestra la cantidad, etiqueta y destinatario; el usuario firma una transferencia (SOL o SPL).
- El comerciante monitorea la referencia (y la cantidad) a través de RPC hasta que se confirme, y luego cumple con el pedido.
Usa solicitudes de transferencia cuando la acción sea "enviar N de activo X a destinatario Y" sin composición de múltiples instrucciones en el servidor.
Ruta de solicitud de transacción
- La billetera abre
https://merchant.example/pay?...(o la forma de solicitud de transacción que tu billetera soporte). - El endpoint valida los parámetros, carga un blockhash, construye instrucciones para la cuenta conectada, serializa una transacción en el cable (sin firmar, o parcialmente firmada solo cuando intencionalmente co-firmas).
- La billetera simula y muestra la vista previa; el usuario firma; la red ejecuta.
- El comerciante verifica la liquidación a través de referencias, saldos, eventos del programa o huellas digitales de instrucciones.
Las solicitudes de transacciones y Actions se superponen mucho. Muchos productos implementan Actions (o manejadores compatibles con Actions) y tratan las solicitudes de transacciones de Solana Pay como el ancestro con sabor a pago del mismo patrón.
Actions: GET metadatos, POST transacción
| Método | Rol |
|---|---|
OPTIONS | Preflight CORS para clientes de navegador y extensiones |
GET | Metadatos de solo lectura para tarjetas y desplegadores |
POST | Acepta { account } (y campos de cuerpo opcionales), devuelve { transaction } base64 |
GET no debe mutar estado. Es presentación cacheable: icono HTTPS, título, descripción, etiqueta del botón, entradas opcionales. POST es dinámico por usuario: inserta su pubkey como firmante/pagador de tarifas, establece un blockhash fresco, adjunta solo las cuentas e instrucciones requeridas para esa CTA.
Los clientes muestran tus metadatos, luego hacen POST con la dirección de la billetera conectada. Tu servidor devuelve una transacción que la billetera firma. Las devoluciones de llamada opcionales informan la finalización; nunca las trates como prueba única sin confirmación RPC.
Blinks: Actions compartibles
Un cliente Blink toma una URL de Action (a menudo a través de una consulta de proveedor como ?action=https://...) y:
- Obtiene los metadatos GET de Action para la tarjeta desplegable.
- Renderiza el icono, título y CTA en la superficie del host.
- Ejecuta la misma ruta POST → firmar → enviar que un cliente nativo de Actions.
Tu trabajo sigue siendo el endpoint de Action: CORS, TLS, metadatos precisos y transacciones de mínimo privilegio. Los proveedores de Blink y las billeteras agregan listas de permitidos, advertencias y distintivos; estos complementan la construcción segura, no la reemplazan.
Construir una Action (bucle de implementación)
Las Actions de producción suelen vivir como manejadores de rutas (por ejemplo, Next.js App Router bajo app/api/actions/...):
- Estructura GET, POST y OPTIONS con encabezados CORS de Actions.
- GET devuelve activos de marca estables en tu dominio.
- POST analiza
account, construye instrucciones (constructores de Kit o ayudantes de Codama/IDL para programas de Anchor), establece el pagador de tarifas y el blockhash, serializa base64. - Simula antes de devolver cuando el fallo desperdiciaría atención u ocultaría configuración rota.
- Observa el costo RPC, errores y firmas en el lado del servidor con límites de tasa.
IDs de programa y URLs RPC separadas para devnet y mainnet-beta. Una Action de mainnet apuntando a un ID de programa de devnet es un error común de lanzamiento.
Seguridad y verificación como mecánicas de primera clase
- Transporte: Solo HTTPS para URLs de Action, iconos y endpoints de Pay.
- Origen: los usuarios deben ver el dominio real; los sitios clonados roban iconos y etiquetas.
- Contenido de la transacción: mínimo privilegio; sin
SetAuthorityinesperados, aprobaciones ilimitadas o transferencias no relacionadas. - Simulación: las billeteras simulan; tu manejador POST también debería hacerlo para rutas conocidas como buenas.
- Liquidación: para comercio, confirma en la cadena con referencia + cantidad (y mint) antes del cumplimiento.
- Abuso: limita la tasa de POST, limita el patrocinio de tarifas y evita endpoints abiertos que construyan drenajes elegidos por el atacante bajo tu marca.
La verificación del lado de Blink también cubre registros de clientes, verificaciones de dominio e integridad de despliegue (el icono sigue en tu host). Trata las cachés de despliegue como propensas a desactualizarse; versiona las URLs de activos estáticos cuando cambie la marca.
Consideraciones Avanzadas y Aplicaciones
Elegir la capa correcta
| Necesidad | Preferir | Evitar cuando |
|---|---|---|
| Pago de SOL/SPL en persona | Transferencia de Solana Pay + QR | Necesitas composición de múltiples instrucciones |
| Checkout con swap/mint/ix personalizado | Solicitud de transacción o Action | La URL de transferencia simple es suficiente |
| CTA social compartible | Action + Blink | Solo POS fuera de línea |
| Experiencia de producto completa multi-pantalla | dApp con adaptador de billetera | Solo necesitas un CTA de un toque |
| Movimiento de dinero de alto riesgo | Programa de depósito en garantía + liquidación verificada | Confiar solo en eventos "pagados" del cliente |
Muchos equipos ejecutan ambos: Solana Pay o Actions para adquisición y POS, y una dApp completa para usuarios avanzados. La habilidad compartida es construir transacciones seguras para una clave pública de cliente.
Patrones de producto
- Facturas y donaciones: solicitudes de transferencia con referencias únicas y etiquetas cortas.
- Comercio con inventario: solicitud de transacción o Action que mintea un recibo, quema un PDA de cupón o mueve fondos de bóveda bajo reglas del programa.
- Gobernanza y comunidad: CTAs de votar, reclamar o apostar como Blinks.
- Puntos de entrada DeFi: un swap o depósito ix configurado con slippage explícito; nunca ocultes aprobaciones ilimitadas detrás de una etiqueta "Reclamar".
- Patrocinio de tarifas: firma parcial opcional para UX sin gas, con límites duros, autenticación y monitoreo para que el patrocinio no pueda ser drenado.
Cliente, stack y operaciones
Usa @solana/kit 7.0.0 para RPC, direcciones, construcción de mensajes y codificación en el cable. Prefiere transacciones versionadas y simulación. Para programas Anchor 0.32.1, genera constructores tipados (Codama/IDL) para que las metadatos de cuenta permanezcan correctos a medida que los programas evolucionan.
Una Action solo entrega una transacción que el usuario firma; no relaja las comprobaciones de Sealevel, PDAs, reglas de tokens o límites de CU en los programas que llamas.
Operacionalmente: caché CDN para metadatos GET estables, nunca caches respuestas de transacciones POST entre usuarios o tiempos; rota blockhashes en cada POST; registra latencia y fallos sin secretos en las cadenas de consulta; si se lanza una Action defectuosa, desconecta la ruta y rota los activos cuando aparezcan clones de phishing.
Conceptos Erróneos Comunes
- "Solana Pay es solo códigos QR para SOL." Pay cubre flujos de transferencia y solicitud de transacciones, incluyendo cantidades SPL y APIs de comerciantes más ricas.
- "Actions reemplazan a las billeteras." Actions alimentan billeteras y clientes Blink; el usuario todavía firma en un contexto de billetera.
- "Un Blink es un programa en cadena separado." Un Blink es distribución y experiencia de usuario de despliegue alrededor de una URL de Action; el estado de la cadena cambia solo cuando la transacción firmada aterriza.
- "La simulación verde significa que el comerciante puede marcar como pagado." La simulación no es liquidación. Confirma firmas y saldos en tu nivel de compromiso requerido.
- "GET puede crear los efectos secundarios de la factura." GET es para metadatos. Crear pedidos o quemar nonces en GET invita a las cachés y rastreadores a corromper el estado.
- "CORS comodín siempre está bien." Los clientes de especificación necesitan CORS, pero los endpoints sensibles o patrocinados aún necesitan límites de tasa, autenticación y monitoreo de abuso.
- "El icono y el título prueban la legitimidad." Los clones de phishing copian ambos. La inspección del dominio y la verificación del cliente importan más que la marca sola.
- "Una URL de Action puede significar de forma segura cualquier cosa que el cuerpo solicite." Prefiere plantillas fijas y auditadas por ruta (
/vote,/mint,/pay) sobre constructores abiertos. - "Las solicitudes de transacciones y Actions no están relacionadas." Comparten transacciones creadas por el servidor; Actions es el estándar más amplio y listo para redes sociales.
- "El patrocinio de tarifas es crecimiento gratuito." El patrocinio sin límites es un vector de drenaje. Presupuesta, autentica y mide su uso.
Preguntas Frecuentes
¿Qué problema resuelven juntos Solana Pay, Actions y Blinks?
Permiten a los usuarios completar intenciones en la cadena (pagar, votar, mintear, intercambiar) desde enlaces, códigos QR y superficies sociales sin forzar cada interacción a través de una dApp personalizada de múltiples páginas.
¿Cuándo debería usar una solicitud de transferencia simple en lugar de una Action?
Cuando la intención es un pago simple de SOL o SPL a un destinatario y cantidad conocidos, y no necesitas lógica de múltiples instrucciones o CTAs de despliegue social. Las URLs de transferencia son la superficie de ataque más pequeña.
¿Qué es una cuenta de referencia en Solana Pay?
Una clave pública incluida en el pago para que tu backend pueda encontrar la transacción en cadena coincidente y vincularla a un ID de pedido. Genera una referencia única por sesión de checkout y verifica la cantidad en el servidor.
¿Cómo difieren las solicitudes de transacciones de las solicitudes de transferencia?
Las solicitudes de transferencia describen un pago que la billetera puede construir localmente. Las solicitudes de transacciones acceden a tu API HTTPS para que el servidor devuelva una transacción completa (swap, mint, programa personalizado, etc.) para que el cliente la firme.
¿Qué debe implementar un endpoint de Actions?
Como mínimo: CORS/OPTIONS según lo requieran los clientes, metadatos GET para visualización humana, y POST que acepta la cuenta del usuario y devuelve una transacción base64. Sigue los campos actuales de la especificación de Actions que soportan las billeteras de tu público objetivo.
¿Es un Blink una API separada de una Action?
Generalmente no. La Action es la API. Un Blink es cómo se vincula, despliega y presenta esa Action dentro de aplicaciones y proveedores compatibles con Blink.
¿Por qué los iconos de Action necesitan HTTPS en mi dominio?
Los clientes cargan iconos para tarjetas y despliegues. El hotlinking o los activos HTTP rompen la renderización, debilitan las señales de confianza y crean riesgo en la cadena de suministro si un tercero cambia la imagen.
¿Puedo construir Actions con @solana/kit 7.0.0?
Sí. Kit es el stack de TypeScript que este sitio fija para RPC, direcciones y construcción de mensajes de transacción en manejadores POST.
¿Necesito Anchor para lanzar una Action?
No. Actions son HTTP más cualquier transacción válida de Solana. Anchor 0.32.1 ayuda cuando tu CTA llama a un programa de Anchor y quieres constructores dirigidos por IDL; los programas nativos funcionan igual a nivel de cable.
¿Cómo deben los comerciantes verificar que un pago fue exitoso?
Confirma a través de RPC (y preferiblemente websockets o un indexador) una transacción que coincida con las reglas de referencia, cantidad, mint y destinatario en tu nivel de compromiso. No confíes solo en devoluciones de llamada del lado del cliente.
¿Cuáles son los errores más arriesgados en los manejadores POST de Action?
Transacciones con privilegios excesivos, omisión de simulación, patrocinio de tarifas sin límites, límites de tasa faltantes y IDs de programa de clúster incorrectos en producción.
¿Cómo manejan Blinks la confianza para dominios desconocidos?
Los clientes pueden advertir, permitir o mostrar distintivos de verificación. Asume que los usuarios pueden ignorar las advertencias; mantén las transacciones mínimas y los dominios consistentes con tu marca.
¿Se deben almacenar en caché los metadatos GET en la CDN?
Sí, para marca estable, con TTLs cortos si los títulos cambian a menudo. Nunca almacenes en caché las respuestas de transacciones POST entre usuarios o tiempos.
¿Qué debería leer a continuación en esta sección?
Comienza con Conceptos Básicos de Solana Pay y Solicitudes de Transacciones, luego Actions (la especificación) y Blinks. Implementa con Construir una Action y fortalece con Seguridad y Verificación.
Relacionados
- Conceptos Básicos de Solana Pay - URLs de transferencia, flujos QR, referencias y metadatos de pago
- Solicitudes de Transacciones - transacciones creadas por el servidor para checkout más allá de transferencias simples
- Actions (la especificación) - contrato de metadatos GET y transacción POST
- Blinks - enlaces de Action compartibles e incrustables y experiencia de usuario de despliegue
- Construir una Action - endpoints, CORS, metadatos y flujo de firma de extremo a extremo
- Seguridad y Verificación - confianza, phishing, simulación y verificaciones de liquidación
Versiones del Stack: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1, y @solana/kit 7.0.0.