@omegax/protocol-sdk 0.4.0

package/dist/claims.js

@@ -0,0 +1,361 @@
+import bs58 from 'bs58';
+import nacl from 'tweetnacl';
+import { PublicKey, SystemProgram, Transaction, TransactionInstruction, } from '@solana/web3.js';
+import { anchorDiscriminator, encodeU64Le, fromHex, hashStringTo32, } from './utils.js';
+import { deriveClaimDelegatePda, deriveClaimPda, deriveClaimV2Pda, deriveConfigV2Pda, deriveOutcomeAggregatePda, derivePoolOraclePolicyPda, derivePoolTermsPda, deriveCycleWindowPda, deriveCycleOutcomePda, deriveMembershipPda, } from './protocol_seeds.js';
+const SUBMIT_CLAIM_DISCRIMINATOR = anchorDiscriminator('global', 'submit_claim');
+const SUBMIT_REWARD_CLAIM_DISCRIMINATOR = anchorDiscriminator('global', 'submit_reward_claim');
+function validateRewardClaimOptionalAccounts(params) {
+    const providedCount = [
+        params.poolAssetVault,
+        params.poolVaultTokenAccount,
+        params.recipientTokenAccount,
+    ].filter((value) => typeof value === 'string' && value.length > 0).length;
+    if (providedCount !== 0 && providedCount !== 3) {
+        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 ruleHash = fromHex(params.ruleHashHex, 32);
+    const intentHash = fromHex(params.intentHashHex, 32);
+    return Buffer.concat([
+        SUBMIT_REWARD_CLAIM_DISCRIMINATOR,
+        new PublicKey(params.member).toBuffer(),
+        Buffer.from(cycleHash),
+        Buffer.from(ruleHash),
+        Buffer.from(intentHash),
+        encodeU64Le(params.payoutAmount),
+        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 ruleHash = fromHex(params.ruleHashHex, 32);
+    const [configV2Pda] = deriveConfigV2Pda(programId);
+    const [poolTermsPda] = derivePoolTermsPda({
+        programId,
+        poolAddress,
+    });
+    const [poolOraclePolicyPda] = derivePoolOraclePolicyPda({
+        programId,
+        poolAddress,
+    });
+    const [membershipPda] = deriveMembershipPda({
+        programId,
+        poolAddress,
+        member,
+    });
+    const [aggregatePda] = deriveOutcomeAggregatePda({
+        programId,
+        poolAddress,
+        member,
+        cycleHash,
+        ruleHash,
+    });
+    const [claimRecordV2Pda] = deriveClaimV2Pda({
+        programId,
+        poolAddress,
+        member,
+        cycleHash,
+        ruleHash,
+    });
+    const [claimDelegatePda] = deriveClaimDelegatePda({
+        programId,
+        poolAddress,
+        member,
+    });
+    const optionPlaceholder = programId;
+    const claimDelegateAccount = params.claimDelegate ? claimDelegatePda : optionPlaceholder;
+    const poolAssetVaultAccount = params.poolAssetVault
+        ? new PublicKey(params.poolAssetVault)
+        : optionPlaceholder;
+    const poolVaultTokenAccount = params.poolVaultTokenAccount
+        ? new PublicKey(params.poolVaultTokenAccount)
+        : optionPlaceholder;
+    const recipientTokenAccount = params.recipientTokenAccount
+        ? new PublicKey(params.recipientTokenAccount)
+        : optionPlaceholder;
+    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 },
+        ],
+        programId,
+        data: serializeSubmitRewardClaimPayload(params),
+    });
+    const tx = new Transaction({
+        recentBlockhash: params.recentBlockhash,
+        feePayer: claimant,
+    }).add(instruction);
+    const unsignedTxBase64 = tx
+        .serialize({ requireAllSignatures: false, verifySignatures: false })
+        .toString('base64');
+    return {
+        intentHashHex: Buffer.from(fromHex(params.intentHashHex, 32)).toString('hex'),
+        unsignedTxBase64,
+        requiredSigner: claimant.toBase58(),
+    };
+}
+function firstSignatureBase58(tx) {
+    if (tx.signatures.length === 0)
+        return null;
+    const first = tx.signatures[0];
+    if (!first?.signature)
+        return null;
+    return bs58.encode(first.signature);
+}
+export function validateSignedClaimTx(params) {
+    let tx;
+    try {
+        tx = Transaction.from(Buffer.from(params.signedTxBase64, 'base64'));
+    }
+    catch {
+        return {
+            valid: false,
+            txSignature: null,
+            reason: 'invalid_transaction_base64',
+            signer: null,
+        };
+    }
+    if (typeof params.expectedUnsignedTxBase64 === 'string' && params.expectedUnsignedTxBase64.length > 0) {
+        try {
+            const expectedUnsignedTx = Transaction.from(Buffer.from(params.expectedUnsignedTxBase64, 'base64'));
+            const signedMessageBytes = tx.serializeMessage();
+            const expectedMessageBytes = expectedUnsignedTx.serializeMessage();
+            if (signedMessageBytes.length !== expectedMessageBytes.length
+                || !signedMessageBytes.every((value, index) => value === expectedMessageBytes[index])) {
+                return {
+                    valid: false,
+                    txSignature: firstSignatureBase58(tx),
+                    reason: 'intent_message_mismatch',
+                    signer: tx.feePayer?.toBase58() ?? null,
+                };
+            }
+        }
+        catch {
+            return {
+                valid: false,
+                txSignature: firstSignatureBase58(tx),
+                reason: 'intent_message_mismatch',
+                signer: tx.feePayer?.toBase58() ?? null,
+            };
+        }
+    }
+    const expectedSigner = params.requiredSigner.trim();
+    const signer = tx.feePayer?.toBase58() ?? null;
+    if (!signer) {
+        return {
+            valid: false,
+            txSignature: null,
+            reason: 'missing_fee_payer',
+            signer: null,
+        };
+    }
+    if (signer !== expectedSigner) {
+        return {
+            valid: false,
+            txSignature: firstSignatureBase58(tx),
+            reason: 'required_signer_mismatch',
+            signer,
+        };
+    }
+    const expectedPubkey = tx.signatures.find((s) => s.publicKey.toBase58() === expectedSigner);
+    if (!expectedPubkey || !expectedPubkey.signature) {
+        return {
+            valid: false,
+            txSignature: firstSignatureBase58(tx),
+            reason: 'missing_required_signature',
+            signer,
+        };
+    }
+    const ok = nacl.sign.detached.verify(tx.serializeMessage(), expectedPubkey.signature, new PublicKey(expectedSigner).toBytes());
+    if (!ok) {
+        return {
+            valid: false,
+            txSignature: firstSignatureBase58(tx),
+            reason: 'invalid_required_signature',
+            signer,
+        };
+    }
+    return {
+        valid: true,
+        txSignature: firstSignatureBase58(tx),
+        reason: null,
+        signer,
+    };
+}
+function lower(value) {
+    return value.toLowerCase();
+}
+export function mapValidationReasonToClaimFailure(reason) {
+    if (!reason)
+        return null;
+    if (reason === 'intent_message_mismatch')
+        return 'intent_message_mismatch';
+    if (reason === 'required_signer_mismatch')
+        return 'required_signer_mismatch';
+    return 'unknown';
+}
+export function normalizeClaimSimulationFailure(params) {
+    const logs = params.logs ?? [];
+    const logsText = lower(logs.join('\n'));
+    const errText = lower(params.err == null
+        ? ''
+        : typeof params.err === 'string'
+            ? params.err
+            : JSON.stringify(params.err));
+    const haystack = `${logsText}\n${errText}`;
+    if (haystack.includes('insufficientpoolliquidity')
+        || haystack.includes('insufficient funds')
+        || haystack.includes('insufficient lamports')) {
+        return {
+            code: 'simulation_failed_insufficient_funds',
+            message: 'Pool does not have sufficient liquidity for this claim.',
+        };
+    }
+    if (haystack.includes('poolnotactive') || haystack.includes('pool is not active')) {
+        return {
+            code: 'simulation_failed_pool_paused',
+            message: 'Pool is paused or not active for claims.',
+        };
+    }
+    if (haystack.includes('membershipnotactive')
+        || haystack.includes('membership member mismatch')
+        || haystack.includes('membership')) {
+        return {
+            code: 'simulation_failed_membership_invalid',
+            message: 'Membership is not active for this pool.',
+        };
+    }
+    return {
+        code: 'simulation_failed_unknown',
+        message: 'Claim simulation failed before broadcast.',
+    };
+}
+export function normalizeClaimRpcFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const normalized = lower(message);
+    if (normalized.includes('timeout')
+        || normalized.includes('timed out')
+        || normalized.includes('blockhash not found')) {
+        return {
+            code: 'rpc_timeout',
+            message: message || 'RPC timeout while submitting claim transaction.',
+        };
+    }
+    return {
+        code: 'rpc_rejected',
+        message: message || 'RPC rejected claim transaction.',
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './utils.js';
+export * from './oracle.js';
+export * from './claims.js';
+export * from './rpc.js';
+export * from './protocol_seeds.js';
+export * from './protocol.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './utils.js';
+export * from './oracle.js';
+export * from './claims.js';
+export * from './rpc.js';
+export * from './protocol_seeds.js';
+export * from './protocol.js';

package/dist/oracle.d.ts

@@ -0,0 +1,22 @@
+import type { OracleSigner, OracleKmsSignerAdapter, OutcomeAttestation } from './types.js';
+export type AttestOutcomeParams = {
+    userId: string;
+    cycleId: string;
+    outcomeId: string;
+    asOfIso: string;
+    payload: Record<string, unknown>;
+    signer: OracleSigner;
+    submitAttestation?: (attestation: OutcomeAttestation) => Promise<{
+        txSignature?: string;
+    }>;
+};
+export type AttestOutcomeResult = {
+    attestation: OutcomeAttestation;
+    txSignature: string | null;
+};
+export declare function createOracleSignerFromEnv(params?: {
+    keyIdEnv?: string;
+    secretKeyBase58Env?: string;
+}): OracleSigner;
+export declare function createOracleSignerFromKmsAdapter(adapter: OracleKmsSignerAdapter): OracleSigner;
+export declare function attestOutcome(params: AttestOutcomeParams): Promise<AttestOutcomeResult>;

package/dist/oracle.js

@@ -0,0 +1,82 @@
+import bs58 from 'bs58';
+import nacl from 'tweetnacl';
+import { newId, nowIso, sha256Hex, stableStringify, toIsoString } from './utils.js';
+export function createOracleSignerFromEnv(params) {
+    const keyIdEnv = params?.keyIdEnv ?? 'ORACLE_SIGNER_KEY_ID';
+    const secretKeyEnv = params?.secretKeyBase58Env ?? 'ORACLE_SIGNER_SECRET_KEY_BASE58';
+    const keyId = String(process.env[keyIdEnv] || '').trim();
+    const secretKeyBase58 = String(process.env[secretKeyEnv] || '').trim();
+    if (!keyId) {
+        throw new Error(`Missing ${keyIdEnv}`);
+    }
+    if (!secretKeyBase58) {
+        throw new Error(`Missing ${secretKeyEnv}`);
+    }
+    const secretKeyBytes = bs58.decode(secretKeyBase58);
+    if (secretKeyBytes.length !== nacl.sign.secretKeyLength) {
+        throw new Error(`Invalid secret key length for ${secretKeyEnv}`);
+    }
+    const publicKeyBytes = secretKeyBytes.slice(32);
+    return {
+        keyId,
+        publicKeyBase58: bs58.encode(publicKeyBytes),
+        sign: async (message) => {
+            return nacl.sign.detached(message, secretKeyBytes);
+        },
+    };
+}
+export function createOracleSignerFromKmsAdapter(adapter) {
+    return {
+        keyId: adapter.keyId,
+        publicKeyBase58: adapter.publicKeyBase58,
+        sign: (message) => adapter.signWithKms(message),
+    };
+}
+function canonicalAttestationBody(params) {
+    return {
+        id: params.id,
+        userId: params.userId,
+        cycleId: params.cycleId,
+        outcomeId: params.outcomeId,
+        asOfIso: toIsoString(params.asOfIso),
+        issuedAtIso: toIsoString(params.issuedAtIso),
+        payload: params.payload,
+        verifier: {
+            keyId: params.verifierKeyId,
+            publicKeyBase58: params.verifierPublicKeyBase58,
+            algorithm: 'ed25519',
+        },
+    };
+}
+export async function attestOutcome(params) {
+    const id = newId('att');
+    const issuedAtIso = nowIso();
+    const body = canonicalAttestationBody({
+        id,
+        userId: params.userId,
+        cycleId: params.cycleId,
+        outcomeId: params.outcomeId,
+        asOfIso: params.asOfIso,
+        issuedAtIso,
+        payload: params.payload,
+        verifierKeyId: params.signer.keyId,
+        verifierPublicKeyBase58: params.signer.publicKeyBase58,
+    });
+    const canonical = stableStringify(body);
+    const message = new TextEncoder().encode(canonical);
+    const signature = await params.signer.sign(message);
+    const attestation = {
+        ...body,
+        signatureBase64: Buffer.from(signature).toString('base64'),
+        digestHex: sha256Hex(message),
+    };
+    let txSignature = null;
+    if (params.submitAttestation) {
+        const result = await params.submitAttestation(attestation);
+        txSignature = typeof result?.txSignature === 'string' ? result.txSignature : null;
+    }
+    return {
+        attestation,
+        txSignature,
+    };
+}

package/dist/protocol.d.ts

@@ -0,0 +1,9 @@
+import { Connection } from '@solana/web3.js';
+import type { ProtocolClient } from './types.js';
+export declare const PROTOCOL_PROGRAM_ID = "Bn6eixac1QEEVErGBvBjxAd6pgB9e2q4XHvAkinQ5y1B";
+export declare function createProtocolClient(connection: Connection, programIdInput: string): ProtocolClient;
+export declare function derivePoolAddress(params: {
+    programId: string;
+    authority: string;
+    poolId: string;
+}): string;