Skip to main content
Architecture status: Working architecture, August 2026. This document consolidates Oynk’s complete technical architecture into one review surface. Its primary purpose is to specify the SCF Integration Track work: how Privy, Stellar Wallets Kit, Anchor Platform, Blend v2, Stellar USDC, and Oynk’s Soroban coordination and settlement protocol combine into one commercial-payment lifecycle. It also covers the implemented monorepo, identity and compliance foundation, BSC and Solana visibility plane, the separately deployed Stellar mainnet settlement MVP, data and API boundaries, and operational controls. The Stellar mainnet MVP is deployed at CDTDCQ2Y6OASQVJGOFBA2EHP3AV7N6FFULJNEFGMORLYMNHECX7OO2W6. It was created on July 11, 2026 in transaction 58eb6b55…d2fa0. On September 3, 2026, WASM d16b5f8a2b9971e2ea45bf0737731ed6348bd83b7c30fde275589f69ea132bc9 was uploaded and the existing instance was upgraded by its administrator. The live WASM was fetched after confirmation and matched the artifact built from source commit 60489c3. Source, locked tests, and structured deployment evidence are maintained by Emmanuel Ekoja in the settlement-aggregator-protocol repository. The original July WASM hash remains recorded as source-unverified historical provenance. The mainnet MVP completed three settlement lifecycles using real USDC. With seven token decimals, the deposited principals normalize to 500, 1,500, and 2,360 USDC, totaling 4,360 USDC of settlement principal. This measure counts each request once rather than double-counting its escrow deposit and subsequent claim.

​
1. Executive summary

Oynk is designed as programmable infrastructure between payment demand and local financial capability. Payment applications use a consistent lifecycle while qualified liquidity and settlement providers execute corridor-specific collection, conversion, digital-asset, and payout legs. The architecture separates five concerns:
  1. Experience: public web, payment experiences, and organization-specific operations consoles.
  2. Control plane: identity, authorization, exact-value validation, compliance policy, quotes, provider selection, payment state, and authoritative references.
  3. Provider plane: qualified participants that supply liquidity, banking connectivity, collection, exchange, and destination payout.
  4. Settlement plane: the deployed Soroban MVP and its proposed hardened successor governing funding, commitments, claims, refunds, and disputes.
  5. Visibility plane: chain indexers, normalized PostgreSQL records, reconciliation, metrics, and operational dashboards.
The design deliberately separates observed blockchain movement from verified business settlement. A chain transaction proves accepted ledger activity; it does not prove customer authorization, provider eligibility, fiat delivery, or end-to-end payment completion.

​
2. Goals and non-goals

​
Goals

  • Give payment applications one stable, idempotent lifecycle across multiple providers and corridors.
  • Apply identity, authorization, compliance, limit, and route policy before value-changing actions.
  • Treat all monetary values exactly, without floating-point arithmetic.
  • Use authoritative references across payment, provider, contract, chain, and reconciliation records.
  • Make on-chain settlement transitions explicit, auditable, replay-safe, and privacy-conscious.
  • Observe supported blockchain activity durably across reorganizations, duplicates, RPC limits, and partial failures.
  • Keep providers modular so a provider can be added, suspended, or replaced without redesigning application integrations.
  • Operate under least privilege with durable audit, monitoring, recovery, and incident controls.

​
Non-goals

Oynk does not replace local licensing, sanctions obligations, banking connectivity, provider due diligence, liquidity commitments, dispute operations, or legal analysis. A public dashboard is not a ledger of legally final customer payments. Soroban cannot independently establish an off-chain payout fact without evidence supplied through an authorized policy boundary.

​
3. System context

​
3.1 SCF integration scope at a glance

The grant-funded system is not a collection of unrelated integrations. Each building block owns a distinct boundary in the same payment flow.
Two wallet paths, one authorization boundary: Privy is the default onboarding path. Stellar Wallets Kit is an alternative for a participant that already controls a compatible Stellar wallet. Selecting either path does not approve a participant or a payment; Oynk’s server still applies organization permissions, KYC/KYB status, corridor policy, limits, and transaction-specific authorization.

​
3.2 End-to-end integration flow

