@omegax/protocol-sdk 0.4.4 → 0.5.0

package/NOTICE

@@ -0,0 +1,5 @@
+OmegaX Health Protocol SDK
+Copyright (c) 2026 OMEGAX HEALTH FZCO and contributors
+
+Licensed under the Apache License, Version 2.0.
+This product includes software developed by OMEGAX HEALTH FZCO.

package/README.md

@@ -5,9 +5,9 @@ TypeScript SDK for OmegaX protocol integrations on Solana.
 ## Network status
 
 - Current live network: **devnet beta**
-- Mainnet support: **coming soon**
+- Public integration target: **devnet beta**
 - Protocol UI: https://protocol.omegax.health
-- Protocol repository: `omegaxhealth_protocol`
+- Protocol repository: `omegax-protocol`
 - Governance token:
   - Mainnet CA: `4Aar9R14YMbEie6yh8WcH1gWXrBtfucoFjw6SpjXpump`
   - Devnet: governance token distribution is via the protocol faucet
@@ -16,7 +16,7 @@ It supports:
 
 - Oracle lifecycle, staking, attestation voting, and reward claims
 - Pool creation, configuration, enrollment, funding, and reward claims
-- Coverage product and policy lifecycle (subscribe, premium, claim, settlement)
+- Policy series and policy position lifecycle (subscribe, premium, claim, settlement)
 - Deterministic PDA/seed derivation and account readers
 - Unsigned claim-intent building + signed message validation
 - RPC helpers for send/simulate/status workflows
