Hyperion SDK

Public extension contracts and TypeScript authoring support for Hyperion protocol providers, contract projections, backend adapters and API plugins.

Status: Private development package for Hyperion 4.5, maintained by EOS Rio. This foundation implements inert component manifests, declared version checks, portable protocol-provider contracts and a bounded declarative table projection contract. It provides no projection runtime, database adapter or qualified stable SDK release.

Read the architecture definition, ADRs and release roadmap.

SDK, runtime and adapter source homes define package ownership; assigned homes are not implementation or release-support claims.

Scope

Follow the shared TypeScript 7 and Bun toolchain policy for development and CI.

• Independently versioned SDK contracts, compatible within each major; breaking contracts require a new major.
• Backend-neutral mutations and logical queries, explicit capabilities and reusable conformance fixtures.
• Shared semantics for required language bindings; build on the existing worker infrastructure.
• Explicit migration from @eosrio/hyperion-plugin-core. The old package remains separate; see the source-backed migration inventory and qualification policy.

Development metadata API

import { validateComponentManifest, checkCompatibility } from '@eosrio/hyperion-sdk';

const manifest = {
  schemaVersion: 1,
  package: '@example/plugin',
  version: '0.1.0-dev.1',
  kind: 'plugin',
  compatibility: { hyperion: '^4.5.0-dev.1', sdk: '^0.0.0-dev.1' },
};

validateComponentManifest(manifest); // { valid: true, manifest }
checkCompatibility(manifest, { hyperion: '4.5.0-dev.1', sdk: '0.0.0-dev.1' });
// { compatible: true, errors: [] }: declared range eligibility, without qualification evidence.

The manifest reference defines the shared metadata and diagnostics. The canonical JSON Schema is also exported as @eosrio/hyperion-sdk/component-manifest.schema.json. Metadata validation never loads code, installs dependencies, updates plugins or establishes tested support. Catalog records and release qualification must pin exact component revisions separately.

Protocol-provider development API

The additive protocol contract is exercised by History API #212 and tracked in SDK #4. It separates SHiP sessions, contract ABI/value codecs and normalization from database persistence. Import its portable types and inert validateProtocolSelection validator through @eosrio/hyperion-sdk/protocol or the root.

The optional observeBlockAbi hook captures separate action-input, native-deployment and block-end ABI facts for History API #213 and SDK #6. Observations preserve raw bytes and source anchors; they do not establish canonical coverage, ABI applicability or projection readiness.

The optional verifyNativeGenesis hook returns native block-one ABI and empty application-state facts from retained sections for History API #240 and SDK #9. The host verifies the selected source and reruns the hook before granting coverage; ordinary missing-trace guards remain unchanged.

The optional protocol-native action contract, tracked in SDK #19, adds explicit host capability negotiation, detached per-origin decisions and a separate native value codec. Its validators establish shapes and declared interface agreement; source verification, canonical authority and activation remain provider/host work.

Portable table projection development API

The additive table projection contract is the first SDK #1 slice. It supplies fixed-ABI declarative field mapping, complete put/delete mutations, contiguous block/checkpoint bindings, strict replay identity, capability validation and bounded logical equality/keyset/count queries. Import through @eosrio/hyperion-sdk/projection or the root. The packaged @eosrio/hyperion-sdk/examples/table-projection export provides one reusable synthetic example. Runtime orchestration and actual native storage/query execution belong to their assigned components.

The separate opt-in rollback contract adds fenced reads/writes, bounded undo coverage and resumable runtime-coordinated recovery for SDK #14 and Tools #21. Existing v1 consumers remain unchanged. Database and process-restart qualification belongs to the real adapter and runtime fixtures, not these SDK-only checks.

The additive retained-checkpoint inspection lets a host inspect the adapter's bounded applied branch under its current revision. Its separate capability manifest leaves both existing interfaces unchanged. Inspection supplies no canonical or serving authority.

The separate opt-in contextual scalar mapping family adds original contract/block/time context, explicit absence policy and a distinct preserving replacement operation. Existing v1 contracts stay unchanged. Pure helpers and capability negotiation do not qualify runtime, database atomicity, source authority or production rollback; those remain linked host/adapter work.

The independently activated contextual recovery family keeps the complete contextual batch under a persisted revision fence and reuses exact rollback, coverage and retained-inspection semantics. Existing ordinary/basic contextual/rollback contracts stay closed; SDK snapshot guards do not replace atomic engine checks or host source authority.

The stateful projection proposal and its proposed ADR explore the additive capability needed by SDK #32's untemplated asset lifecycle. The explicit opt-in SDK development contract now provides executable capture, reduction, coherent reads, fixed-candidate custody and adapter conformance seams. The architecture remains proposed; no installed backend support, activation or qualification is implied. Existing families remain unchanged.

Remaining foundation work

Track SDK issue #1 and release coordination #24.

The cross-repository implementation target is one declarative contract round-tripping through the SDK and a real MongoDB adapter. SDK-only checks do not establish that outcome. See P05 in the approved issue batch.

Read CONTRIBUTING.md and AGENTS.md. Run npm ci, npm run typecheck, npm test, npm run test:package and npm run check:docs. Development requires Node.js 24 or newer and Bun 1.4.4, pinned in .bun-version. npm run typecheck uses bun check -p tsconfig.json; npm run build uses TypeScript 7.0.2 to emit JavaScript and declarations. Keep npm ci and the committed npm lockfile for dependency installation. CI exercises Node.js 24 and 26 with the pinned Bun checker. npm pack and Git dependency installation build through prepare. private: true prevents accidental registry publication. These checks cover metadata/protocol selection, portable projection contracts and a packed ESM/TypeScript consumer. Host execution and chain/runtime qualification have their own acceptance evidence. Licensed under MIT.