The expected happy path is:
  1. Onboard and connect. The business authenticates through Privy and receives embedded Stellar access, or connects an existing wallet through Stellar Wallets Kit. The selected public address is bound to the participant’s Oynk organization after a signed challenge and server-side authorization.
  2. Establish eligibility. Oynk collects or retrieves required customer information and makes the KYC/KYB, sanctions, wallet-risk, corridor, provider-type, and limit decisions. Anchor Platform’s SEP-12 endpoint exposes the required fields and status, while the Oynk business server remains the decision-maker.
  3. Request and lock a rate. The business requests an indicative price or firm quote. Anchor Platform exposes the SEP-38 interface; Oynk’s liquidity engine filters eligible providers, obtains capacity and pricing, calculates disclosed fees, and persists the accepted quote and expiry. Acceptance creates a time-bounded rate-lock obligation.
  4. Collect origin value. For a fiat on-ramp or off-ramp, Anchor Platform manages the standardized SEP-24 flow and receives authenticated updates from Oynk’s business server as the regulated fiat partner reports collection or payout. SEP-31 is used where another anchor or sending institution initiates a cross-border receive-payment flow.
  5. Account for the deposit. Any business deposit is divided in Oynk’s exact-value subledger into the amount reserved for active rate locks and the remaining liquid excess. Reserved funds cannot enter a yield strategy.
  6. Apply optional Blend allocation. An eligible business may explicitly opt in to allocate up to the configured percentage of only its excess USDC balance to an allowlisted Blend v2 pool. The initial policy target is at most 50% of eligible excess, subject to a lower corridor, business, pool, or aggregate cap. Oynk never allocates the reserve needed to honor a rate lock.
  7. Coordinate and settle. Oynk creates a referenced Soroban settlement containing the exact asset, amount, authorized parties, deadlines, route commitment, and policy version. Stellar USDC funds the contract. Authorized transitions enable claim, refund, cancellation, or dispute resolution without placing personal or bank information on-chain.
  8. Observe and reconcile. The Soroban indexer consumes versioned contract events. Oynk correlates them with Anchor Platform transaction IDs, fiat-provider references, wallet addresses, payment legs, and internal ledger entries. A payment becomes complete only when every required on-chain and off-chain leg satisfies its completion rule.

​
3.3 Privy embedded-wallet integration

Privy is the primary access path for general business onboarding. Oynk will use it to create or recover an embedded wallet experience behind familiar authentication, then associate the resulting Stellar address with an Oynk organization and user membership. The integration will implement:
  • Privy session verification on the server before trusting a wallet association;
  • Stellar account creation or access in the supported Privy configuration;
  • signed wallet-linking challenges with nonce, expiry, intended organization, and network;
  • explicit transaction previews for asset, amount, destination/contract, network, fee, and expiry;
  • reauthentication or step-up controls for sensitive signing actions;
  • account recovery, wallet unlinking, compromised-session response, and audit events; and
  • testnet/mainnet configuration separation.
Privy does not make compliance, payment, quote, or settlement decisions. It supplies the embedded access and signing boundary; Oynk supplies business authorization and transaction policy. Completion test: A newly approved test business can authenticate, obtain or access a Stellar-capable embedded wallet, link it to the correct organization, review and authorize a testnet transaction, reconnect safely, and view the resulting payment reference without exposing private key material to Oynk.

​
3.4 Stellar Wallets Kit integration

Stellar Wallets Kit is the alternative access path for settlement partners, liquidity providers, and businesses that prefer an existing external Stellar wallet. Oynk will use the kit’s supported-wallet connection and signing interfaces instead of implementing wallet-specific adapters. The integration will implement:
  • supported-wallet discovery and connection;
  • a signed, expiring challenge to prove control of the selected account;
  • network/passphrase checks before any signature request;
  • transaction-envelope presentation and user authorization;
  • rejection, disconnect, account-change, and reconnect handling;
  • mapping of an approved address to provider and corridor permissions; and
  • server-side verification that the submitted transaction matches the immutable payment instruction.
A connected wallet is not automatically an eligible settler. Oynk separately verifies the provider, organization, account allowlist, corridor, amount, asset, and assigned settlement role. Completion test: An approved provider connects a supported testnet wallet, proves address control, receives a transaction built for its assigned settlement, signs or rejects it, and Oynk records the result idempotently. A wrong-network, wrong-account, altered-envelope, expired-challenge, or unapproved-provider attempt is rejected.

​
3.5 Anchor Platform on-ramp and off-ramp integration

