mergepay-api

A API Mergepay é o serviço de backend do Mergepay, uma aplicação de liquidação de grupos nativa da Stellar. Trata da autenticação, lógica de grupos e despesas, liquidação on-chain, integração com a Stellar, multisig de tesouraria e fluxos de anchor SEP-24. O sistema é construído sobre a blockchain Stellar. Cada liquidação é um pagamento on-chain real: o login usa autenticação de carteira SEP-10, os pagamentos transportam um memo `MP:<code>` que os liga a uma despesa específica, os saldos são liquidados em XLM ou USDC através de trustlines, as tesourarias partilhadas usam multisig da Stellar, e a conversão fiat de entrada/saída passa por anchors SEP-24. O servidor nunca guarda as chaves privadas do utilizador — constrói envelopes de transação XDR não assinados que a carteira do utilizador assina antes da submissão ao Horizon. Arquitetura: A API é um backend Fastify + TypeScript suportado por PostgreSQL. Comunica com um frontend Next.js via REST com autenticação Bearer JWT. Um worker em segundo plano trata da submissão de liquidações e do polling de anchors SEP-24 com acompanhamento de tarefas baseado em claims e recuperação de processos que falharam. As principais funcionalidades incluem: - Autenticação baseada em carteira SEP-10, em que a chave pública do utilizador é a sua identidade - Fluxo de liquidação: a API constrói um XDR de pagamento não assinado com origem, destino, ativo, montante e memo, regista-o como pendente, a carteira assina-o, e a API valida o XDR assinado contra a intenção armazenada antes de o submeter ao Horizon - Expiração da intenção de transação com prazos controlados pelo servidor e tolerância limitada a desvios de relógio - Tesourarias de grupo partilhadas usando multisig da Stellar para levantamentos que exigem múltiplos signatários - Pontes de depósito e levantamento de anchors SEP-24 para conversão de fiat para Stellar - Proteção de idempotência na execução de liquidações para evitar submissões duplicadas - Limitação de taxa abrangente por rota com contadores partilhados suportados por base de dados entre instâncias - Limites de tamanho de pedido em corpos JSON e uploads multipart - Modo estrito do TypeScript aplicado em toda a base de código - Todos os corpos de pedido da API validados com Zod O projeto requer Node.js 20+ e PostgreSQL 14+ para ser executado. Pode ser implementado no Render, Fly.io ou Railway com um Postgres provisionado por fornecedores como Neon, Supabase ou RDS. Os testes são executados sem base de dados ou rede, usando Prisma e Horizon simulados, cobrindo o motor de liquidação, cálculos monetários, desafio/verificação SEP-10, validação de XDR assinado e rotas de autenticação. Um ficheiro `docs/api.http` incluído no repositório fornece uma coleção REST Client para exploração local da API.