Anchor Stellar da VANK — Guia de integração

# Leia o stellar.toml do ambiente — é a fonte da verdade
curl https://dev-stable-anchor.thisisvank.com/.well-known/stellar.toml   # produção: anchor.thisisvank.com

# Sem o SDK, o SEP-10 são duas chamadas (qualquer linguagem):
GET  https://dev-stable-anchor.thisisvank.com/auth?account=G...        # → { transaction, network_passphrase }
#    Verifique o challenge ANTES de assinar: read_challenge_transaction(xdr, SIGNING_KEY do toml, passphrase, home_domain, web_auth_domain) no SDK da sua linguagem
#    Assine com a chave da conta (e com a do seu domínio se enviou 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"; // testes · produção: anchor.thisisvank.com
const CLIENT_DOMAIN = "tu-dominio.com";                 // o seu, o que publica sua SIGNING_KEY

async function authenticate(authSecretKey: string) {
  const wallet = Wallet.TestNet(); // produção: Wallet.MainNet()
  const anchor = wallet.anchor({ homeDomain: HOME_DOMAIN });
  const sep10 = await anchor.sep10();
  const authKey = SigningKeypair.fromSecret(authSecretKey);

  // Seu backend co-assina o challenge com a chave do seu domínio.
  // A chave SECRETA nunca sai de lá, nem chega ao navegador.
  const walletSigner = new DomainSigner("https://" + CLIENT_DOMAIN + "/sign", {});

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

// No SEU backend. Recebe o challenge, assina com a chave do seu domínio e devolve.
// 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!)); // a secreta da sua SIGNING_KEY
  res.json({ transaction: tx.toXDR(), network_passphrase });
});

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

// Saque (off-ramp): o usuário envia USDC e recebe COP
const { url, id } = await anchor.sep24().withdraw({
  authToken,
  withdrawalAccount: USER_STELLAR_PUBLIC_KEY,
  assetCode: "USDC",
  lang: "pt",
});
// Abra `url` em um webview: a UI da VANK guia o resto

// Depósito (on-ramp): o usuário paga COP (PSE) e recebe USDC
const { url, id } = await anchor.sep24().deposit({
  authToken,
  destinationAccount: USER_STELLAR_PUBLIC_KEY,
  assetCode: "USDC",
  lang: "pt",
});

const watcher = anchor.sep24().watcher();
const { stop } = watcher.watchOneTransaction({
  authToken,
  assetCode: "USDC",
  id: transactionId,
  onMessage: (tx) => {
    if (tx.status === "pending_user_transfer_start") {
      // Saque: envie o USDC agora. Depósito: aguarde o pagamento do usuário
    }
  },
  onSuccess: (tx) => { /* completed */ },
  onError: (tx) => { /* error */ },
});

# Sem o SDK: iniciar e consultar (sandbox; produção: 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"}'      # ou /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        # assinar SEP-10 e o pagamento on-chain
# Nada mais: o resto do SEP-6 são chamadas HTTP normais (fetch).

const ANCHOR = "https://dev-stable-anchor.thisisvank.com";   // SEP-6 vive HOJE no ambiente de testes
const auth = { Authorization: `Bearer ${authToken}` };   // JWT do SEP-10 (passo 3)

// 1) Solicite o saque. Retorna um id; você ainda NÃO pode enviar o USDC.
const { id } = await fetch(
  `${ANCHOR}/sep6/withdraw?asset_code=USDC&account=${account}&amount=2&type=breb`,
  { headers: auth },
).then((r) => r.json());

// 2) Consulte a transação e REAJA ao seu status.
const tx = async () =>
  (await fetch(`${ANCHOR}/sep6/transaction?id=${id}`, { headers: auth }).then((r) => r.json()))
    .transaction;