Oynk intends to use Anchor Platform as the standardized Stellar-facing boundary for on-ramp, off-ramp, and cross-border flows. Anchor Platform will be deployed with private access to the Oynk business server; it will not connect directly to internal databases or independently approve customers. The business server will expose only the callbacks and private APIs Anchor Platform requires. Requests will be authenticated, schema-validated, idempotent, correlated to stable Oynk references, and recorded in an audit trail. Fiat-provider webhooks remain untrusted until signature verification, replay protection, status-transition validation, and reconciliation succeed. Anchor status is not by itself proof of fiat finality. Oynk records the Anchor transaction ID, external fiat reference, provider evidence, Stellar transaction hash, Soroban settlement ID, and reconciliation state as separate fields. Completion test: A reviewer can authenticate, satisfy a test SEP-12 customer flow, obtain and accept a SEP-38 firm quote, start a SEP-24 deposit or withdrawal or a documented SEP-31 receive flow, observe authenticated fiat-status updates, and trace the same stable reference into Soroban funding and reconciliation. Duplicate callbacks do not duplicate value or advance an invalid state.

​
3.6 Blend v2 opt-in yield integration

Blend is not the source of rate-lock liquidity and is not permitted to hold funds needed for settlement. It is an optional capital-efficiency feature for eligible excess business deposits. For each business, Oynk’s exact-value subledger will maintain:
  • RESERVED: immediately available USDC required for accepted rate locks;
  • LIQUID: USDC not currently reserved or supplied to Blend;
  • YIELD_PENDING: opted-in excess awaiting a permitted supply/withdraw transaction; and
  • YIELD_DEPLOYED: principal represented by the business’s share of the reconciled Blend position.
The allocation precondition is:
The proposed initial opt_in_percentage ceiling is 50%, but policy may set it lower. Oynk will allowlist the pool and asset contract, verify network and contract identifiers, read pool liquidity and position state, record transaction hashes and ledger numbers, and reconcile aggregate on-chain balances back to per-business principal, yield, loss, fees, and withdrawals. The funded scope will not borrow, use leverage, enter a backstop module, promise a return, guarantee principal, or automatically opt a business in. A liquidity shortfall, pool/configuration anomaly, oracle-health breach, reconciliation variance, or emergency state disables new allocations and can initiate controlled withdrawals without consuming rate-lock reserves. Completion test: An eligible test business explicitly opts in, allocates only permitted excess test USDC, sees its subledger and Blend position reconcile, requests withdrawal, and opts out. Attempts to allocate reserved funds, exceed any cap, use a non-allowlisted pool, or act without consent fail before submission.

​
3.7 Soroban coordination and settlement protocol

Soroban is the final coordination and value-settlement layer in the flow. Oynk will harden the existing mainnet MVP into a contract suite and supporting submitter/indexer that can represent payment requests, eligible provider participation, firm quote commitments, escrow funding, deadlines, claim authorization, refunds, disputes, reconciliation references, and terminal completion. The control plane will keep customer identity, bank instructions, compliance evidence, provider pricing detail, and raw payout evidence off-chain. The contract receives only the minimum non-personal reference, exact network-scoped asset and amount, authorized addresses, deadlines, policy/route commitment, and permitted transition. Every contract method will verify Soroban authorization, current state, asset allowlist, exact amount, deadline, and replay/idempotency condition. Claim and refund are mutually exclusive terminal outcomes. Privileged actions—including pause, dispute resolution, migration, and upgrade—will use documented role separation and auditable governance rather than a single implicit application key. Completion test: A testnet lifecycle proceeds from request and quote commitment through exact USDC funding, claim enablement, claim, event indexing, and reconciliation. Separate fixtures prove expiry/refund, cancellation-before-funding, dispute resolution, duplicate submission, unauthorized signer, wrong asset/amount, paused contract, and indexer replay behavior. The final milestone executes one narrowly scoped approved mainnet flow after release gates are satisfied.

​
3.8 Cross-integration identifiers and state ownership

One payment_id ties the integrations together, but Oynk preserves each system’s native identity instead of treating similar amounts or timestamps as correlation. The commercial payment state lives in Oynk. Anchor Platform owns standardized protocol workflow state. Privy or the connected wallet owns signing authority. Blend owns the aggregate lending-pool position. Soroban owns settlement escrow and transition state. A successful result in any one component cannot independently mark the overall payment complete.

​
3.9 Integration security and production gates

