npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@xyo-network/xl1-statement-graph-sdk

v0.7.1

Published

Chain-facing SDK for the XYO Statement Graph — finalized-scan replay source, verified writer, and replay-contract checkpointing over structural XL1 viewer/datalake interfaces.

Readme

@xyo-network/xl1-statement-graph-sdk

Chain-facing SDK for the XYO Statement Graph (see the repository WHITEPAPER). Everything chain-shaped is a STRUCTURAL interface (FinalizedBlockViewer, BodyStore, StatementBroadcaster) — a real XL1 gateway viewer and REST datalake runner satisfy them directly, and the testing package's fakes exercise every behavior deterministically.

Version note: the resume-integrity behavior described below (the floor bound, the checkpoint refusals and their details, the scan-side resume guards, the duplicate-transaction decode check, and the through RangeError) shipped in 0.6.0, published 2026-10-08. A consumer pinned to ~0.5.x (or a ^0.5 peer range) does not pick up 0.6.0 and keeps the 0.5.4 behavior until it moves to ~0.6.x. The strict gate profile described below (ReplayContract.gateProfile, its comparison on resume, and strict revision 1) shipped in 0.7.0, published 2026-10-09; a consumer pinned to ~0.6.x keeps the 0.6.0 behavior until it moves to ~0.7.x.

  • Bridge: decodeHydratedBlock — XL1 hydrated blocks → committed-order abstract transactions plus non-transaction block carriers, with the D7-critical rule that txIndex counts the FULL committed block payload array before filtering. It returns undefined for an unrecognizable or consensus-invalid block, including one that commits the same transaction twice.

  • Scan (scanFinalizedStatements): forward finalized walk with same-block elevated Claim hydration. Every transaction Bound Witness and every carrier consumed by the scan is canonical root-hash verified: required elevated Claims, configured auxiliary items, and co-committed objects named by verified Claims when strict body/schema equality is enabled. Unrelated non-transaction carriers do not affect Statement Graph replay. ClaimCarrierIntegrityError stops scanning on missing/mismatched Claim carriers, relevant non-Claim mismatches raise BlockCarrierIntegrityError, and the datalake is never a Claim-event fallback. Verified object/auxiliary carriers take precedence over off-chain resolution. A height for which the gateway returns no block, a block for another height, or a block that fails decoding (shape, commitment, or duplicate-transaction checks) raises BlockUnavailableError rather than being skipped; a gateway read that throws propagates its own error. Bulk range completeness, per-block fallback, head-regression checks against a resumed checkpoint's throughBlock, AbortSignal, strict object-body verification, indexedSchemaPolicy, and auxiliary candidates remain supported.

  • Writer: buildClaim({source, subject, hashes}), shared prepareStatements, insertVerified (insert → readback hash check), and publishStatements — Claims occupy only the elevated/on-chain partition and use XL1 root hashes; referenced object identity remains dataHash-based. Every named object must be co-committed or the whole Claim transaction is rejected. Objects whose client metadata makes root hash differ from dataHash are rejected because they cannot satisfy that commitment. The on-chain/off-chain transport partitions are disjoint and order-independent.

  • Checkpoint: format version 2, ReplayContract-scoped, with observable load causes (missing / corrupt / contract-mismatch). Stored and directly supplied resumeFrom values pass the same runtime parser before records or horizons are trusted: the scan throws on corrupt and contract-mismatch, and rescans from floorBlock on missing. A loadCheckpoint corrupt detail quoted below reaches a scan caller as resume checkpoint is corrupt: <detail> (Whitepaper §8.2). Legacy, foreign, and invalid checkpoints:

    • format 1 (written by releases before 0.5.0 other than 0.4.0/0.4.1), no marker, or any other marker below 2 or not a number loads as missing and rescans from the floor;
    • 0.4.0/0.4.1 checkpoints are format 2 with the old records shape, so they load as corrupt with pre-fold-4 checkpoint (0.4.0/0.4.1 `records` shape); delete it to rescan from floor, and the scan throws. Delete them to rescan from the floor;
    • a format number above 2 was written by a newer SDK and loads as corrupt with unsupported checkpoint format N; upgrade the SDK, so from 0.6.0 this SDK never silently rescans over it (0.5.4 and earlier still load it as missing and rescan);
    • a fold-4 checkpoint that retains unresolved Claim references loads as corrupt, and the scan requires a full rescan;
    • a checkpoint whose contract differs from the expected one in any field except throughBlock is contract-mismatch (contractMismatch names the first field). From 0.7.0 that includes the gate profile, compared by value with gateProfileMismatch under the legacy rule (see Strict gate profile): a profile-less checkpoint is accepted unless the expected profile sets requireBodySchemaEquality. A caller that runs loadCheckpoint itself must pass the effective contract, with the profile its scans run under: a profile-bearing checkpoint is contract-mismatch against a contract without one;
    • floorBlock is a hard lower bound on claim state. A frozen record whose firstBlock precedes floorBlock loads as corrupt with claim record firstBlock F precedes floorBlock N; full rescan from floor required, and a watermark below the floor with the matching watermark block B precedes … detail. assembleCheckpointRecords applies the record check to every frozen half it assembles, inline or sharded, and prefixes a shard half's detail with its position (record shard I: claim record firstBlock …). That shard detail reaches only callers that resolve shards themselves: the scan refuses a sharded checkpoint first (see Resume). Delete the checkpoint and rescan from the floor.

    The generic protocol still models unresolved event bodies for non-XL1/local backings, but finalized scans turn missing elevated carriers into fatal integrity errors.

  • Resume (ScanOptions.resumeFrom): the scan walks [max(floorBlock, throughBlock + 1), head], so it never re-reads a walked block and never reads below the floor. A checkpoint sealed while the horizon was still below the floor (its throughBlock is below floorBlock and nothing was walked) resumes at the floor. Every resume check runs before any block is read:

    • the scan consumes only self-contained checkpoints. One that externalizes records to recordShards throws resume checkpoint externalizes its records to shards; assemble them before scanning, and inline records that fail assembly throw resume checkpoint records do not assemble: <detail>;
    • claim state (frozen records or watermarkGroupEventKeys) without a fold watermark, or a watermark.block beyond throughBlock, is not a finalized-scan checkpoint and throws with full rescan from floor required. An empty checkpoint without a watermark still resumes. loadCheckpoint leaves these shapes valid because other producers (sharded or local-log checkpoints) hold them legitimately; do not use checkpointSeed as a fold seed for such a checkpoint;
    • a finalized head below throughBlock throws FinalizedHeadRegressionError;
    • a caller through below throughBlock, with the chain not regressed, is a request error: it throws RangeError (through T is below the resume checkpoint's walked horizon W). A through above the finalized head is still clamped to the head.
  • Strict gate profile (ReplayContract.gateProfile, 0.7.0; Whitepaper §8.2). The strict gates are dataset identity, declared in the contract as {rejectAmbiguousSchemaDeclarations, requireBodySchemaEquality, revision} and omitted for the default profile (both flags off), so default-profile contracts and checkpoints are byte-identical to 0.6.0.

    • Effective contract. The scan runs under contract.gateProfile, or, when the contract has none, the profile the deprecated ScanOptions.strict declares at STRICT_GATE_REVISION. ScanOptions.strict is still honored, so existing callers keep working, but new code declares the profile in the contract. A declared profile at another revision throws replay contract gateProfile revision N does not match this implementation (1); then, when both are present and declare different profiles, the scan throws TypeError: ScanOptions.strict conflicts with contract.gateProfile; …, both before any read. The two are compared symmetrically by value, so an explicit all-off contract profile agrees only with all-off strict flags. The effective contract, with gateProfile only when it is not the default, drives the resume check, extraction, strict body resolution, and the checkpoint the scan seals.
    • Resume. A checkpoint that records a profile resumes only under the same profile, by value and revision; under any other, the default included, the scan throws resume checkpoint belongs to a different dataset: gateProfile … != …. Legacy rule: a profile-less checkpoint, written under the default profile or by 0.6.0 or earlier, is accepted unless the effective profile sets requireBodySchemaEquality (gateProfile default (or written before gate profiles) != {…}; strict body-schema equality requires a full rescan from floor). The rule encodes revision 1, which left rejectAmbiguousSchemaDeclarations unchanged: under a profile at any other revision a profile-less checkpoint is refused (… strict revision N requires a full rescan from floor). A strict rejectAmbiguousSchemaDeclarations checkpoint from 0.6.0 or earlier therefore resumes without a rescan, and the next checkpoint records the profile. SDK releases before 0.7.0 reject a profile-bearing contract and load a profile-bearing checkpoint as corrupt, so a fleet that shares one checkpoint store upgrades together and cannot downgrade past a profile-bearing checkpoint.
    • Helpers. canonicalGateProfile(profile) returns the canonical form (undefined when both flags are off, at any revision). gateProfileFromStrict(strict) turns StrictModeOptions into a canonical profile at STRICT_GATE_REVISION; use it to declare the profile in the contract when migrating off ScanOptions.strict, and in the contract you pass to loadCheckpoint (it returns undefined for the default profile, whose key the contract omits). gateProfileMismatch(actual, expected) compares a checkpoint's profile (actual) with the expected one by value under the legacy rule, so it is asymmetric, and returns the mismatch detail or undefined; contractMismatch calls it after every other field.
    • Strict revision 1. Under requireBodySchemaEquality an object body must be a plain record whose schema is a string equal to the declaration (object-schema-mismatch otherwise; anything but a plain record, or no verified body, is object-body-unverifiable), and a pure object whose hash is H({schema: declared}) self-verifies with no stored body (withPureObjectBodies, from the protocol package). The scan applies it per transaction before extraction; auxiliary candidates keep the bodies actually read. A dataset folded under requireBodySchemaEquality before 0.7.0 needs a full rescan from its floor, which the legacy rule enforces.
    • Availability. Under requireBodySchemaEquality, an object with no same-block carrier whose off-chain body is missing or fails its hash check is dropped for that entry (object-body-unverifiable; a failed hash also appears in corrupt), and the checkpoint still advances past the block. The exception is a correctly declared pure object, which self-verifies: it folds whether its readback is missing or corrupt (a corrupt readback is still reported in corrupt). Resume never revisits it, so the drop is permanent for that checkpoint lineage; only a rescan from the floor evaluates it again. This is decided behavior: object availability under strict mode is settled once per lineage (Whitepaper §8.4). Declaring the profile does not declare the object corpus, and strict datasets can see a different negation set from default ones (Whitepaper §14.1).

Account-mode transaction building (buildTransaction + addTransactionToChain) stays at the consumer boundary for now — publishStatements targets the universal addPayloadsToChain path both browser and Node gateways expose.

License

LGPL-3.0-only © XY Labs / XYO Foundation