// Recém-criada está em incomplete: espere o PRIMEIRO ciclo do motor (até ~30 s) antes de decidir algo. Se perguntar só uma vez agora, pula o próximo passo.
let t = await tx();
while (t.status === "incomplete") { await sleep(5000); t = await tx(); }
if (t.status === "pending_customer_info_update") {
  // 3) Faltam dados. PERGUNTE quais — nunca adivinhe.
  const need = await fetch(
    `${ANCHOR}/sep12/customer?account=${account}&transaction_id=${id}`,
    { headers: auth },
  ).then((r) => r.json());
  console.log(need.fields);   // cada campo traz uma descrição para seu usuário

  // 4) Envie-os ATRELADOS a esta transação. bank_account_number = a chave 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 saque: assim o SEP-12 sabe que a chave é necessária
      // SEU USUÁRIO, quem saca. O mesmo que ele digita no nosso formulário no SEP-24.
      first_name: "Ana", last_name: "Pérez",
      email_address: "ana@example.com",
      id_type: "CC", id_number: "1000000001",
      // O BENEFICIÁRIO: só a chave. Você NÃO envia nome nem documento — nós resolvemos no diretório Bre-B.
      bank_account_number: "@llaveDeTuUsuario",
    }),
  });
}

// 5) CONSULTE — não espere resposta imediata. Após o PUT, a transação
//    pode levar até ~30 s para avançar: nosso motor trabalha em ciclos.
while (["incomplete", "pending_customer_info_update"].includes((t = await tx()).status)) await sleep(5000);
// Quando chegar a pending_user_transfer_start você já tem destino e memo.
// t.withdraw_anchor_account · t.withdraw_memo (memo_type "id") · t.amount_out = COP líquidos
// t.fee_details.total vem em USDC: é a mesma taxa que a cotação deu em COP, em outra unidade
// t.message = o beneficiário resolvido: mostre ao usuário ANTES de assinar

// 6) Envie o USDC para essa conta com ESSE memo e continue consultando até completed.

// 1) Cotação firme (opcional, mas é o que garante a taxa ao seu usuário)
// USDC_ISSUER: o emissor que você leu do stellar.toml do ambiente (seção 3). Nunca fixo no 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  ← a comissão vem À PARTE, não dentro do preço

// 2) Inicie o depósito com essa cotação.
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());
// ATENÇÃO: esta resposta NÃO traz o link. Apenas { how, id }.

// 3) O link está na TRANSAÇÃO.
const t = await fetch(`${ANCHOR}/sep6/transaction?id=${id}`, { headers: auth })
  .then((r) => r.json()).then((r) => r.transaction);
// t.more_info_url            → abra em um webview. Seu token vive 10 min; se vencer, releia e sai outro.
// t.user_action_required_by  → até quando seu usuário tem. HOJE vem null: use o expires_at da cotação

// 4) Seu usuário escolhe o banco e paga via PSE. Continue sondando até completed.

# SEP-6 · depósito — NÃO precisa de SEP-12: a identidade é verificada no formulário do more_info_url
GET /sep6/deposit?asset_code=USDC&account=G...&amount=2&type=bank_transfer
#   → pague pelo more_info_url da transação (mesmo formulário e mesmo PSE de teste)

# SEP-6 · saque — PRECISA de SEP-12: PUT /sep12/customer (Authorization: Bearer <JWT SEP-10>)
{
  "account": "G...SUA_CONTA_TESTNET",
  "type": "sep6-withdrawal",
  "first_name": "Tester",                     # quem saca: seu usuário
  "last_name": "Sandbox",
  "email_address": "tester@example.com",
  "id_type": "CC",
  "id_number": "1000000001",
  "bank_account_number": "@alphamunKey01"     # o beneficiário: só a chave Bre-B
}
GET /sep6/withdraw?asset_code=USDC&account=G...&amount=1&type=breb   # amount=1.11 → com devolução

# SEP-6 · depósito — NÃO precisa de SEP-12: a identidade é verificada no formulário do more_info_url
GET /sep6/deposit?asset_code=USDC&account=G...&amount=2&type=bank_transfer
#   → pague pelo more_info_url da transação (mesmo formulário e mesmo PSE de teste)

# SEP-6 · saque — PRECISA de SEP-12: PUT /sep12/customer (Authorization: Bearer <JWT SEP-10>)
{
  "account": "G...SUA_CONTA_TESTNET",
  "type": "sep6-withdrawal",
  "first_name": "Tester",                     # quem saca: seu usuário
  "last_name": "Sandbox",
  "email_address": "tester@example.com",
  "id_type": "CC",
  "id_number": "1000000001",
  "bank_account_number": "@alphamunKey01"     # o beneficiário: só a chave Bre-B
}
GET /sep6/withdraw?asset_code=USDC&account=G...&amount=1&type=breb   # amount=1.11 → com devolução