feat: implement spatial H3 multi-peer liquidity netting and atomic swap engine

[Opulencechuks]

Closes #372

Summary

This PR implements an automated Spatial H3 Multi-Peer Liquidity Netting & Cross-Chain Atomic Swap Engine. Velo's current cash allocation processes requests as isolated point-to-point trades, which leads to capital inefficiency, high transaction fees, and excessive provider collateral lockups in dense geographic areas.

This change introduces an automated multi-hop circular clearing model. It leverages Uber H3 spatial indexing to group participants, Johnson's algorithm for directed graph cycle detection, and PostgreSQL deadlock-free ordered pessimistic locking (SELECT FOR UPDATE NOWAIT). Furthermore, it updates the atomic-swap and session-account Soroban smart contracts to broadcast secret_reveal events for automated preimage propagation and enforces session quota limits during relayer executions.

Testing

The following commands were used to validate the core logic, stress test the pessimistic row locking, and run the Soroban invariant assertions:

# Run unit tests for Johnson's cycle detection and H3 resolution
vitest run apps/api/src/lib/__tests__/spatial-netting.test.ts

# Execute the 50-client parallel concurrency stress test for DB deadlock avoidance (40P01)
vitest run tests/concurrency/netting_deadlock_stress.test.ts

# Run tests for on-chain Soroban HTLC invariants and session quotas
cd contracts/atomic-swap && cargo test
cd contracts/session-account && cargo test

Checklist

• I read the contributing guide.
• I added or updated relevant documentation.
• I verified the change with the relevant tests or builds.

[vercel]

@Opulencechuks is attempting to deploy a commit to the jotelfootball-tech's projects Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
velo	Error		Aug 25, 2026 3:41am
velo-frontend	Ready	Preview	Aug 25, 2026 3:41am

[jotel-dev]

@Opulencechuks your pr has been reviewed and I noticed that the node CI check failed,same as the the vercel front-end deployment and the velo API deployment, kindly fix that and I will review it again
Thanks.

[jotel-dev]

@Opulencechuks yu have made some progress but the node ci check failed and the velo deployment too, fix that and iI will review it again

[jotel-dev]

@Opulencechuks you have made some progress but stilll, the node ci check failed and the velo deployment too, fix that and it will review it again

[jotel-dev]

Hey @Opulencechuks , noticing node-ci / build and Vercel – velo are failing now (29s and deployment failure respectively), even though this was green before. Could you check the logs and the npx vercel inspect dpl_3cor8S8sy3v... output and see what's going on?

[Opulencechuks]

please review and merge