@@ -38,6 +38,11 @@ It supports:
 npm install @omegax/protocol-sdk
 ```
 
+## Breaking change in `0.5.0`
+
+- Legacy and `V2` exported names were removed from the public SDK surface.
+- Use the current canonical protocol builders, readers, and PDA helpers only.
+
 ## Support matrix
 
 - Node.js `>=20`
@@ -49,7 +54,7 @@ npm install @omegax/protocol-sdk
 - Builders create **unsigned** transactions. Your app signs and submits them.
 - `programId` is explicit in SDK flows and should be passed from your runtime config.
 - Use `createProtocolClient(connection, programId)` for protocol operations.
-- `createConnection({ network: 'mainnet' })` is available but warns that mainnet is coming soon.
+- Keep integrations pointed at `devnet` until OmegaX announces public mainnet availability.
 
 ## Quickstart
 
@@ -76,7 +81,8 @@ const tx = protocol.buildSubmitRewardClaimTx!({
   claimant: '<claimant-pubkey>',
   poolAddress: '<pool-pubkey>',
   member: '<member-pubkey>',
-  cycleId: 'cycle-2026-01',
+  seriesRefHashHex: '<32-byte-hex>',
+  cycleHashHex: '<32-byte-hex>',
   ruleHashHex: '<32-byte-hex>',
   intentHashHex: '<32-byte-hex>',
   payoutAmount: 1n,
@@ -98,30 +104,31 @@ const result = await rpc.broadcastSignedTx({ signedTxBase64: signed });
 
 ### Pool creator / operator
 
-- Create and configure pools: `buildCreatePoolV2Tx`, `buildSetPoolStatusTx`, `buildSetPoolTermsHashTx`
-- Configure oracle policy/rules: `buildSetPoolOraclePolicyTx`, `buildSetPoolOutcomeRuleTx`, `buildSetPoolOracleTx`
+- Create and configure pools: `buildCreatePoolTx`, `buildSetPoolStatusTx`, `buildSetPoolTermsHashTx`
+- Configure oracle policy/rules: `buildSetPoolOraclePolicyTx`, `buildSetPolicySeriesOutcomeRuleTx`, `buildSetPoolOracleTx`
 - Fund payout liquidity: `buildFundPoolSolTx`, `buildFundPoolSplTx`
-- Manage coverage products: `buildRegisterCoverageProductV2Tx`, `buildUpdateCoverageProductV2Tx`
+- Manage policy series: `buildCreatePolicySeriesTx`, `buildUpdatePolicySeriesTx`
 
 ### Pool participant / member
 
 - Enroll: `buildEnrollMemberOpenTx`, `buildEnrollMemberTokenGateTx`, `buildEnrollMemberInvitePermitTx`
 - Authorize claim delegation: `buildSetClaimDelegateTx`
-- Claim rewards: `buildSubmitRewardClaimTx` (and legacy `buildSubmitClaimTx`)
-- Participate in coverage: `buildSubscribeCoverageProductV2Tx`, `buildCreateCoveragePolicyTx`, `buildIssueCoveragePolicyFromProductV2Tx`
+- Claim rewards: `buildSubmitRewardClaimTx`
+- Participate in policy series: `buildSubscribePolicySeriesTx`, `buildIssuePolicyPositionTx`, `buildPayPremiumSolTx`, `buildPayPremiumSplTx`
 
 ### Oracle operator
 
-- Register/update oracle: `buildRegisterOracleV2Tx`, `buildUpdateOracleProfileV2Tx`, `buildUpdateOracleMetadataTx`
+- Register/update oracle: `buildRegisterOracleTx`, `buildUpdateOracleProfileTx`, `buildUpdateOracleMetadataTx`
 - Stake lifecycle: `buildStakeOracleTx`, `buildRequestUnstakeTx`, `buildFinalizeUnstakeTx`, `buildSlashOracleTx`
 - Outcome + premium attestations: `buildSubmitOutcomeAttestationVoteTx`, `buildAttestPremiumPaidOffchainTx`
-- Claim oracle rewards: `buildClaimOracleV2Tx`
+- Claim oracle rewards: `buildClaimOracleTx`
 
 ### Coverage claims
 
 - Submit claim: `buildSubmitCoverageClaimTx`
+- Claim approved payout: `buildClaimApprovedCoveragePayoutTx`
 - Settle claim: `buildSettleCoverageClaimTx`
-- Premium payment: `buildPayPremiumOnchainTx`
+- Premium payment: `buildPayPremiumSolTx`, `buildPayPremiumSplTx`
 - Optional policy NFT mint: `buildMintPolicyNftTx`
 
 ## Module imports
@@ -146,11 +153,15 @@ Available subpaths: `claims`, `protocol`, `protocol_seeds`, `rpc`, `oracle`, `ty
 - `/docs/RELEASE.md` — versioning, CI gates, tag/publish flow
 - `/docs/DOCS_SYNC_WORKFLOW.md` — exact cross-repo docs sync workflow (`omegax-docs`)
 - `/docs/CROSS_REPO_RELEASE_ORDER.md` — commit message templates and release ordering
-- `/PROTOCOL_V2_PARITY_CHECKLIST.md` — protocol parity checklist
+- `/PROTOCOL_PARITY_CHECKLIST.md` — protocol parity checklist
 
 ## Protocol parity
 
-The SDK includes a strict instruction-account parity test against an Anchor IDL.
+The SDK includes:
+
+- a strict instruction-account parity test against an Anchor IDL
+- a live protocol-contract parity check when a local `omegax-protocol` workspace is present
+- a local protocol compatibility gate that runs an SDK smoke test plus the full protocol surface matrix through an SDK adapter
 
 - Default fixture path: `tests/fixtures/omegax_protocol.idl.json`
 - Optional local override:
@@ -165,6 +176,32 @@ Refresh the fixture:
 npm run sync:idl-fixture
 ```
 
+For the normal local workspace layout, this reads from:
+
+- `../omegax-protocol/idl/omegax_protocol.json`
+
+Run the full local compatibility gate before pushing SDK changes that may affect protocol behavior:
+
+```bash
+npm run verify:protocol:local
+```
+
+This verifies the current local `omegax-protocol` workspace state, including staged, unstaged, and untracked source changes, and records the exact workspace fingerprint it tested.
+
+For targeted localnet-only verification:
+
+```bash
+npm run test:protocol:localnet
+```
+
+If you changed SDK builders that are consumed by the oracle service, refresh the local dependency there after rebuilding the SDK:
+
+```bash
+cd ../omegaxhealth_services/services/protocol-oracle-service
+npm run sdk:refresh
+npm run sdk:check
+```
+
 Latest fixture sync metadata:
 
 - Source commit: `e32313b5c49fb06a609252f845845fcf2d49e98d`
@@ -179,12 +216,33 @@ npm pack --dry-run
 npm audit --omit=dev
 ```
 
+## Cross-repo sync
+
+Keep the repos aligned in this order:
+
+1. `omegax-protocol`
+2. `omegax-sdk`
+3. `protocol-oracle-service`
+4. `omegaxhealth_flutter` if the service DTO changed
+
+Practical rule:
+
+- protocol interface changes start in `omegax-protocol`
+- SDK mirrors the protocol interface and exposes the supported client surface
+- the oracle service refreshes the local SDK package and owns the app-facing Seeker DTO
+- Flutter only follows the service contract
+
 ## OSS docs
 
 - `CONTRIBUTING.md`
 - `SECURITY.md`
 - `CODE_OF_CONDUCT.md`
+- `AUTHORS.md`
 
 ## License
 
-Apache-2.0
+This SDK is licensed under Apache-2.0.
+
+The on-chain OmegaX protocol program lives in the separate `omegax-protocol` repository and is licensed independently under AGPL-3.0-or-later.
+
+Maintained by OMEGAX HEALTH FZCO with open-source contributors. Project initiated by Marino Sabijan, MD.

package/dist/claims.d.ts

@@ -1,5 +1,4 @@
-import type { BuildUnsignedClaimTxParams, BuildUnsignedRewardClaimTxParams, ClaimFailureCode, ClaimFailureDetail, ClaimIntent, RewardClaimIntent, ValidateSignedClaimTxReason, ValidateSignedClaimTxParams, ValidateSignedClaimTxResult } from './types.js';
-export declare function buildUnsignedClaimTx(params: BuildUnsignedClaimTxParams): ClaimIntent;
+import type { BuildUnsignedRewardClaimTxParams, ClaimFailureCode, ClaimFailureDetail, RewardClaimIntent, ValidateSignedClaimTxReason, ValidateSignedClaimTxParams, ValidateSignedClaimTxResult } from './types.js';
 export declare function buildUnsignedRewardClaimTx(params: BuildUnsignedRewardClaimTxParams): RewardClaimIntent;
 export declare function validateSignedClaimTx(params: ValidateSignedClaimTxParams): ValidateSignedClaimTxResult;
 export declare function mapValidationReasonToClaimFailure(reason: ValidateSignedClaimTxReason | null): ClaimFailureCode | null;

package/dist/claims.js

@@ -1,10 +1,12 @@
 import nacl from 'tweetnacl';
 import { PublicKey, SystemProgram, Transaction, TransactionInstruction, } from '@solana/web3.js';
-import { anchorDiscriminator, encodeU64Le, fromHex, hashStringTo32, } from './utils.js';
-import { decodeSolanaTransaction, solanaTransactionFirstSignature, solanaTransactionMessageBytes, solanaTransactionRequiredSigner, solanaTransactionSignerSignature, } from './transactions.js';
-import { deriveClaimDelegatePda, deriveClaimPda, deriveClaimV2Pda, deriveConfigV2Pda, deriveOutcomeAggregatePda, derivePoolOraclePolicyPda, derivePoolTermsPda, deriveCycleWindowPda, deriveCycleOutcomePda, deriveMembershipPda, } from './protocol_seeds.js';
-const SUBMIT_CLAIM_DISCRIMINATOR = anchorDiscriminator('global', 'submit_claim');
+import { anchorDiscriminator, encodeU64Le, fromHex, } from './utils.js';
+import { decodeSolanaTransaction, solanaTransactionFirstSignature, solanaTransactionIntentMessageBytes, solanaTransactionMessageBytes, solanaTransactionRequiredSigner, solanaTransactionSignerSignature, } from './transactions.js';
+import { deriveClaimPda, deriveConfigPda, deriveOutcomeAggregatePda, derivePoolCompliancePolicyPda, derivePoolOraclePolicyPda, derivePoolTreasuryReservePda, derivePoolTermsPda, deriveMembershipPda, ZERO_PUBKEY, } from './protocol_seeds.js';
 const SUBMIT_REWARD_CLAIM_DISCRIMINATOR = anchorDiscriminator('global', 'submit_reward_claim');