Before a mainnet corridor is enabled, Oynk requires:
  • confirmed provider support for the intended country, currency, direction, limits, Stellar network, and USDC asset;
  • applicable Oynk authorization and/or a documented regulated-bank, PSP, anchor, or payout-partner arrangement;
  • production KYC/KYB, sanctions, wallet-risk, transaction-monitoring, case, and audit integrations;
  • independent Soroban security review and resolved release-blocking findings;
  • tested secrets management, signer separation, contract governance, pause, recovery, and rollback procedures;
  • Anchor callback authentication, idempotency, replay protection, and fiat reconciliation;
  • Privy and external-wallet recovery/compromise procedures;
  • Blend pool allowlisting, allocation caps, consent records, liquidity/risk monitoring, reconciliation, and emergency withdrawal controls; and
  • on-chain monitoring for contract events, balances, failed or stuck transactions, indexing lag, reserve deficits, unauthorized changes, and reconciliation variance.
Production activation is corridor-specific. Completing the technical integration does not assert that Oynk or every liquidity participant is licensed for every jurisdiction or transaction type. Solid paths through identity, BSC/Solana indexing, PostgreSQL, APIs, and web views have implemented foundations. Dotted Stellar/Soroban and payment-orchestration paths are proposed.

​
4. Repository and package architecture

Oynk is a pnpm workspace with strict package ownership. Shared models belong in @oynk/shared. Business rules and authorization remain in @oynk/api. Presentation packages consume shared contracts and never import API internals. Future Soroban contracts should have a clearly owned Rust workspace, deterministic tests, generated bindings, deployment manifests, and source-to-bytecode verification.

​
5. Implemented runtime architecture

The API validates environment configuration at startup. It exposes liveness, readiness, public activity, synchronization, authentication, and compliance routes. When enabled, synchronization runs after startup and on a configured interval. Production scaling should extract indexing into dedicated workers instead of coupling scheduled work to an API instance.

​
6. Experience and presentation layer

The public web application provides Oynk’s website and settlement-activity dashboard. The dashboard separates gross blockchain movement from reference-paired estimated settlement, shows inflows and outflows, exposes sync timestamps and timeline activity, and links on-chain observations to explorers. The authenticated console supports business and settlement-partner signup, email verification, password-plus-OTP sign-in, organization selection, role-specific shells, and business-compliance draft entry. Payment, payout, settlement, provider, liquidity, corridor, terminal, reconciliation, webhook, API-key, and full internal review destinations are not complete transactional products. They remain empty, disabled, or informational until their server APIs and authorization contracts exist. Business logic must not migrate into React components. UI authorization improves usability but never replaces server enforcement.

​
7. Identity, tenant, and authorization model

​
Users and organizations

Users and organizations are distinct records. A user can hold organization memberships; a session selects one active organization and receives the corresponding role and resolved permission list. Organization types are:
  • BUSINESS
  • SETTLEMENT_PARTNER
  • INTERNAL
Organization lifecycle includes draft, email-verification-required, compliance-incomplete, submitted, under-review, additional-information-required, approved, active, rejected, suspended, and closed states. SANDBOX, TEST, and LIVE platform modes separate environments and operational authority.

​
Authentication flow

Passwords use scrypt with per-password salts. OTP and session secrets are stored as keyed hashes using an environment pepper. OTPs have expiry, attempt limits, and resend cooldowns. Sessions expire, can be revoked, and carry a distinct CSRF secret. Return paths are constrained to safe local paths. Authentication rate limiting is process-local today and must move to shared gateway or datastore enforcement before horizontal scaling.

​
Authorization

Roles map to fine-grained permissions for payments, payouts, terminals, settlements, liquidity, compliance, organization management, members, developer tooling, audit, indexing, applications, and account activation. Every sensitive server route must authenticate the session, resolve the active organization, require the correct permission, and enforce CSRF for cookie-authenticated state changes.

​
8. Compliance architecture

The implemented business profile flow validates legal name, registration information, ISO country codes, incorporation date, tax identifier, website, industry, business description, address, expected volume, expected transactions, and source of funds. A save operation atomically updates the organization, upserts the profile, and records an audit event. The target control plane adds:
  • KYC/KYB and beneficial-owner verification
  • Sanctions and politically exposed person screening where required
  • Transaction monitoring and case management
  • Corridor, currency, asset, provider, and amount/frequency eligibility
  • Evidence retention and Travel Rule exchange where applicable
  • Versioned decisions linked to payments and assignments
Personal data remains off public chains. On-chain state should contain only stable non-personal references or deliberately designed commitments. The architecture does not imply licensing or approval in any jurisdiction.

​
9. Target payment control plane

