Skip to main content

SDK Workflows

These workflows map the OmegaX economic model to the SDK builders and readers.

Use them by workflow rather than reading the entire catalog in protocol-object order.

Use this page when you already know the integration lane and need the exact builders, readers, and helpers for that workflow.

These workflows describe the public SDK and protocol model on Solana devnet beta. OmegaX-built product availability, posted reserve, and claim-review staffing are separate from what the builders can express.

Workflow map​

PathUse it forPrimary objects
Path AOracle registration, schema operations, and claim-case attestations.Oracle profiles, pool oracle policy, outcome schemas, claim attestations.
Path BApp-facing member, claim, obligation, and payout state.Member positions, claim cases, obligations, reserve ledgers.
Path CSponsor programs, reserve domains, liquidity pools, capital classes, and allocations.Reserve domains, plans, funding lines, pools, classes, LP positions, allocations.

Shared integration pattern​

  1. Create connection, protocol, and rpc clients.
  2. Derive addresses with PDA helpers.
  3. Build unsigned transactions with build...Tx(...).
  4. Sign with your wallet or signer stack.
  5. Broadcast with broadcastSignedTx(...).
  6. Verify state with fetch...(...) readers and reserve-model helpers.

Use createSafeProtocolClient(...) for production and settlement flows. Raw createProtocolClient(...) builders are useful for protocol engineering and tests, but production flows should stay on the safe layer unless an explicit unsafe custom-program override is part of a devnet or localnet workflow.

Runnable starting points:

  • npm run example:smoke for a no-signature safe-client import and PDA smoke.
  • npm run example:app for member, claim, and obligation read-model shaping.
  • npm run example:oracle for protocol-bound oracle attestation signing and verification.

Path A: Oracle and event producers​

Use this path when your service needs to normalize private inputs into OmegaX-compatible outcome events and policy-bound oracle actions.

Workflow A1: Oracle and schema registry operations​

Use this when an oracle service needs to register metadata, configure pool oracle controls, or manage the schema registry.

Builders:

  • buildRegisterOracleTx(...)
  • buildClaimOracleTx(...)
  • buildUpdateOracleProfileTx(...)
  • buildSetPoolOracleTx(...)
  • buildSetPoolOraclePermissionsTx(...)
  • buildSetPoolOraclePolicyTx(...)
  • buildRegisterOutcomeSchemaTx(...)
  • buildVerifyOutcomeSchemaTx(...)
  • buildBackfillSchemaDependencyLedgerTx(...)
  • buildCloseOutcomeSchemaTx(...)

Readers:

  • fetchOracleProfile(...)
  • fetchPoolOracleApproval(...)
  • fetchPoolOraclePolicy(...)
  • fetchPoolOraclePermissionSet(...)
  • fetchOutcomeSchema(...)
  • fetchSchemaDependencyLedger(...)

Workflow A2: Oracle attestation and claim-case services​

Use this when an external oracle worker or service needs a stable signing surface for outcome attestations or must anchor a schema-bound decision against an active claim case.

Builders and helpers:

  • buildAttestClaimCaseTx(...)
  • createOracleSignerFromEnv(...)
  • createOracleSignerFromKmsAdapter(...)
  • attestOutcome(...)
  • attestProtocolOutcome(...)
  • verifyOracleAttestation(...)
  • verifyProtocolOracleAttestation(...)

Use attestProtocolOutcome(...) for settlement-critical claim evidence. It binds the signed payload to network, program ID, health plan, funding line, claim case, schema key hash, audience, nonce, issue time, as-of time, and expiry. Use verifyProtocolOracleAttestation(...) before settlement intake so the SDK checks signature, expiry, expected network/program/account IDs, audience, nonce, and optional pool/class/allocation scope together.

The SDK repo includes an offline oracle-attestation example that uses a KMS-style adapter without secrets or funded signers.

buildAttestClaimCaseTx(...) mirrors the current claim-attestation account list: oracle signer, protocol governance, health plan, oracle profile, writable claim case, funding line, outcome schema, optional pool oracle scope accounts, claim attestation, and system program. Pass the pool, capital class, allocation position, pool oracle approval, permission set, and policy accounts when the claim is scoped to LP capital.

Readers:

  • fetchClaimAttestation(...)
  • fetchClaimCase(...)
  • fetchOutcomeSchema(...)