+function bytesEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
 function validateRewardClaimOptionalAccounts(params) {
     const providedCount = [
         params.poolAssetVault,
@@ -15,17 +17,8 @@ function validateRewardClaimOptionalAccounts(params) {
         throw new Error('poolAssetVault, poolVaultTokenAccount, and recipientTokenAccount must be provided together');
     }
 }
-function serializeSubmitClaimPayload(params) {
-    const cycleHash = hashStringTo32(params.cycleId);
-    const intentHash = hashStringTo32(params.intentId);
-    return Buffer.concat([
-        SUBMIT_CLAIM_DISCRIMINATOR,
-        Buffer.from(cycleHash),
-        Buffer.from(intentHash),
-    ]);
-}
 function serializeSubmitRewardClaimPayload(params) {
-    const cycleHash = hashStringTo32(params.cycleId);
+    const cycleHash = fromHex(params.cycleHashHex, 32);
     const ruleHash = fromHex(params.ruleHashHex, 32);
     const intentHash = fromHex(params.intentHashHex, 32);
     return Buffer.concat([
@@ -38,98 +31,17 @@ function serializeSubmitRewardClaimPayload(params) {
         new PublicKey(params.recipient).toBuffer(),
     ]);
 }
-export function buildUnsignedClaimTx(params) {
-    const claimant = new PublicKey(params.claimantWallet);
-    const programId = new PublicKey(params.programId);
-    const poolAddress = new PublicKey(params.poolAddress);
-    const cycleHash = hashStringTo32(params.cycleId);
-    const [membershipPda] = deriveMembershipPda({
-        programId,
-        poolAddress,
-        member: claimant,
-    });
-    const [cycleOutcomePda] = deriveCycleOutcomePda({
-        programId,
-        poolAddress,
-        member: claimant,
-        cycleHash,
-    });
-    const [claimPda] = deriveClaimPda({
-        programId,
-        poolAddress,
-        member: claimant,
-        cycleHash,
-    });
-    const [cycleWindowPda] = deriveCycleWindowPda({
-        programId,
-        poolAddress,
-        cycleHash,
-    });
-    const instruction = new TransactionInstruction({
-        keys: [
-            {
-                pubkey: claimant,
-                isSigner: true,
-                isWritable: true,
-            },
-            {
-                pubkey: poolAddress,
-                isSigner: false,
-                isWritable: true,
-            },
-            {
-                pubkey: membershipPda,
-                isSigner: false,
-                isWritable: false,
-            },
-            {
-                pubkey: cycleOutcomePda,
-                isSigner: false,
-                isWritable: true,
-            },
-            {
-                pubkey: cycleWindowPda,
-                isSigner: false,
-                isWritable: false,
-            },
-            {
-                pubkey: claimPda,
-                isSigner: false,
-                isWritable: true,
-            },
-            {
-                pubkey: SystemProgram.programId,
-                isSigner: false,
-                isWritable: false,
-            },
-        ],
-        programId,
-        data: serializeSubmitClaimPayload(params),
-    });
-    const tx = new Transaction({
-        recentBlockhash: params.recentBlockhash,
-        feePayer: claimant,
-    }).add(instruction);
-    const unsignedTxBase64 = tx
-        .serialize({ requireAllSignatures: false, verifySignatures: false })
-        .toString('base64');
-    return {
-        intentId: params.intentId,
-        unsignedTxBase64,
-        requiredSigner: claimant.toBase58(),
-        expiresAtIso: params.expiresAtIso,
-        attestationRefs: params.attestationRefs,
-    };
-}
 export function buildUnsignedRewardClaimTx(params) {
     validateRewardClaimOptionalAccounts(params);
     const claimant = new PublicKey(params.claimantWallet);
     const member = new PublicKey(params.member);
     const programId = new PublicKey(params.programId);
     const poolAddress = new PublicKey(params.poolAddress);
-    const cycleHash = hashStringTo32(params.cycleId);
+    const payoutMint = new PublicKey(params.payoutMint ?? ZERO_PUBKEY);
+    const cycleHash = fromHex(params.cycleHashHex, 32);
     const ruleHash = fromHex(params.ruleHashHex, 32);
-    const [configV2Pda] = deriveConfigV2Pda(programId);
+    const seriesRefHash = fromHex(params.seriesRefHashHex, 32);
+    const [configPda] = deriveConfigPda(programId);
     const [poolTermsPda] = derivePoolTermsPda({
         programId,
         poolAddress,
@@ -138,6 +50,11 @@ export function buildUnsignedRewardClaimTx(params) {
         programId,
         poolAddress,
     });
+    const [poolTreasuryReservePda] = derivePoolTreasuryReservePda({
+        programId,
+        poolAddress,
+        paymentMint: payoutMint,
+    });
     const [membershipPda] = deriveMembershipPda({
         programId,
         poolAddress,
@@ -146,24 +63,29 @@ export function buildUnsignedRewardClaimTx(params) {
     const [aggregatePda] = deriveOutcomeAggregatePda({
         programId,
         poolAddress,
+        seriesRefHash,
         member,
         cycleHash,
         ruleHash,
     });
-    const [claimRecordV2Pda] = deriveClaimV2Pda({
+    const [claimRecordPda] = deriveClaimPda({
         programId,
         poolAddress,
+        seriesRefHash,
         member,
         cycleHash,
         ruleHash,
     });
-    const [claimDelegatePda] = deriveClaimDelegatePda({
-        programId,
-        poolAddress,
-        member,
-    });
     const optionPlaceholder = programId;
-    const claimDelegateAccount = params.claimDelegate ? claimDelegatePda : optionPlaceholder;
+    const memberCycleAccount = params.memberCycle
+        ? new PublicKey(params.memberCycle)
+        : optionPlaceholder;
+    const cohortSettlementRootAccount = params.cohortSettlementRoot
+        ? new PublicKey(params.cohortSettlementRoot)
+        : optionPlaceholder;
+    const claimDelegateAccount = params.claimDelegate
+        ? new PublicKey(params.claimDelegate)
+        : optionPlaceholder;
     const poolAssetVaultAccount = params.poolAssetVault
         ? new PublicKey(params.poolAssetVault)
         : optionPlaceholder;
@@ -173,24 +95,39 @@ export function buildUnsignedRewardClaimTx(params) {
     const recipientTokenAccount = params.recipientTokenAccount
         ? new PublicKey(params.recipientTokenAccount)
         : optionPlaceholder;
+    const keys = [
+        { pubkey: claimant, isSigner: true, isWritable: true },
+        { pubkey: configPda, isSigner: false, isWritable: false },
+        { pubkey: poolAddress, isSigner: false, isWritable: true },
+        { pubkey: poolTermsPda, isSigner: false, isWritable: false },
+        { pubkey: poolOraclePolicyPda, isSigner: false, isWritable: false },
+        { pubkey: poolTreasuryReservePda, isSigner: false, isWritable: true },
+        { pubkey: membershipPda, isSigner: false, isWritable: false },
+        { pubkey: aggregatePda, isSigner: false, isWritable: true },
+        { pubkey: memberCycleAccount, isSigner: false, isWritable: false },
+        {
+            pubkey: cohortSettlementRootAccount,
+            isSigner: false,
+            isWritable: params.cohortSettlementRoot != null,
+        },
+        { pubkey: new PublicKey(params.recipientSystemAccount), isSigner: false, isWritable: true },
+        { pubkey: claimDelegateAccount, isSigner: false, isWritable: false },
+        { pubkey: poolAssetVaultAccount, isSigner: false, isWritable: false },
+        { pubkey: poolVaultTokenAccount, isSigner: false, isWritable: params.poolVaultTokenAccount != null },
+        { pubkey: recipientTokenAccount, isSigner: false, isWritable: params.recipientTokenAccount != null },
+        { pubkey: claimRecordPda, isSigner: false, isWritable: true },
+        { pubkey: new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'), isSigner: false, isWritable: false },
+        { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+        {
+            pubkey: params.includePoolCompliancePolicy
+                ? derivePoolCompliancePolicyPda({ programId, poolAddress })[0]
+                : programId,
+            isSigner: false,
+            isWritable: false,
+        },
+    ];
     const instruction = new TransactionInstruction({
-        keys: [
-            { pubkey: claimant, isSigner: true, isWritable: true },
-            { pubkey: configV2Pda, isSigner: false, isWritable: false },
-            { pubkey: poolAddress, isSigner: false, isWritable: true },
-            { pubkey: poolTermsPda, isSigner: false, isWritable: false },
-            { pubkey: poolOraclePolicyPda, isSigner: false, isWritable: false },
-            { pubkey: membershipPda, isSigner: false, isWritable: false },
-            { pubkey: aggregatePda, isSigner: false, isWritable: true },
-            { pubkey: new PublicKey(params.recipientSystemAccount), isSigner: false, isWritable: true },
-            { pubkey: claimDelegateAccount, isSigner: false, isWritable: false },
-            { pubkey: poolAssetVaultAccount, isSigner: false, isWritable: false },
-            { pubkey: poolVaultTokenAccount, isSigner: false, isWritable: params.poolVaultTokenAccount != null },
-            { pubkey: recipientTokenAccount, isSigner: false, isWritable: params.recipientTokenAccount != null },
-            { pubkey: claimRecordV2Pda, isSigner: false, isWritable: true },
-            { pubkey: new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'), isSigner: false, isWritable: false },
-            { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
-        ],
+        keys,
         programId,
         data: serializeSubmitRewardClaimPayload(params),
     });
@@ -225,14 +162,17 @@ export function validateSignedClaimTx(params) {
             const expectedUnsignedTx = decodeSolanaTransaction(params.expectedUnsignedTxBase64);
             const signedMessageBytes = solanaTransactionMessageBytes(tx);
             const expectedMessageBytes = solanaTransactionMessageBytes(expectedUnsignedTx);
-            if (signedMessageBytes.length !== expectedMessageBytes.length
-                || !signedMessageBytes.every((value, index) => value === expectedMessageBytes[index])) {
-                return {
-                    valid: false,
-                    txSignature: solanaTransactionFirstSignature(tx),
-                    reason: 'intent_message_mismatch',
-                    signer: solanaTransactionRequiredSigner(tx),
-                };
+            if (!bytesEqual(signedMessageBytes, expectedMessageBytes)) {
+                const signedIntentBytes = solanaTransactionIntentMessageBytes(tx);
+                const expectedIntentBytes = solanaTransactionIntentMessageBytes(expectedUnsignedTx);
+                if (!bytesEqual(signedIntentBytes, expectedIntentBytes)) {
+                    return {
+                        valid: false,
+                        txSignature: solanaTransactionFirstSignature(tx),
+                        reason: 'intent_message_mismatch',
+                        signer: solanaTransactionRequiredSigner(tx),
+                    };
+                }
             }
         }
         catch {