Intuition Packages

TypeScript libraries for building applications on Intuition’s identity and knowledge graph protocol.

These packages split Intuition's protocol, identity, and knowledge-graph modeling tools into focused ESM-only TypeScript packages. Builders can install only the layers they need while still converging on shared Intuition vocabulary, deterministic IDs, and graph modeling conventions.

View the @0xintuition npm organization.

Start Here

Start with the offline getting-started guide to build an atom, understand deterministic identity, and choose the packages your app needs. No wallet, RPC, or API key is needed to build atom data.

import { buildIidAnchor } from '@0xintuition/primitives/anchor';

const result = buildIidAnchor('music-recording', { isrc: 'US-RC1-76-07839' });
if (!result.success) throw new Error(result.errors.join('; '));

result.value.iid;     // int:isrc:USRC17607839
result.value.profile; // p0: the atom data is the canonical IID
result.value.dataHex; // hex bytes for contract calls
result.value.id;      // deterministic bytes32 atom ID

The IID packages and anchor API are new in this release candidate; the existing npm alpha tags do not yet contain them. See the release guide for package versions and validation requirements.

To run the dry-run UI example from a checkout, use Node 20 minimum (Node 24 tested) and the Bun version pinned in package.json:

bun install --frozen-lockfile
bun run build
cd examples/hackathon-quickstart
bun run dev

The example uses Creation Profiles to demonstrate atom inputs, metadata relationships, sameAs links, and deterministic IDs without submitting transactions.

Core Concepts

• Atom: an entity represented by data bytes, with a deterministic bytes32 ID.
• Triple: a relationship between a subject atom, predicate atom, and object atom.
• IID: a canonical identifier such as int:isrc:USRC17607839; it describes identity, while an atom ID hashes the exact representation stored on-chain.
• Classification and Creation Profile: shared data describing entity types, fields, identity ladders, and suggested relationships.
• Vault: the on-chain shares/assets associated with an atom or triple on a particular bonding curve.

See the IID explainer for identity schemes and representation profiles. The packages supply deterministic identity and graph building tools and reusable parsing, classification, and enrichment runtimes. Applications configure providers, credentials, cache adapters, scheduling, ranking, and persistence; importing a runtime does not start a worker or fetch data.

For the coordinated Core extraction and publication gates, see the atom runtime migration runbook.

What You Can Build

Use these packages to build Intuition-aligned knowledge graph flows:

• schema-backed atom creation forms with shared classification fields
• metadata predicate pickers that suggest valid relationship triples
• deterministic atom, predicate, triple, and counter-triple IDs before writing on-chain
• sameAs identity-linking flows that separate atom payload choices from graph-growth choices
• generated creation UIs from package data instead of app-local shadow maps
• protocol read/write surfaces once your app owns submission and wallet flow

For known creation flows, start from a Creation Profile:

import { musicRecordingCreationProfile } from '@0xintuition/classifications/creation/music-recording'

const fields = musicRecordingCreationProfile.fields
const relationships = musicRecordingCreationProfile.relationships

Use fields to render atom inputs and relationships to suggest triples such as MusicRecording -> inPlaylist -> MusicPlaylist.

Package Layers

Layer	Packages	Purpose
Semantic / data modeling	schema-org, classifications, predicates	Canonical vocabulary, schema references, recommended atom fields, metadata predicates, and relationship guardrails
Identity	iid-spec, iid, iid-registry, iid-ladder, ids	Canonical real-world identifiers, semantic/provider resolution, deterministic input projection, and content-addressable protocol IDs
Builder helpers	primitives	Higher-level atom, predicate, triple, discovery, and validation helpers
Pipeline runtime	pipeline-runtime	Effect-free concurrency, circuit breaking, cancellation, observation, and provider host policies
Atom processing	atom-parser, atom-classification, atom-enrichment, atom-runtime	Input parsing, plugin-based classification, provider execution, and field extraction
Application integration	sdk, cli	Typed action plans, API reads, and deterministic command-line calldata generation
Protocol plumbing	protocol, deployments, periphery, curves, react	ABIs, bytecode, chain/deployment metadata, bridge/router and fee-proxy helpers, curve math, and React hooks