Constants:

  • CLAIM_ATTESTATION_DECISION_SUPPORT_APPROVE
  • CLAIM_ATTESTATION_DECISION_SUPPORT_DENY
  • CLAIM_ATTESTATION_DECISION_REQUEST_REVIEW
  • CLAIM_ATTESTATION_DECISION_ABSTAIN
  • POOL_ORACLE_PERMISSION_ATTEST_CLAIM

Path B: Health / wallet / app builders​

Use this path when your app needs member, claim, obligation, and payout state without owning the entire sponsor or capital stack.

Workflow B1: Protection claims and premium flows​

Use this when a policy series needs explicit premium intake, claim review, claim attestation visibility, and settlement consequences.

Builders:

  • buildRecordPremiumPaymentTx(...)
  • buildOpenClaimCaseTx(...)
  • buildAttachClaimEvidenceRefTx(...)
  • buildAdjudicateClaimCaseTx(...)
  • buildSettleClaimCaseTx(...)
  • buildSettleClaimCaseSelectedAssetTx(...)
  • buildCreateObligationTx(...)
  • buildReserveObligationTx(...)
  • buildSettleObligationTx(...)

Readers:

  • fetchClaimCase(...)
  • fetchClaimAttestation(...)
  • fetchObligation(...)
  • fetchFundingLineLedger(...)
  • fetchPlanReserveLedger(...)
  • fetchSeriesReserveLedger(...)

Helpers:

  • normalizeClaimSimulationFailure(...)
  • normalizeClaimRpcFailure(...)
  • validateSignedClaimTx(...)

validateSignedClaimTx(...) checks a submitted signed transaction against a server-stored unsigned transaction plus a nonce-bearing, expiring claim intent before intake trusts the signer. Use exact-message mode for higher-risk settlement flows; wallet flows may allow blockhash-only refresh when the rest of the message still matches.

The SDK repo includes a deterministic app-builder read-model example for shaping member, claim, and obligation snapshots into user-facing state.

Workflow B2: Member read models​

Use this when you want wallet-facing or app-facing views rather than raw account objects.

Helpers:

  • buildMemberReadModel(...)
  • describeEligibilityStatus(...)
  • describeClaimStatus(...)
  • describeObligationStatus(...)
  • shortenAddress(...)

Note:

  • buildOpenMemberPositionTx(...) lives in the sponsor-funded plan workflow below because the same canonical builder can be used by app-facing products or sponsor-controlled products depending on plan configuration.

Path C: Sponsor and capital integrators​

Use this path when you need to create the settlement boundary, launch sponsor programs, or connect LP capital to those lanes.

Workflow C1: Governance and reserve-domain bootstrap​

Use this when preparing the settlement boundary for a new domain and asset.

buildCreateDomainAssetVaultTx(...) derives the protocol-owned SPL vault token account at the canonical domain_asset_vault_token PDA. Do not create or pass an admin-owned token account; the protocol initializes the PDA-owned account inline.

Reserve asset rails are first-class protocol objects. Use buildConfigureReserveAssetRailTx(...) to set the role, oracle source, decimals, and bounds for an asset, then buildPublishReserveAssetRailPriceTx(...) when a governance or oracle source publishes the current reserve price. deriveReserveAssetRailPda(...) gives clients the rail address.

Builders:

  • buildInitializeProtocolGovernanceTx(...)
  • buildRotateProtocolGovernanceAuthorityTx(...)
  • buildAcceptProtocolGovernanceAuthorityTx(...)
  • buildCancelProtocolGovernanceAuthorityTransferTx(...)
  • buildSetProtocolEmergencyPauseTx(...)
  • buildCreateReserveDomainTx(...)
  • buildUpdateReserveDomainControlsTx(...)
  • buildCreateDomainAssetVaultTx(...)
  • buildConfigureReserveAssetRailTx(...)
  • buildPublishReserveAssetRailPriceTx(...)
  • buildInitProtocolFeeVaultTx(...)
  • buildWithdrawProtocolFeeSolTx(...)
  • buildWithdrawProtocolFeeSplTx(...)
  • buildInitPoolTreasuryVaultTx(...)
  • buildInitPoolOracleFeeVaultTx(...)

