Anchor Stellar de VANK — Guía de integración

# Lee el stellar.toml del ambiente — es la fuente de verdad
curl https://dev-stable-anchor.thisisvank.com/.well-known/stellar.toml   # producción: anchor.thisisvank.com

# Sin el SDK, SEP-10 son dos llamadas (cualquier lenguaje):
GET  https://dev-stable-anchor.thisisvank.com/auth?account=G...        # → { transaction, network_passphrase }
#    Verifica el challenge ANTES de firmar: read_challenge_transaction(xdr, SIGNING_KEY del toml, passphrase, home_domain, web_auth_domain) en el SDK de tu lenguaje
#    Fírmalo con la llave de la cuenta (y con la de tu dominio si mandaste client_domain)
POST https://dev-stable-anchor.thisisvank.com/auth   {"transaction": "<xdr firmado>"}   # → { token }  (JWT, 24 h)

yarn add @stellar/typescript-wallet-sdk

import { Wallet, SigningKeypair, DomainSigner } from "@stellar/typescript-wallet-sdk";

const HOME_DOMAIN = "dev-stable-anchor.thisisvank.com"; // pruebas · producción: anchor.thisisvank.com
const CLIENT_DOMAIN = "tu-dominio.com";                 // el tuyo, el que publica tu SIGNING_KEY

async function authenticate(authSecretKey: string) {
  const wallet = Wallet.TestNet(); // producción: Wallet.MainNet()
  const anchor = wallet.anchor({ homeDomain: HOME_DOMAIN });
  const sep10 = await anchor.sep10();
  const authKey = SigningKeypair.fromSecret(authSecretKey);

  // Tu backend co-firma el challenge con la llave de tu dominio.
  // La llave SECRETA nunca sale de ahí, ni llega al navegador.
  const walletSigner = new DomainSigner("https://" + CLIENT_DOMAIN + "/sign", {});

  return await sep10.authenticate({
    accountKp: authKey,
    walletSigner,
    clientDomain: CLIENT_DOMAIN,
  });
}

// En TU backend. Recibe el challenge, lo firma con la llave de tu dominio y lo devuelve.
// POST /sign  →  { transaction, network_passphrase }
import { Transaction, Keypair } from "@stellar/stellar-sdk";

app.post("/sign", (req, res) => {
  const { transaction, network_passphrase } = req.body;
  const tx = new Transaction(transaction, network_passphrase);
  tx.sign(Keypair.fromSecret(process.env.CLIENT_DOMAIN_SECRET!)); // la secreta de tu SIGNING_KEY
  res.json({ transaction: tx.toXDR(), network_passphrase });
});

# https://tu-dominio/.well-known/stellar.toml
VERSION = "2.7.0"
SIGNING_KEY = "G...LA_LLAVE_PUBLICA_DE_TU_APP"

// Retiro (off-ramp): el usuario envía USDC y recibe COP
const { url, id } = await anchor.sep24().withdraw({
  authToken,
  withdrawalAccount: USER_STELLAR_PUBLIC_KEY,
  assetCode: "USDC",
  lang: "es",
});
// Abre `url` en un webview: la UI de VANK guía el resto

// Depósito (on-ramp): el usuario paga COP (PSE) y recibe USDC
const { url, id } = await anchor.sep24().deposit({
  authToken,
  destinationAccount: USER_STELLAR_PUBLIC_KEY,
  assetCode: "USDC",
  lang: "es",
});

const watcher = anchor.sep24().watcher();
const { stop } = watcher.watchOneTransaction({
  authToken,
  assetCode: "USDC",
  id: transactionId,
  onMessage: (tx) => {
    if (tx.status === "pending_user_transfer_start") {
      // Retiro: envía el USDC ahora. Depósito: espera el pago del usuario
    }
  },
  onSuccess: (tx) => { /* completed */ },
  onError: (tx) => { /* error */ },
});

# Sin el SDK: iniciar y consultar (sandbox; producción: anchor.thisisvank.com)
curl -X POST "https://dev-stable-anchor.thisisvank.com/sep24/transactions/deposit/interactive" \
  -H "Authorization: Bearer $SEP10_JWT" -H "Content-Type: application/json" \
  -d '{"asset_code":"USDC","account":"G...","lang":"es"}'      # o /withdraw/interactive → { url, id }

curl "https://dev-stable-anchor.thisisvank.com/sep24/transaction?id=$TRANSACTION_ID" \
  -H "Authorization: Bearer $SEP10_JWT"

npm install @stellar/stellar-sdk        # firmar SEP-10 y el pago on-chain
# Nada más: el resto de SEP-6 son llamadas HTTP normales (fetch).

const ANCHOR = "https://dev-stable-anchor.thisisvank.com";   // SEP-6 vive HOY en el ambiente de pruebas
const auth = { Authorization: `Bearer ${authToken}` };   // JWT de SEP-10 (paso 3)

// 1) Pide el retiro. Devuelve un id; todavía NO puedes enviar el USDC.
const { id } = await fetch(
  `${ANCHOR}/sep6/withdraw?asset_code=USDC&account=${account}&amount=2&type=breb`,
  { headers: auth },
).then((r) => r.json());

// 2) Sondea la transacción y REACCIONA a su estado.
const tx = async () =>
  (await fetch(`${ANCHOR}/sep6/transaction?id=${id}`, { headers: auth }).then((r) => r.json()))
    .transaction;