The control plane is authoritative for customer intent and business lifecycle. It owns:
  • Idempotent payment creation
  • Exact origin and destination amounts
  • Currency, asset, chain, recipient, and corridor validation
  • Quote requests, fees, rate locks, expiry, and slippage
  • Compliance and limit decisions
  • Provider eligibility, capacity, selection, and assignment
  • Funding instructions and deadlines
  • Settlement, payout, evidence, exception, refund, and dispute state
  • Stable payment, settlement, corridor, and leg references
  • Auditable state transitions
Indexers must never create or authorize payment state by observing a similar amount and timestamp.

​
10. Proposed end-to-end payment lifecycle

Completion requires all required legs and evidence. Quote acceptance, funding, provider evidence, on-chain claims, and retries must be idempotent. Expired quotes require requoting. Partial funding requires an explicit top-up, partial acceptance, cancellation, or refund rule. Provider failure can trigger reassignment, refund, or dispute only through defined transitions.

​
11. Provider network architecture

Providers are modular participants, not implicitly trusted extensions of Oynk. Each production profile needs legal/KYB status, beneficial ownership, corridor and currency eligibility, supported assets and rails, banking capability, operating hours, limits, liquidity or collateral policy, pricing, service levels, evidence requirements, contacts, suspension state, and exit procedure. Assignment filters by eligibility before comparing capacity, price, completion history, concentration, and operational risk. Provider performance should measure verified acceptance, completion time, quote reliability, evidence quality, exception and dispute rates, reconciliation gaps, and availability. Fiat connectors should expose idempotent create, status, evidence, cancel, and reconcile operations behind provider-specific adapters. A provider callback is untrusted input until authenticated, validated, deduplicated, and correlated to the correct assignment.

​
12. Stellar and Soroban target architecture

Stellar is the proposed asset settlement rail. Soroban is the proposed programmable policy boundary for referenced settlement state. Customer identity, provider due diligence, quote calculation, route selection, compliance reasoning, and detailed fiat evidence remain off-chain. Before implementation, Oynk must decide network selection, asset and issuer allowlists, trustline requirements, token contract identity, contract ownership, upgrade governance, authorization graph, storage and event schema, fee sponsorship, sequence handling, timebounds, partial funding, dispute authority, emergency pause, recovery, and data retention. RPC URLs, issuers, network passphrases, contract IDs, explorers, and signers must be environment-specific validated configuration. Testnet and mainnet identifiers must never mix.

​
13. Proposed Soroban settlement contract

​
State machine

​
Minimum record

​
Contract invariants

  • Settlement identifiers cannot be reused with different terms.
  • Only the configured network-scoped asset and permitted amount can fund a request.
  • Claim and refund are mutually exclusive terminal outcomes.
  • State transitions are monotonic except where an explicitly specified dispute path applies.
  • Each transition verifies the necessary Soroban authorization entries.
  • Repeated submissions are idempotent or fail without changing value.
  • Deadline behavior is based on documented ledger-time semantics.
  • Checked integer arithmetic prevents overflow, underflow, and precision drift.
  • Stored state and emitted events exclude names, phone numbers, bank data, credentials, and raw compliance evidence.

​
Events and indexing

Events should be versioned and cover creation, funding, claim enablement, claim, refund initiation, refund, dispute, resolution, pause, and migration where applicable. The future indexer stores network, contract ID, ledger, transaction hash, event position, topic/version, settlement reference, decoded payload, and ingestion checkpoint. Event identity must be deterministic so replays do not duplicate business records.

​
14. Stellar asset and transaction model

An asset allowlist is keyed by network and canonical identity. Classic Stellar assets require code and issuer. Soroban token use requires the verified contract address and its relationship to the underlying asset. Symbols are display values only. Before building a transaction, Oynk validates network/passphrase, asset identity, decimals, exact scalar conversion, trustline or authorization prerequisites, issuer controls, recipient address, settlement state, and signer authority. A dedicated submitter should:
  1. Build the intended operation from immutable, versioned instructions.
  2. Simulate Soroban execution.
  3. Enforce resource and fee limits.
  4. Collect the minimum required authorization.
  5. Add bounded time conditions and network/contract domain binding.
  6. Persist submission intent and transaction identity under an idempotency key.
  7. Submit once and recover status after timeouts rather than blindly resubmitting.
  8. Wait for the defined successful ledger and contract result.
  9. Correlate the indexed event to the authoritative settlement reference.
If Oynk sponsors fees or reserves, sponsorship must be limited by operation, account, asset, amount, frequency, and environment to prevent arbitrary relay abuse.