Readers:

  • fetchProtocolGovernance(...)
  • fetchReserveDomain(...)
  • fetchDomainAssetVault(...)
  • fetchDomainAssetLedger(...)
  • fetchReserveAssetRail(...)

PDA helpers:

  • deriveReserveAssetRailPda(...)
  • deriveProtocolFeeVaultPda(...)
  • derivePoolTreasuryVaultPda(...)
  • derivePoolOracleFeeVaultPda(...)

Workflow C2: Sponsor-funded health plan​

Use this for sponsor budgets, reward programs, or early-stage plans that do not need LP capital.

Sponsor budget and premium builders move tokens as part of the instruction. Provide the payer source token account, canonical domain vault token account, asset mint, and token program alongside the reserve ledgers. Premium and claim-settlement fee flows also require the matching protocol or oracle fee-vault accounts when fees are configured.

Production integrations should prefer createSafeProtocolClient(...) for sponsor funding, premium payment, settlement, fee withdrawal, and treasury withdrawal flows. The safe layer derives PDA-owned vaults, enforces classic SPL Token accounts, and preflights token-account mint and owner where a Connection is available. Safe settlement additionally requires recipientOwnerAddress so the payout token account owner is checked before signing.

Builders:

  • buildCreateHealthPlanTx(...)
  • buildUpdateHealthPlanControlsTx(...)
  • buildCreatePolicySeriesTx(...)
  • buildInitializeSeriesReserveLedgerTx(...)
  • buildVersionPolicySeriesTx(...)
  • buildOpenMemberPositionTx(...)
  • buildUpdateMemberEligibilityTx(...)
  • buildOpenFundingLineTx(...)
  • buildFundSponsorBudgetTx(...)
  • buildRecordPremiumPaymentTx(...)
  • buildOpenClaimCaseTx(...)
  • buildAdjudicateClaimCaseTx(...)
  • buildSettleClaimCaseTx(...)
  • buildSettleClaimCaseSelectedAssetTx(...)
  • buildCreateObligationTx(...)
  • buildReserveObligationTx(...)
  • buildSettleObligationTx(...)
  • buildReleaseReserveTx(...)

Readers:

  • fetchHealthPlan(...)
  • fetchPolicySeries(...)
  • fetchMemberPosition(...)
  • fetchFundingLine(...)
  • fetchFundingLineLedger(...)
  • fetchClaimCase(...)
  • fetchPlanReserveLedger(...)
  • fetchSeriesReserveLedger(...)
  • fetchObligation(...)

Helpers:

  • recomputeReserveBalanceSheet(...)
  • buildSponsorReadModel(...)

Workflow C3: LP capital, classes, and redemptions​

Use this when capital providers enter through liquidity pools and capital classes.

LP deposits transfer the deposited asset into the configured domain vault before shares are credited. Redemption requests and queue processing pass shares only; the program derives asset payout from class NAV and queued redemption state.

Production integrations should use createSafeProtocolClient(...) for LP deposits, redemption requests, and redemption queue processing so pool class ledger, LP position, vault, and treasury accounts are derived consistently.

Builders:

  • buildCreateLiquidityPoolTx(...)
  • buildCreateCapitalClassTx(...)
  • buildUpdateLpPositionCredentialingTx(...)
  • buildUpdateCapitalClassControlsTx(...)
  • buildDepositIntoCapitalClassTx(...)
  • buildRequestRedemptionTx(...)
  • buildProcessRedemptionQueueTx(...)

Readers:

  • fetchLiquidityPool(...)
  • fetchCapitalClass(...)
  • fetchPoolClassLedger(...)
  • fetchLPPosition(...)
  • fetchDomainAssetLedger(...)

Helpers:

  • recomputeReserveBalanceSheet(...)
  • buildCapitalReadModel(...)

Workflow C4: Allocation and impairment​

Use this when LP capital is bridged into plan-side funding lines.

Builders:

  • buildCreateAllocationPositionTx(...)
  • buildUpdateAllocationCapsTx(...)
  • buildAllocateCapitalTx(...)
  • buildDeallocateCapitalTx(...)
  • buildMarkImpairmentTx(...)

Readers:

  • fetchAllocationPosition(...)
  • fetchAllocationLedger(...)
  • fetchCapitalClass(...)
  • fetchFundingLine(...)
  • fetchObligation(...)

Next read​