Packages

• @0xintuition/schema-org - pinned schema.org vocabulary with inherited property lookup.
• @0xintuition/classifications - Intuition classification specs, Creation Profiles, recommended atom fields, and metadata predicates.
• @0xintuition/predicates - canonical predicate registry, deterministic predicate IDs, launch constants, and display helpers.
• @0xintuition/ids - deterministic atom, predicate, triple, counter-triple, and OAuth atom IDs.
• @0xintuition/iid-spec - normative Intuition Identifier specification and conformance corpus.
• @0xintuition/iid - pure IID parsing, canonicalization, validation, and derivation.
• @0xintuition/iid-registry - pure IID-to-classification, provider, and identifier-hint resolution.
• @0xintuition/iid-ladder - strong identifier, registered provider-handle, and canonical-URL projection for application and seed inputs.
• @0xintuition/primitives - high-level builders and validators for off-chain Intuition data.
• @0xintuition/protocol - core contract wrappers, event parsers, and protocol interaction helpers; re-exports core ABIs, deployment addresses, and chain metadata from @0xintuition/deployments.
• @0xintuition/deployments - the single source of Intuition contract ABIs, deploy bytecode, core and periphery deployment addresses, and chain metadata.
• @0xintuition/periphery - periphery bridge/router and FeeProxy helpers and calldata utilities; addresses come from @0xintuition/deployments.
• @0xintuition/curves - bonding curve math helpers, including dynamic-fee curve quotes and exact-net gross-up quotes.
• @0xintuition/sdk - integration SDK with API reads, onchain action planning helpers, and deterministic utilities.
• @0xintuition/cli - agent-oriented calldata encoders, action plan builders, and the intuition executable.
• @0xintuition/pipeline-runtime - Effect-free Promise runtime utilities and provider host policies.
• @0xintuition/atom-parser - input detection, normalization, and bounded remote inspection.
• @0xintuition/atom-runtime - shared Promise-based composition, configuration, cache setup, and engine memoization.
• @0xintuition/atom-classification - configurable classification engines and reusable plugins.
• @0xintuition/atom-enrichment - provider adapters, enrichment execution, and field extraction using public classification specifications.
• @0xintuition/react - React provider and hooks for protocol reads/writes.

Install

Published packages can be installed with npm, Bun, or another package manager. The repository itself uses Bun. Packages are ESM-only; use import. For the currently published semantic APIs:

npm install @0xintuition/classifications@alpha @0xintuition/predicates@alpha viem@^2

@0xintuition/protocol uses the 4.x line. This candidate publishes to alpha; changing latest is a separate release-owner decision. Consult each package README for peers and public subpaths.

Validation

bun install --frozen-lockfile
bun run build
bun run typecheck
bun run test
bun run check
bun run schema:validate
bun run schema-org:check-generated
bun run classifications:check-creation-profiles
bun run predicates:check-generated
bun run registry:check
bun run registry:test
bun run release:registry:test
bun run conformance:check
bun run protocol:check-artifacts
bun run protocol:sync-artifacts:test
bun run guard:supply-chain:test
bun run guard:supply-chain
bun run pack:dry-run
bun run smoke:tarballs

Conformance harness

After bun run build, run bun run conformance:check for five public-surface proofs over reference implementation @ 31b62f3. See the harness guide for coverage, explicit divergences, and vector maintenance.

Contributing and Releases

• Contributing guide
• Release strategy and runbook
• Contract artifact provenance

Package roots are npm-publishable artifacts. Release PRs should follow the validation gate, dist-tag policy, and publish order documented in docs/release.md.