> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molpha.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Reference

> Exported types, derivation helpers, and the framework-agnostic EVM/Starknet verifier-argument builders.

## `RequestSignedDataOptions`

Options for `MolphaGateway.requestSignedData` and the second argument to `MolphaSDK.requestAndSubmit` (omit `feedId` there — it is the first argument):

```ts theme={null}
export interface RequestSignedDataOptions {
  feedId: string;
  signaturesRequired: number;
  apiConfig: APIConfig;
  subscriptionOwner?: string;
  consumerAuthority?: string;
  /** Override gateway auth signer for this call. */
  signer?: Signer;
  /** Encrypt private API secrets for selected nodes. */
  encrypt?: { secrets: Record<string, string> };
  /** Max accepted value age in seconds. Default 60. */
  maxAge?: number;
  /** Each retry re-rolls the timestamp. Default 15. */
  maxRetries?: number;
  /** Per-request timeout in ms. Default 5000. */
  timeoutMs?: number;
  /** Reuse registry + nodes from `prepareContext` (opt-in cache). */
  context?: Partial<RoundContext>;
  verifyNodeKeys?: NodeKeyVerifier;
  /** Unsafe: skip node-key auth for private APIs. Default false. */
  allowUnverifiedNodeKeysForPrivateApi?: boolean;
}
```

`apiConfig` must match the feed's committed configuration (same shape passed to `deriveApiConfigHash`). `maxAge` (seconds) lets the gateway return a cached result when one is fresh enough.

## `APIConfig`

```ts theme={null}
export interface APIConfig {
  url: string;
  method?: "GET" | "POST" | "PUT";
  headers?: Record<string, string>;
  responseParser: string;
  valueTransform?: string;
}
```

The SDK canonicalizes missing fields (`method` → `"GET"`, `headers` → `{}`, `valueTransform` → `""`) before hashing and before posting to the gateway.

## `RoundContext`

Returned by `sdk.gateway.prepareContext(feedId)` — pass it back via `requestSignedData({ ..., context })` so each round is a single gateway POST:

```ts theme={null}
export interface RoundContext {
  registryVersion: number;
  redundancyBuffer: number;
  nodes: Node[];
}
```

Caching is opt-in. Refresh when the on-chain registry version changes; a stale context produces a result the chain will reject.

## `DataUpdateResult`

A completed gateway round, ready to submit on-chain:

```ts theme={null}
export interface DataUpdateResult {
  feedId: string;
  /** Human-readable value. */
  value: string;
  /** 32-byte packed value, hex. */
  valuePacked: string;
  /** canonicalTimestamp (seconds). */
  timestamp: number;
  registryVersion: number;
  signaturesRequired: number;
  /** 32-byte big-endian bitmap, hex. */
  signersBitmap: string;
  /** 32-byte scalar, hex. */
  s: string;
  /** 20-byte commitment address, hex. */
  commitmentAddr: string;
  /** Whether the value was freshly fetched this round. */
  fresh: boolean;
}
```

## `MolphaWallet`

Anchor `Wallet` plus optional gateway auth. Keypair-backed wallets (`walletFromKeypairFile`) derive auth from `Wallet.payer` automatically; browser adapters should supply `signAuthMessage`:

```ts theme={null}
type MolphaWallet = Wallet & {
  signAuthMessage?: (msg: Uint8Array) => Promise<Uint8Array>;
};
```

## `PlanType`

```ts theme={null}
enum PlanType {
  Basic = 0,
  // Standard / Professional / Enterprise reserved (on-chain ordinals 1–3)
}
```

The SDK currently exports `Basic`. On-chain plan IDs remain `0…3`.

## Derivation helpers

```ts theme={null}
// feedId = keccak256("MOLPHA_JOB_V1" || owner || apiConfigHash || [signaturesRequired])
export function deriveFeedId(
  owner: Uint8Array,
  apiConfigHash: Uint8Array,
  signaturesRequired: number,
): Uint8Array;

export function deriveFeedIdString(
  owner: Uint8Array,
  apiConfigHash: Uint8Array,
  signaturesRequired: number,
): string;

// 32-byte keccak commitment to the canonicalized API config
export function deriveApiConfigHash(apiConfig: APIConfig): Uint8Array;
```

`owner` and `apiConfigHash` must be exactly 32 bytes. `signaturesRequired` is encoded as one byte.

## `buildEvmVerifierArgs`

Converts a `DataUpdateResult` into the two structs the EVM verifier's `verify()` takes — a pure mapping with zero runtime dependency (use the output with ethers, viem, or a raw `eth_call`).

| Gateway `DataUpdateResult` | EVM struct field                 |
| -------------------------- | -------------------------------- |
| `feedId`                   | First `DataUpdate` bytes32 field |
| `registryVersion`          | `DataUpdate.registryVersion`     |
| `signaturesRequired`       | `DataUpdate.signaturesRequired`  |
| `valuePacked`              | `DataUpdate.value`               |
| `timestamp`                | `DataUpdate.canonicalTimestamp`  |
| `s`                        | `SchnorrSignature.signature`     |
| `commitmentAddr`           | `SchnorrSignature.commitment`    |
| `signersBitmap`            | `SchnorrSignature.signersBitmap` |

Pass the `feedId` bytes as the first `DataUpdate` field. See [Verify on EVM](/guides/verify-on-evm) for the consumer-contract side.

## `buildStarknetVerifierArgs`

Converts a `DataUpdateResult` into the Cairo verifier's calldata structs, with no starknet.js runtime dependency.

| Gateway `DataUpdateResult` | Cairo struct field                | Cairo type               |
| -------------------------- | --------------------------------- | ------------------------ |
| `feedId`                   | `data_update.feed_id`             | `u256`                   |
| `registryVersion`          | `data_update.registry_version`    | `u32`                    |
| `signaturesRequired`       | `data_update.signatures_required` | `u32`                    |
| `valuePacked`              | `data_update.value`               | `u256`                   |
| `timestamp`                | `data_update.canonical_timestamp` | `u64`                    |
| `s`                        | `schnorr_data.signature`          | `u256`                   |
| `commitmentAddr`           | `schnorr_data.commitment`         | `felt252` (low 160 bits) |
| `signersBitmap`            | `schnorr_data.signers_bitmap`     | `u256`                   |

See [Verify on Starknet](/guides/verify-on-starknet) for the consumer-contract side.