Settlement

Reference documentation for the settlement engine — routing intents to their exit targets, recording outcomes, and managing degraded connectivity.

Exit Targets

Settlement routes each intent to its configured exit target based on IntentType:

The caller must provide the exit target explicitly — there is no SDK default, forcing conscious choice of network (devnet, mainnet, custom).

Settling an Intent

Expo SDK

import { settle } from '@zypp-labs/expo-sdk';

// Settle on Solana mainnet
const result = settle(
  intentId,
  'https://api.mainnet-beta.solana.com',
  0 // exitType: 0 = SolanaRpc, 1 = DeveloperBackend, 2 = SolanaProgram
);

Unity SDK

var result = ZyppSdk.Settle(
  intent.intentId,
  "https://api.mainnet-beta.solana.com",
  ZyppExitType.SolanaRpc
);

Degraded Connectivity Routing

For apps operating in unreliable connectivity environments (events, transit, remote areas):

import { settleWithStrategy, reportConnectivity } from '@zypp-labs/expo-sdk';

// Report degraded connectivity
reportConnectivity('degraded');

// Settle with primary + degraded fallback
const result = settleWithStrategy(
  intentId,
  'https://rpc.mainnet.solana.com', 0,  // primary: Solana L1
  'https://rollup.example.com',      2,  // degraded: ephemeral rollup
);

Payment intents always route through the primary exit target regardless of connectivity. Payments must never be redirected through a degraded fallback.

Settlement Record

pub enum ExitOutcome {
    Accepted,    // Exit target accepted → SyncedProvisional
    Rejected,    // Exit target rejected → Failed
    RetryLater,  // Temporary failure → no state change, caller decides
}

Settlement records outcomes via record_outcome():

• Accepted → transitions to SyncedProvisional (will not downgrade a SyncedFinalized entry)
• Rejected → transitions to Failed with delivery or settlement failure stage
• RetryLater → no state change (temporary failure, caller decides retry timing)

State Machine Integration

The settlement engine interacts with the queue state machine:

Pending → settle() → SyncedProvisional → finalize() → SyncedFinalized
                        ↓
                     Failed

The transition to SyncedFinalized happens only after the exit target confirms finality. For payments on Solana L1, this means waiting for block confirmation.

Fee Estimation

// Estimate the SOL fee for settlement
const estimatedFee = await estimateFee(intentId);

Fees cover Solana transaction costs and vary based on network congestion.

ExitStrategy

pub struct ExitStrategy {
    pub primary: ExitTarget,   // Primary exit target
    pub degraded: Option<ExitTarget>,  // Fallback for degraded connectivity
}

pub enum ExitTarget {
    SolanaRpc { rpc_url: String },
    DeveloperBackend { endpoint_url: String },
    SolanaProgram { program_id: Pubkey, rpc_url: String },
}

The strategy is resolved based on connectivity quality:

Settlement Does Not Validate

Settlement routes intents based on IntentType, not trust tier or domain semantics. It does NOT:

• Verify cryptographic signatures (handled by sync engine)
• Check trust tier requirements (handled by templates)
• Enforce business rules (handled by exit target)

These are the responsibility of the exit target (L1 or developer backend).

Next Steps

• Build a Payment flow with settlement
• Configure Queues for offline persistence
• See Examples for full settlement workflows