@reptilianhq/chain-data-contract

Versioned GraphQL contract shared by Reptilian API and read-only consumers of the Reptilian chain-data gateway. The package contains no credentials or transport policy.

It exports:

• the public schema SDL;
• the approved operation documents, names, and SHA-256 persisted-query IDs;
• the Apollo persisted-query manifest;
• TypeScript variable and result types generated from every approved operation.
• the versioned Robinhood testnet gen-9 replay fixture and its normalized recount validators.

import {
  CHAIN_DATA_OPERATION_IDS,
  type ChainDataOperationData,
  type ChainDataOperationVariables,
} from '@reptilianhq/chain-data-contract';

The raw artifacts are also available through the ./schema.graphql, ./operations.graphql, and ./persisted-manifest.json package exports. Consumers should pin an exact version and upgrade atomically with the Reptilian API. Publishing a new version does not activate it in any consumer.

Quote values are asset-aware across Pons curves, AMMs, LB pools, fees, launch summaries, and wallet positions. Prefer ExactAssetAmount, volumeByQuoteAsset, and totalsByQuoteAsset: they preserve the quote-token address, raw integer, and ERC-20 decimals. Legacy ExactQuoteAmount fields are retained for older consumers, but callers must use the adjacent quote-token identity before interpreting them. Legacy protocol and wallet totals are wrapped-native-only and are withheld when they would mix unlike assets. Prices are null when quote-token decimals cannot be established safely.

Pons launch summaries include a provider-specific pons object containing the exact factory lifecycle, immutable launch configuration, fee policy, creator recipient, buyback terms, sweep evidence, graduated position ID, and rescue evidence. Current reserves, claimable balances, and vesting availability remain block-pinned RPC authority rather than inferred historical state.

LaunchFeed.provider optionally scopes pagination to launchonblock or pons. The gateway applies the indexed LaunchOnBlock identity set inside the database query, before the cursor and page limit, so a small provider cannot be starved by a much larger provider sharing the deployment.

LaunchDetail.supplyDistribution exposes exact, non-overlapping original-supply custody slices. Consumers must treat raw amounts as authoritative and require reconciled=true with partial=false before presenting the result as complete. The gateway fences its custody query between two identical indexer checkpoints; an advancing or changed snapshot is deliberately returned as partial.

LaunchDetail.externalMarkets lists launch-scoped Uniswap v2, v3, and v4 market identities and their creation evidence. These records prove initialization only: they are separate from canonical pools, do not contribute to TVL or price, and carry an explicit partial flag during indexer cutovers.

During the coordinated 0.3 to 0.4 rollout, the gateway accepts the legacy 0.3 LaunchDetail persisted hash but dispatches it through the current resolver. Its JSON is therefore the backward-compatible superset shape and can include supplyDistribution; legacy clients must tolerate unrequested fields.

Replay fixture

The ./replay-fixtures export pins the reviewed gen-9 read deployment, historical observation boundary, and representative GUDTEK launch, registered LB pool, trade, holder recount, and retained-ranking evidence:

import {
  ROBINHOOD_TESTNET_GEN9_REPLAY_FIXTURE,
  assertRobinhoodTestnetGen9ReplaySnapshot,
} from '@reptilianhq/chain-data-contract/replay-fixtures';

Adapters in either SDK normalize replay results to ChainDataReplaySnapshot and call the assertion before accepting recount evidence. The assertion requires the corrected holder count, explicit LB-pair exclusion from holders and ranking, zero unregistered LB activity, and representative exact values.

The fixture pins the reviewed read deploymentId; it deliberately does not pin the Launchpad SDK transaction release. Write deployments can advance independently. The eleven launch/indexer operations require readDeployment.deploymentId; the chain-data client binds it once at construction instead of deriving it from the transaction target. The deployment-independent EthUsdPrice operation reads the reviewed Robinhood mainnet WETH/USDG pair and takes no variables.

WalletLiquidityBookPositions and LiquidityBookPosition expose factory-indexed LB receipt ownership without joining through Launch. This intentionally supports live pairs imported from other launchpads. Position discovery is paginated by pair and detail bins are paginated separately.

PortfolioWalletBalances adds stable token identities plus exact amount and source-watermark fields for native portfolio capture. PortfolioWalletLiquidityPositions is a separately bounded receipt-position feed. It does not claim that LB receipt balances are underlying-token amounts, and the package intentionally publishes no lending operation until the indexer can distinguish unsupported coverage from a wallet with zero positions.

The package is published publicly to npm from this repository. Consumers pin an exact version; no registry configuration or credential is required to install it.

npm install @reptilianhq/[email protected]

Versions published before 0.10.0 remain in the ReptilianHQ GitHub Packages version history but are no longer the install path for new consumers.

Development

pnpm --filter @reptilianhq/chain-data-contract generate
pnpm --filter @reptilianhq/chain-data-contract check

Edit chain-data-schema.graphql and chain-data-operations.json, regenerate, and commit the generated operation document, manifest, persisted-operation module, and GraphQL Code Generator result types together.

Publishing

After the reviewed version change merges into main, push the immutable chain-data-contract-v<version> tag at that commit. The release workflow checks main ancestry, builds and verifies the package without publishing credentials, then publishes the exact prepared tarball from a separate OIDC job. A later main commit does not invalidate the release. Main package changes no longer publish automatically. Retries accept the exact existing tag's version.

See Contract releases for the shared publisher, registry verification, recovery and the independent deployment-contract boundary.

Reference pair identity

Version 0.11.0 adds ReferencePairMetadata(deploymentId, pair): chain, factory, ordered tokens and indexed creation provenance for reviewed reference pairs. It returns null for uncovered pairs or missing creation rows; unavailable canonical coverage fails the operation. It contains no current reserves or price. Consumers must keep reserve freshness checks and upgrade only after the indexer replay and gateway deployment have been verified.