​
15. Smart accounts and delegated authorization

The planned smart-account layer supports narrow authority rather than unlimited hot keys. A policy may combine a Stellar G-account or contract principal, passkey-backed user authorization, short-lived session delegates, per-action and per-asset limits, recipient constraints, rolling spend limits, expiry, invocation counts, nonces, recovery, and revocation. Phone numbers can aid discovery or recovery but are not cryptographic authorization.

​
Low-connectivity flow

This is one-sided low-connectivity authorization, not fully offline settlement. The merchant must reach the network, and offline users cannot observe recent revocation or competing submissions. Policies require narrow caps, short expiry, atomic nonce consumption, secure key storage, domain separation, clear wallet signing UX, and explicit maximum exposure.

​
16. Current blockchain visibility plane

​
Synchronization coordination

An in-process flag prevents overlapping work locally. A fixed PostgreSQL advisory lock prevents concurrent API or CLI processes from executing the global sync. Every run receives a UUID and durable start/end time, mode, state, counts, error count, and per-chain outcome. Partial success is retained.

​
BSC indexing

The BSC indexer observes configured wallets against allowlisted ERC-20 contracts. Current assets are USDT, USDC, and BTCB. It calculates a safe tip by subtracting confirmation depth, rewinds recent blocks on later runs to reconcile reorganizations, and advances a cursor keyed by normalized wallet and contract. Log ranges adapt to RPC constraints: the indexer begins with a configured chunk, retries temporary failures, reduces rejected ranges down to a minimum, and grows after repeated successes. Delays and jitter reduce provider pressure. Block timestamps are cached within a run. Deterministic transfer identities and upserts make rewind and replay safe.

​
Solana indexing

The Solana indexer observes configured owner, associated-token-account, token-account, and manual sources. It fetches signatures, loads parsed transactions, and derives USDT/USDC movement from pre/post token balances. Failed transactions remain visible with FAILED status but cannot be paired. The current signature limit bounds each source scan. Production still needs durable historical pagination/checkpoints, comprehensive source discovery, Token-2022 coverage, and an automatic durable-failure reprocessor. Reliable archival RPCs are required for material backfills.

​
Pairing and settlement semantics

The current matcher processes confirmed, unpaired inflows and selects an available confirmed outflow using same-asset preference, amount proximity, and time proximity. PostgreSQL NUMERIC performs amount comparison. Both legs are locked and updated within one database transaction. These pairs are labeled HEURISTIC with confidence 0.5000. They support investigation only and are excluded from authoritative reference-paired settlement. Future payment orchestration must write explicit payment, settlement, corridor, origin-leg, and destination-leg references.

​
17. Exact value and metrics

Raw token integers, decimals, normalized decimal strings, and operational USD values are retained. Monetary calculations must use integer or exact decimal representations. Current operational valuations are: BTCB’s value is not live or historical pricing. Metrics are operational indicators, not accounting statements.
  • Gross transfer volume: all confirmed observed legs plus recorded off-chain movement.
  • Inflow and outflow: wallet-relative direction.
  • Estimated settled volume: conservative smaller value of REFERENCE-paired legs plus off-chain records.
  • Unmatched volume: movement not included in authoritative pairing.
  • Settlement count: reference-paired settlements plus off-chain records.
  • Last indexed time: synchronization-run time, not transaction time.

​
18. Implemented PostgreSQL model

Future migrations need requests, quotes, acceptances, assignments, funding instructions, compliance decisions, payout evidence, disputes, refunds, Stellar network/asset configuration, Soroban submissions, contract events, and reconciliation outcomes. Historical migrations remain immutable.

​
19. API boundaries

​
Current public and operational endpoints

  • GET /health/live: process liveness.
  • GET /health/ready: configuration and PostgreSQL readiness.
  • GET /api/dashboard: metrics, timeline, and recent activity filtered by ALL, BSC, SOLANA, or OFFCHAIN.
  • GET /api/dashboard/sync and GET /api/sync/status: in-process synchronization status.
  • POST /api/dashboard/sync: administrator-key-protected, process-limited async synchronization.
  • GET /api/sync/runs, /api/sync/runs/{id}, and /api/sync/failures: operational records requiring deployment access policy.
