SDK Recipes: @omegax/protocol-sdk

These recipes are copy-paste starting points for common external integrations. Use createSafeProtocolClient(...) by default. Use raw builders, dynamic instruction construction, or custom program IDs only for test workflows or advanced integrations that have a specific reason to bypass the safe client.

Start With The CLI

npx @omegax/protocol-sdk doctor
npx @omegax/protocol-sdk scaffold node-backend --out omegax-provider-backend
npx @omegax/protocol-sdk scaffold next-route --out omegax-health-route
npx @omegax/protocol-sdk scaffold oracle-worker --out omegax-oracle-worker

Expected output: doctor should report passing checks without requiring a funded wallet, private key, or transaction submission.

Next step: choose one scaffold, install dependencies, and run the scaffold's documented smoke check before adding funded or signing flows.

Node Backend

Install:

npx @omegax/protocol-sdk scaffold node-backend --out omegax-provider-backend
cd omegax-provider-backend
npm install

import {
  PROTOCOL_PROGRAM_ID,
  createConnection,
  createSafeProtocolClient,
  deriveReserveDomainPda,
  getOmegaXNetworkInfo,
} from '@omegax/protocol-sdk';

const networkInfo = getOmegaXNetworkInfo('devnet');
const connection = createConnection({
  network: 'devnet',
  rpcUrl: process.env.SOLANA_RPC_URL ?? networkInfo.defaultRpcUrl,
  commitment: 'confirmed',
});
const protocol = createSafeProtocolClient(connection, {
  programId: PROTOCOL_PROGRAM_ID,
});

export function reserveDomainAddress(domainId: string) {
  return deriveReserveDomainPda({
    domainId,
    programId: protocol.getProgramId(),
  }).toBase58();
}

Expected output: a JSON status payload with network, programId, reserveDomain, healthPlan, instruction count, and account count.

Next step: wire the status helper into your backend route and keep all funded or signing flows behind explicit user approval and server-side validation.

Next.js Server Route

Install:

npx @omegax/protocol-sdk scaffold next-route --out omegax-health-route

import { NextResponse } from 'next/server';
import {
  PROTOCOL_PROGRAM_ID,
  createConnection,
  createSafeProtocolClient,
  listProtocolAccountNames,
  listProtocolInstructionNames,
} from '@omegax/protocol-sdk';

export async function GET() {
  const protocol = createSafeProtocolClient(
    createConnection({
      network: 'devnet',
      rpcUrl: process.env.SOLANA_RPC_URL,
    }),
    { programId: PROTOCOL_PROGRAM_ID },
  );

  return NextResponse.json({
    programId: protocol.getProgramId().toBase58(),
    instructions: listProtocolInstructionNames(),
    accounts: listProtocolAccountNames(),
  });
}

Expected output: the GET route returns protocol metadata without any signer.

Next step: move the generated route into your application and replace demo identifiers with plan, reserve, and policy identifiers that your integration controls.

Oracle Worker

Install:

npx @omegax/protocol-sdk scaffold oracle-worker --out omegax-oracle-worker
cd omegax-oracle-worker
npm install

import {
  PROTOCOL_PROGRAM_ID,
  attestProtocolOutcome,
  createOracleSignerFromEnv,
} from '@omegax/protocol-sdk';

const signer = createOracleSignerFromEnv();

export async function attestClaimOutcome(params: {
  healthPlan: string;
  fundingLine: string;
  claimCase: string;
  nonce: string;
}) {
  return await attestProtocolOutcome({
    userId: 'member-001',
    cycleId: 'claim-cycle-001',
    outcomeId: 'claim-supported',
    payload: {
      decision: 'support_approve',
      approvedAmountRaw: '150000000',
    },
    context: {
      network: 'devnet',
      programId: PROTOCOL_PROGRAM_ID,
      healthPlan: params.healthPlan,
      fundingLine: params.fundingLine,
      claimCase: params.claimCase,
      schemaKeyHashHex: 'ab'.repeat(32),
      audience: 'claim-intake-service',
      nonce: params.nonce,
      asOfIso: new Date().toISOString(),
      expiresAtIso: new Date(Date.now() + 5 * 60_000).toISOString(),
    },
    signer,
  });
}

Expected output: a protocol-bound attestation verifies locally and prints an attestation ID plus digest.

Next step: replace the in-memory demo signer with KMS or secret-manager wiring and keep signer material out of tracked files.

Read-Only Frontend

Install:

npm install @omegax/protocol-sdk

import {
  createConnection,
  deriveHealthPlanPda,
  deriveReserveDomainPda,
  getOmegaXNetworkInfo,
  listProtocolAccountNames,
} from '@omegax/protocol-sdk';

const networkInfo = getOmegaXNetworkInfo('devnet');
const connection = createConnection({
  network: 'devnet',
  rpcUrl: networkInfo.defaultRpcUrl,
});

const reserveDomain = deriveReserveDomainPda({ domainId: 'open-usdc-domain' });
const healthPlan = deriveHealthPlanPda({
  reserveDomain,
  planId: 'genesis-protect-acute',
});

console.log({
  rpcEndpoint: connection.rpcEndpoint,
  healthPlan: healthPlan.toBase58(),
  accountTypes: listProtocolAccountNames(),
});

Expected output: a read-only status object with an RPC endpoint, derived health plan PDA, and known account types.

Next step: move RPC calls that need secrets, signing, or privileged context into a backend route.

Typed Error Handling

import {
  OmegaXError,
  OmegaXProgramMismatchError,
  createConnection,
  createSafeProtocolClient,
} from '@omegax/protocol-sdk';

try {
  createSafeProtocolClient(createConnection(), {
    programId: '11111111111111111111111111111111',
  });
} catch (error) {
  if (error instanceof OmegaXProgramMismatchError) {
    console.error(error.code, error.details);
  } else if (error instanceof OmegaXError) {
    console.error(error.code, error.message);
  } else {
    throw error;
  }
}

Integration Smoke

Before adding funded flows, keep a read-only smoke in your own application that imports the SDK, creates a safe client, checks network metadata, and lists the public instruction and account names. That catches package, ESM, and network configuration issues before users sign transactions.