PeriploPeriplo
Launch App

Docs

Documentación

La librería cliente periplo: qué hace hoy, con honestidad, y cómo instalarla.

Última actualización: · npm

Esta sección hoy cubre Introducción e Instalación. Los inicios rápidos y la referencia completa de la API necesitan un facilitador que soporte upto de extremo a extremo, algo que el despliegue público todavía no anuncia; no se publican hasta poder mostrar salida real y verificada.

Introducción

periplo es una librería cliente en TypeScript para pagos x402 en Stellar. Está construida alrededor de upto: en vez de pagar un precio fijo, quien compra firma un techo de gasto una sola vez, y un facilitador liquida después solo el monto realmente usado. El techo nunca cambia; lo único que cambia es el uso real.

techo firmado:   [████████████████████████████████] 0.10 USDC
usado de verdad: [████████░░░░░░░░░░░░░░░░░░░░░░░░] 0.05 USDC liquidado, 0.05 USDC devuelto

Esa es la forma real de la primera liquidación upto en stellar:testnet: quien compró firmó un techo de 0.10 USDC, quien vendió midió 0.05 USDC de uso real, y el contrato UptoSettlement liquidó 0.05 USDC al vendedor y devolvió los otros 0.05 USDC al comprador en la misma transacción. Puedes comprobarlo tú en Stellar Expert, o verlo en vivo en la página del demo.

Qué te da periplo

  • Lado comprador: firmar un techo upto (createUptoStellarPayer) o pagar un precio fijo exact (createExactStellarPayer), y luego pedir un recurso pagado con reintento incluido (payAndFetch, discoverPayAndFetch).
  • Lado vendedor: declarar los metadatos de descubrimiento de un recurso pagado (definePaidResource), anunciar un techo upto (buildUptoRequirements), y liquidar el uso real una vez que se conoce (settleUptoUsage).

Ningún lado reimplementa la verificación ni la liquidación de pagos: cada llamada pasa por HTTPFacilitatorClient, el mismo cliente publicado de @x402/core que entiende cualquier facilitador x402.

Qué funciona hoy, con honestidad

  • exact está vivo en el facilitador público en periplo-testnet.fly.dev (stellar:testnet), usado en todo el demo completo y en la evidencia de conformidad.
  • upto liquida contra un contrato Soroban UptoSettlement ya desplegado, pero necesita un facilitador configurado con la dirección de ese contrato. El propio GET /supported del facilitador público hoy no anuncia upto, solo exact; compruébalo tú mismo antes de asumir lo contrario. Para liquidar de extremo a extremo hace falta correr tu propio facilitador (auto-facilitación) o usar uno que sí soporte upto.
  • Todo aquí es solo stellar:testnet. Periplo no opera en mainnet todavía, y createUptoStellarPayer rechaza con UptoMainnetNotSupportedError cualquier otra red, incluyendo stellar:pubnet.

Requisitos

Node.js 22 o más nuevo (el campo engines.node del paquete). Ninguna otra dependencia de entorno además de lo que instala npm.

Instalación

npm i periplo

Verificado desde una carpeta limpia fuera de este repositorio: npm install periplo, luego npm install --save-dev typescript @types/node, se resuelve e instala sin errores, y npx tsc tipa sin errores un archivo que importa de periplo, siempre que compilerOptions tenga "types": ["node"] (los propios tipos del paquete referencian Buffer, a través de @x402/core).

Requisitos

  • Node.js 22 o más nuevo. Declarado en el propio campo engines.node del paquete; npm avisa con una versión de Node más vieja.
  • @types/node, como dependencia de desarrollo, si usas TypeScript. Sin ella, tsc falla con Cannot find name 'Buffer' dentro de las propias declaraciones de tipos de @x402/core, por las que periplo reexporta.
  • Red: todo en este paquete que habla con Stellar apunta a stellar:testnet. No hay soporte de mainnet; ver Introducción.

Verificar la instalación

Esto comprueba que los tipos de error del paquete funcionan de verdad, sin necesitar red ni credenciales:

import { createUptoStellarPayer, UptoMainnetNotSupportedError } from "periplo";

try {
  createUptoStellarPayer("S" + "A".repeat(55), "stellar:pubnet", {
    facilitatorBaseUrl: "https://periplo-testnet.fly.dev",
    maxSpendPerAuthorization: 1_000_000n,
  });
} catch (error) {
  console.log(error instanceof UptoMainnetNotSupportedError, (error as Error).message);
}

Salida real, de ese script exacto, corrido contra el paquete instalado desde su tarball publicado:

true upto is only supported on stellar:testnet today; stellar:pubnet (including any pubnet/mainnet network) is not yet supported.

Eso confirma dos cosas a la vez: el paquete se instaló y sus tipos resuelven, y upto de verdad rechaza cualquier red que no sea stellar:testnet, en vez de hacer silenciosamente lo incorrecto.