Authentication endpoints handle signup, verification, sign-in, OTP, password reset, organization selection, session reads, resend, and sign-out. Compliance endpoints handle authorized business-profile reads and CSRF-protected saves. Future payment APIs require versioned schemas, authentication, organization authorization, idempotency keys, exact input validation, request-size limits, rate limits, audit transitions, and stable error contracts. No current endpoint creates payments, obtains quotes, assigns providers, submits Stellar transactions, or invokes Soroban.

​
20. Trust boundaries and security model

  1. Credentials prove identity; organization membership and permission checks grant authority.
  2. Browser checks never replace API authorization.
  3. Provider evidence is authenticated external input, not self-proving completion.
  4. Chain consensus proves ledger state, not off-chain identity or payout truth.
  5. RPC responses and webhook payloads are untrusted and validated before persistence.
  6. Public reporting minimizes personal and commercially sensitive data.
  7. Signing material, API keys, session tokens, OTPs, signed payloads, and private evidence are never logged.
  8. Mainnet and testnet configuration, identifiers, signers, and state remain strictly partitioned.
Current controls include Helmet security headers, configured CORS, JSON body limits, Zod input validation, scrypt password hashing, HMAC-secret storage, timing-safe comparisons, CSRF checks, role permissions, audit records, admin sync authentication, replay-safe indexing identities, confirmation depth, rewind, advisory locking, and durable failure state. Before production, add shared rate limiting, stronger operator endpoint authorization, key rotation, secret management, RPC failover, anomaly alerts, complete audit coverage, controlled CORS, formal data retention, and independent security review.

​
21. Soroban threat model

​
22. Reliability, scaling, and observability

​
Reliability baseline

  • Deterministic identities and database uniqueness
  • BSC confirmation depth and reorg rewind
  • Contract-specific BSC checkpoints
  • Adaptive range sizing and bounded RPC retry
  • PostgreSQL advisory locks
  • Durable run and failure records
  • Partial-result preservation
  • Health/readiness endpoints
  • Graceful API and database shutdown

​
Scale path

Move indexing out of the API into workers partitioned by chain and source under durable leases. Preserve deterministic uniqueness and transactional checkpoint rules. Batch writes only after correctness and query-plan measurement. Introduce server-side pagination for large activity datasets and aggregates only when observed load requires them.

​
Required telemetry

Every run should expose run ID, chain, source, range/page, attempts, reductions, insert/update counts, cursor movement, safe-tip lag, duration, and classified errors. Alerts should cover stalled cursors, aging failure backlog, repeated reorg replay, RPC latency/rate limits, partial runs, database pool saturation, stale readiness, unexpected auth failures, Soroban event lag, unresolved contract states, and control-plane/chain divergence.

​
23. Deployment architecture

API, workers, web, console, docs, and database migrations are independent deployment units. Use HTTPS, restricted database networking, non-root runtimes, resource limits, health probes, centralized logs, primary/secondary RPCs, controlled migrations, and tested point-in-time recovery. Soroban deployment records should include environment, network, source revision, WASM hash, verified contract ID, deployment ledger/transaction, administrator and upgrade policy, configuration version, and audit version.

​
24. Disaster recovery and reconciliation

PostgreSQL requires encrypted backups, point-in-time recovery, defined RPO/RTO, retained migration history, and recurring restoration tests. Preserve control-plane, provider, compliance, submission, event, evidence, and audit records according to policy. Derived blockchain data can be rebuilt from verified checkpoints and bounded backfills, but RPC archival availability cannot be the sole backup. After restoration, reconcile database state against BSC safe tips, Solana signatures, future Stellar ledgers, Soroban contract state/events, provider evidence, and control-plane terminal states before reopening value-changing operations.

​
25. Testing architecture

​
Current platform

  • Unit-test address normalization, cursor identity, exact decimals, password/OTP/session controls, validation, route authorization, range adaptation, pairing semantics, and metrics.
  • Use deterministic BSC log and parsed Solana transaction fixtures.
  • Integration-test migrations, duplicates, rewind, atomic checkpoints, advisory locks, partial runs, readiness failure, permission denial, CSRF, rate limits, and recovery against PostgreSQL.
  • Run bounded staging backfills against archival RPC providers.

​
Future Stellar/Soroban platform

  • Unit-test every state transition and authorization branch.
  • Property-test exact amounts, terminal-state exclusivity, nonce uniqueness, limits, and deadlines.
  • Fuzz contract inputs, authorization trees, events, and upgrade/migration paths.
  • Integration-test simulation, signing, submission, timeout recovery, fee/resource limits, event replay, and reconciliation.
  • Test malicious tokens/contracts, unauthorized signers, stale payloads, duplicate submissions, network mismatch, provider failure, refund/claim races, disputes, pauses, and recovery.
  • Complete independent contract and application audits and retest remediations.

