closes issue #2. feat(tokens): implement Soroban contract calls for mint/sell/balance

[Rocket1960]

Close #2

Replace placeholder logic in TokensService with real contract invocations:

• mintTokens: build/simulate/assemble/sign/sendTransaction against tokenMint contract
• sellTokens: same flow against tokenSale contract
• getBalance: simulation-only query returning scValToNative-parsed i128 balance

Update tests to cover full call chain with expanded SDK mock (Contract, TransactionBuilder, Keypair, Address, assembleTransaction, nativeToScVal, scValToNative) and add 9 specs across 3 describe blocks.
closes issue #2

[Joaco2603]

Review: cambios solicitados

Buen approach general. El flujo build → simulate → assemble → sign → send es el correcto para Soroban, y los tests están bien estructurados con 9 specs y buena cobertura de mocks. Pero hay dos temas que necesitan resolverse antes de mergear.

🔴 Error handling ausente

mintTokens, sellTokens y getBalance no tienen ningún try/catch. Si getAccount, simulateTransaction o sendTransaction fallan (timeout, red, contrato inválido), la promesa explota con un error crudo del SDK. En producción eso es un 500 sin mensaje útil.

Qué hacer: Envolver cada método en un try/catch que loggee el error y devuelva un objeto { error: "...", details: ... } consistente.

🟡 Falta polling de getTransactionStatus

sendTransaction solo significa "el RPC aceptó la tx". El resultado final (success/failed) requiere llamar a this.rpc.getTransaction(hash) hasta que status !== NOT_FOUND. Sin eso, el caller recibe un hash pero no sabe si la operación realmente se ejecutó.

Qué hacer: Agregar un helper awaitTransaction(hash) con timeout y reintentos, y llamarlo después de sendTransaction.

---

Issues secundarios (no blocker, para considerar)

• Código duplicado: El flujo build/simulate/assemble/sign/send está copiado 3 veces. Extraer un helper privado submitContractCall evitaría la repetición y centralizaría cambios futuros como el polling.
• BigInt(amount) sin validación: Si amount no es un entero válido, explota con SyntaxError. Validar antes o envolver en try/catch.
• Co-Authored-By: Claude Sonnet 4.6 en el commit: Las reglas del repo (AGENTS.md) piden no agregar atribución de IA a los commits. Sacarlo del mensaje.
• Branch name backend-security no refleja el contenido del PR (tokens, no seguridad).

Tests

Los tests están sólidos. Buenos mocks, cubren edge cases de contract ID faltante y el flujo completo. Cuando agregues error handling, agregaría también tests que verifiquen que los errores se manejan correctamente (RPC timeout, simulate fallido, etc.).

[Joaco2603]

Review: changes requested

Good approach overall. The build → simulate → assemble → sign → send flow is correct for Soroban, and the tests are well structured with 9 specs and solid mock coverage. But two things need to be addressed before merging.

🔴 Missing error handling

mintTokens, sellTokens, and getBalance have zero try/catch. If getAccount, simulateTransaction, or sendTransaction fail (timeout, network, invalid contract), the promise rejects with a raw SDK error. In production that means a 500 with no useful message for the caller.

Fix: Wrap each method in a try/catch that logs the error and returns a consistent { error: "...", details: ... } object.

🟡 Missing getTransactionStatus polling

sendTransaction only means "the RPC accepted the tx". The actual outcome (success/failed) requires calling this.rpc.getTransaction(hash) until status !== NOT_FOUND. Without this, the caller gets a hash but has no idea whether the operation actually executed.

Fix: Add a private awaitTransaction(hash) helper with timeout and retries, and call it after sendTransaction.

---

Secondary issues (not blockers, worth considering)

• Duplicated code: The build/simulate/assemble/sign/send flow is copy-pasted 3 times. Extracting a private submitContractCall helper would reduce repetition and centralize future changes like polling.
• BigInt(amount) without validation: If amount is not a valid integer, it throws SyntaxError. Validate before calling or wrap in try/catch.
• Co-Authored-By: Claude Sonnet 4.6 in the commit: The repo guidelines (AGENTS.md) explicitly forbid AI attribution in commits. Please remove it from the commit message.
• Branch name backend-security doesnt reflect the PR content (tokens, not security).

Tests

Tests are solid. Good mocks, edge cases covered for missing contract IDs, full flow coverage. When you add error handling, Id also add tests that verify errors are handled correctly (RPC timeout, failed simulation, etc.).

[Rocket1960]

Thanks for the review! Pushed a follow-up commit that:

Wraps mintTokens, sellTokens, getBalance in try/catch with consistent { error, details } responses
Adds awaitTransaction polling after sendTransaction
Extracts submitContractCall to remove duplication
Validates amount/price before BigInt()
Tests: 9 → 20 specs (added RPC failure, polling, timeout, and invalid input cases)
Note: the old commit still has the Co-Authored-By AI attribution — happy to rebase and squash if the repo guidelines require a fully clean history.

[Joaco2603]

.

[Joaco2603]

Un solo punto técnico real que corrigiría antes de mergear:

sendTransaction() no valida el status de respuesta

En submitContractCall(), después de sendTransaction tomás el hash y arrancás el polling con awaitTransaction. Pero si la red devuelve ERROR o TRY_AGAIN_LATER, eso se ignora y el polling corre 20 intentos hasta timeout, en vez de fallar rápido con la causa real y un mensaje claro.

Agregaría una guarda tipo:

const response = await this.rpc.sendTransaction(assembled);
if (response.status === ERROR || response.status === TRY_AGAIN_LATER) {
  throw new Error(`sendTransaction failed: ${response.status}`);
}

Antes de llamar a awaitTransaction(hash).

Lo demás se ve bien, está para mergear después de ese fix.

[Rocket1960]

Thanks for the review! Pushed a follow-up commit that:

tokens.service.ts — submitContractCall now captures the full sendTransaction response and checks the status before polling:

const sendResponse = await this.rpc.sendTransaction(assembled);
if (sendResponse.status === 'ERROR' || sendResponse.status === 'TRY_AGAIN_LATER') {
throw new Error(sendTransaction failed: ${sendResponse.status});
}
return this.awaitTransaction(sendResponse.hash);
tokens.service.spec.ts — Two new tests confirm getTransaction is never called and the error surfaces immediately, plus the default mock now includes status: 'PENDING' to be explicit.