// Recién creada está en incomplete: espera el PRIMER ciclo del motor (hasta ~30 s) antes de decidir nada. Si preguntas una sola vez ahora, te saltas el paso siguiente.
let t = await tx();
while (t.status === "incomplete") { await sleep(5000); t = await tx(); }
if (t.status === "pending_customer_info_update") {
  // 3) Te faltan datos. PREGUNTA cuáles — nunca los adivines.
  const need = await fetch(
    `${ANCHOR}/sep12/customer?account=${account}&transaction_id=${id}`,
    { headers: auth },
  ).then((r) => r.json());
  console.log(need.fields);   // cada campo trae una descripción para tu usuario

  // 4) Envíalos ATADOS a esta transacción. bank_account_number = la llave Bre-B.
  await fetch(`${ANCHOR}/sep12/customer`, {
    method: "PUT",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({
      account,
      transaction_id: id,
      type: "sep6-withdrawal",   // contexto de retiro: así SEP-12 sabe que hace falta la llave
      // TU USUARIO, quien retira. Lo mismo que escribe en nuestro formulario en SEP-24.
      first_name: "Ana", last_name: "Pérez",
      email_address: "ana@example.com",
      id_type: "CC", id_number: "1000000001",
      // EL BENEFICIARIO: solo su llave. Su nombre y documento NO los mandas — los resolvemos nosotros contra el directorio Bre-B.
      bank_account_number: "@llaveDeTuUsuario",
    }),
  });
}

// 5) SONDEA — no esperes una respuesta inmediata. Tras el PUT, la transacción
//    puede tardar hasta ~30 s en avanzar: nuestro motor revisa por ciclos.
while (["incomplete", "pending_customer_info_update"].includes((t = await tx()).status)) await sleep(5000);
// Cuando pase a pending_user_transfer_start ya tienes destino y memo.
// t.withdraw_anchor_account · t.withdraw_memo (memo_type "id") · t.amount_out = COP netos
// t.fee_details.total viene en USDC: es el mismo fee que la cotización te dio en COP, en otra unidad
// t.message = el beneficiario resuelto: enséñaselo al usuario ANTES de firmar

// 6) Envía el USDC a esa cuenta con ESE memo, y sigue sondeando hasta completed.

// 1) Cotización en firme (opcional, pero es lo que le garantiza la tasa a tu usuario)
// USDC_ISSUER: el emisor que leíste del stellar.toml del ambiente (sección 3). Nunca fijo en el código.
const q = await fetch(`${ANCHOR}/sep38/quote`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    sell_asset: "iso4217:COP", buy_asset: `stellar:USDC:${USDC_ISSUER}`,
    sell_amount: "5000", sell_delivery_method: "bank_transfer",
    country_code: "CO", context: "sep6",
  }),
}).then((r) => r.json());
// q.price · q.buy_amount · q.fee.total  ← la comisión viene APARTE, no dentro del precio

// 2) Inicia el depósito con esa cotización.
const { id } = await fetch(
  `${ANCHOR}/sep6/deposit-exchange?amount=5000&destination_asset=USDC` +
  `&source_asset=iso4217:COP&quote_id=${q.id}&account=${account}&type=bank_transfer`,
  { headers: auth },
).then((r) => r.json());
// OJO: esta respuesta NO trae el enlace. Solo { how, id }.

// 3) El enlace está en la TRANSACCIÓN.
const t = await fetch(`${ANCHOR}/sep6/transaction?id=${id}`, { headers: auth })
  .then((r) => r.json()).then((r) => r.transaction);
// t.more_info_url            → ábrelo en un webview. Su token vive 10 min; si vence, relee y sale otro.
// t.user_action_required_by  → hasta cuándo tiene tu usuario. HOY viene null: usa expires_at de la cotización

// 4) Tu usuario elige banco y paga por PSE. Sigue sondeando hasta completed.

# SEP-6 · depósito — NO necesita SEP-12: la identidad se verifica en el formulario del more_info_url
GET /sep6/deposit?asset_code=USDC&account=G...&amount=2&type=bank_transfer
#   → paga por el more_info_url de la transacción (mismo formulario y mismo PSE de prueba)

# SEP-6 · retiro — SÍ necesita SEP-12: PUT /sep12/customer (Authorization: Bearer <JWT SEP-10>)
{
  "account": "G...TU_CUENTA_TESTNET",
  "type": "sep6-withdrawal",
  "first_name": "Tester",                     # quien retira: tu usuario
  "last_name": "Sandbox",
  "email_address": "tester@example.com",
  "id_type": "CC",
  "id_number": "1000000001",
  "bank_account_number": "@alphamunKey01"     # el beneficiario: solo su llave Bre-B
}
GET /sep6/withdraw?asset_code=USDC&account=G...&amount=1&type=breb   # amount=1.11 → con devolución

# SEP-6 · depósito — NO necesita SEP-12: la identidad se verifica en el formulario del more_info_url
GET /sep6/deposit?asset_code=USDC&account=G...&amount=2&type=bank_transfer
#   → paga por el more_info_url de la transacción (mismo formulario y mismo PSE de prueba)

# SEP-6 · retiro — SÍ necesita SEP-12: PUT /sep12/customer (Authorization: Bearer <JWT SEP-10>)
{
  "account": "G...TU_CUENTA_TESTNET",
  "type": "sep6-withdrawal",
  "first_name": "Tester",                     # quien retira: tu usuario
  "last_name": "Sandbox",
  "email_address": "tester@example.com",
  "id_type": "CC",
  "id_number": "1000000001",
  "bank_account_number": "@alphamunKey01"     # el beneficiario: solo su llave Bre-B
}
GET /sep6/withdraw?asset_code=USDC&account=G...&amount=1&type=breb   # amount=1.11 → con devolución