​
26. Current limitations

  • No Stellar client, Horizon/RPC integration, asset configuration, transaction submitter, or event indexer exists in this repository.
  • A Soroban MVP is deployed at CDTDCQ2Y6OASQVJGOFBA2EHP3AV7N6FFULJNEFGMORLYMNHECX7OO2W6. Its current live WASM matches the public artifact built from source commit 60489c3, with upload and upgrade evidence recorded through the settlement-aggregator-protocol submodule. Generated application bindings and independent security review remain incomplete.
  • No authoritative payment, quote, provider-assignment, payout, refund, or dispute lifecycle exists.
  • Compliance supports a business draft foundation, not complete screening or review operations.
  • Solana historical pagination, retry processing, Token-2022, and source coverage are incomplete.
  • Live safe-tip chain lag is not surfaced to users.
  • Heuristic pairing is non-authoritative.
  • Operational read endpoints need stronger deployment authorization.
  • Current automated coverage and production telemetry are insufficient for funds-at-risk production.

​
27. Delivery phases

  1. Harden current foundations: complete Solana coverage and retries, chain-lag telemetry, operator access, test fixtures, worker separation, and recovery drills.
  2. Specify and harden Stellar/Soroban: use the mainnet MVP as evidence while freezing asset identity, state machines, authorization, events, upgrades, privacy, fee policy, and threat model for its successor.
  3. Build test environment: implement the hardened contract, clients, signer/submitter, event indexer, explicit references, and reconciliation.
  4. Implement payment orchestration: add requests, rate locks, provider capacity/assignment, compliance gates, fiat adapters, evidence, refunds, disputes, and full APIs.
  5. Conduct security review: execute property/fuzz/integration testing and independent contract/application audits.
  6. Run controlled pilot: restrict providers, corridors, assets, amounts, and exposure with human monitoring and independent reconciliation.
  7. Operate production: require governed upgrades, production key management, redundant infrastructure, formal corridor approval, SLOs, on-call ownership, and tested incident response.

​
28. Production-readiness gates

​
Visibility and platform

  • Bounded Solana history, source discovery, Token-2022, and retry worker complete.
  • Redundant archival RPC providers and measured failover operational.
  • Chain and contract lag visible with actionable alerts.
  • All operational endpoints use durable, least-privilege authorization.
  • PostgreSQL migrations, backups, PITR, and restoration drills verified.
  • End-to-end duplicate, replay, reorg, outage, and partial-run tests pass.
  • Shared rate limiting, secret rotation, CORS, audit, and retention policies deployed.

​
Payment and provider control plane

  • Authoritative requests, quotes, assignments, evidence, payouts, refunds, disputes, and reconciliation implemented.
  • Exact amount handling and idempotency verified across every external boundary.
  • KYC/KYB, screening, corridor, limit, monitoring, and case policy approved.
  • Provider due diligence, capacity tests, service levels, suspension, and exit processes complete.
  • Legal and licensing eligibility confirmed for every production corridor and product.

​
Stellar and Soroban

  • Network, assets, state machine, authorization graph, events, deadlines, upgrades, pause, and recovery frozen.
  • Contract, client, submitter, event indexer, and reconciliation implemented and tested.
  • Property, fuzz, invariant, replay, timeout, adversarial, and migration suites pass.
  • Independent audits completed and all critical/high findings closed and retested.
  • Signing material protected by production key management and least privilege.
  • Deployment artifacts, source, WASM hash, contract IDs, and configuration independently verified.
  • Pilot limits, monitoring, incident ownership, rollback, and communications rehearsed.

​
29. Architectural conclusion

Oynk’s core architectural principle is separation of authority. Applications express intent; the control plane owns policy and lifecycle; providers execute bounded legs; Soroban is intended to enforce narrowly defined on-chain settlement transitions; indexers report ledger facts; and reconciliation determines whether all referenced obligations agree. The current repository provides meaningful identity, compliance, observability, indexing, and presentation foundations, and the separate mainnet MVP proves execution of the initial Soroban settlement lifecycle. Oynk is not yet an end-to-end, audited Stellar payment platform. Moving production funds safely requires integrating and hardening the contract and control-plane layers, preserving exactness and replay safety, proving authorization invariants, independently reviewing the system, and launching within narrow operational and regulatory limits.