Crear saldo reclamable

Los saldos reclamables te permiten enviar pagos que el destinatario puede reclamar bajo condiciones específicas. Esto es útil para funciones similares a escrow, pagos condicionales o transferencias bloqueadas por tiempo.

Configuración

Para los siguientes ejemplos usaremos estas cuentas:

stellar network use testnet

stellar keys generate --fund alice

stellar keys generate bob --fund

stellar keys generate charlie --fund

Ejemplos básicos

Saldo reclamable incondicional

Crear un saldo reclamable que el destinatario pueda reclamar inmediatamente:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 50_000_000 \
  --asset native \
  --claimant bob

También puedes especificar explícitamente incondicional:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 50_000_000 \
  --asset native \
  --claimant 'bob:"unconditional"'

Múltiples reclamantes

Crear un saldo reclamable que pueda ser reclamado por cualquiera de varios destinatarios:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 75_000_000 \
  --asset native \
  --claimant bob \
  --claimant charlie

Predicados basados en tiempo

Antes de un tiempo absoluto

Crear un saldo reclamable que debe ser reclamado antes de una fecha específica:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 30_000_000 \
  --asset native \
  --claimant 'bob:{"before_absolute_time":"1735689599"}'

Antes de un tiempo relativo

Crear un saldo reclamable que debe reclamarse dentro de 1 hora (3600 segundos) desde su creación:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 25_000_000 \
  --asset native \
  --claimant 'bob:{"before_relative_time":"3600"}'

Predicados lógicos

Predicado Not

Crear un saldo reclamable que puede ser reclamado después de cierto tiempo (NO antes de un tiempo relativo):

stellar tx new create-claimable-balance \
  --source alice \
  --amount 40_000_000 \
  --asset native \
  --claimant 'bob:{"not":{"before_relative_time":"7200"}}'

Esto significa: "Puede ser reclamado, PERO NO antes de que hayan pasado 2 horas" (efectivamente: puede ser reclamado después de 2 horas).

Predicado And

Crear un saldo reclamable con múltiples condiciones que TODAS deben ser verdaderas:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 60_000_000 \
  --asset native \
  --claimant 'bob:{"and":[{"before_absolute_time":"1735689599"},{"not":{"before_relative_time":"86400"}}]}'

Esto significa: "Puede ser reclamado antes del 31 de diciembre de 2024 Y después de que haya pasado 1 día".

Predicado Or

Crear un saldo reclamable donde cualquiera de las condiciones puede ser verdadera:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 35_000_000 \
  --asset native \
  --claimant 'bob:{"or":[{"before_relative_time":"3600"},{"not":{"before_absolute_time":"1717200000"}}]}'

Esto significa: "Puede ser reclamado dentro de 1 hora O después del 1 de junio de 2024".

Ejemplos complejos

Reclamantes mixtos con diferentes predicados

Crear un saldo reclamable con múltiples reclamantes que tienen diferentes condiciones de reclamación:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 100_000_000 \
  --asset native \
  --claimant 'bob:{"before_relative_time":"3600"}' \
  --claimant 'charlie:{"not":{"before_relative_time":"86400"}}'

Esto crea un saldo donde:

• Bob puede reclamar dentro de 1 hora
• Charlie puede reclamar después de que haya pasado 1 día

Pago estilo escrow

Crear un escrow donde el destinatario tiene 30 días para reclamar, de lo contrario regresa al remitente:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 200_000_000 \
  --asset native \
  --claimant 'bob:{"before_relative_time":"2592000"}' \
  --claimant 'alice:{"not":{"before_relative_time":"2592000"}}'

Esto significa:

• Bob puede reclamar dentro de 30 días
• Alice puede recuperar después de 30 días si Bob no ha reclamado

Saldo reclamable de activo personalizado

Crear un saldo reclamable para un activo personalizado:

stellar tx new create-claimable-balance \
  --source alice \
  --amount 1000_000_000 \
  --asset USDC:GBUG7QTBTT47XVDVE6RZYWRUZBPLOIO57INE6LYZDMIXMMDCREQRUQKI \
  --claimant 'bob:{"before_absolute_time":"1735689599"}'

Comprendiendo los predicados

Nota: Los predicados deben ser JSON válido, por lo que debes usar comillas y escape adecuados.

Tipos de predicados

Tipo	Descripción	Ejemplo
unconditional	Puede ser reclamado en cualquier momento	"unconditional"
before_absolute_time	Debe reclamarse antes de una marca de tiempo específica	{"before_absolute_time":"1735689599"}
before_relative_time	Debe reclamarse dentro de X segundos desde la creación	{"before_relative_time":"3600"}
not	Niega otro predicado	{"not":{...}}
and	Ambos predicados deben ser verdaderos	{"and":[{...},{...}]}
or	Cualquiera de los predicados puede ser verdadero	{"or":[{...},{...}]}

Notas sobre el formato de tiempo

• Tiempos absolutos: Usa marcas de tiempo Unix (segundos desde epoch)
• Tiempos relativos: Segundos desde el tiempo de creación del saldo reclamable
• Marcas de tiempo: Deben estar en el futuro al crear el saldo

Casos de uso comunes

1. Pago simple con fecha límite

# Bob has 7 days to claim
stellar tx new create-claimable-balance \
  --source alice \
  --amount 50_000_000 \
  --claimant 'bob:{"before_relative_time":"604800"}'

2. Pago retrasado

# Bob can only claim after 1 day
stellar tx new create-claimable-balance \
  --source alice \
  --amount 100_000_000 \
  --claimant 'bob:{"not":{"before_relative_time":"86400"}}'

3. Fondo de emergencia

# Bob can claim immediately, but if he doesn't claim within 48 hours, Alice can reclaim
stellar tx new create-claimable-balance \
  --source alice \
  --amount 500_000_000 \
  --claimant 'bob:{"before_relative_time":"172800"}' \
  --claimant 'alice:{"not":{"before_relative_time":"172800"}}'

Notas

• --amount: Cantidad en stroops (1 XLM = 10,000,000 stroops)
• --asset: Usa "native" para XLM o el formato "CODE:ISSUER" para otros activos
• --claimant: Cuenta con predicado opcional (puede especificarse varias veces)
• Los predicados se evalúan cuando se reclama el saldo reclamable, no al crearlo
• Los predicados And y Or deben tener exactamente 2 subpredicados
• Los predicados complejos pueden anidarse para crear condiciones sofisticadas de reclamación