DEV Community: XRPLWin

HookState Data Viewer: Browse On-Chain State, Build Projections, and Publish Your Hook Manifest

zgrguric — Sun, 26 Apr 2026 08:00:00 +0000

Part two of our HookState series. In part one we covered why raw HookState bytes are hard to read and how the Hook State Converter lets you decode them into a typed ABI schema. This article picks up where that one ended: what you do with that schema once you have it.

From a JSON segment to something useful

At the end of part one, you had a JSON ABI definition — a typed map of your HookState key and value bytes. The article closed with a promise: a dedicated projection builder UI exists that uses that schema to automatically decode HookState entries on the explorer.

It does three things. It lets you browse any hook's raw on-chain state by namespace. It lets you build projections — readable, filterable tables that decode state entries according to your ABI. And it lets you publish a hook manifest, so those projections are available to everyone visiting your hook on the explorer, permanently, without anyone needing to convert themselves.

Browsing namespaces

Every Xahau account can have multiple hooks installed, and each hook stores state under its own namespace — a 32-byte identifier derived from the hook hash. The Data Viewer exposes this structure directly.

Open the tool and navigate to any account. The left panel lists all namespaces active on that account, each showing how many total state entries it contains. Clicking a namespace loads its content into the main panel as a set of tabs.

If a manifest has already been published for that hook, the namespace label resolves from a raw hash to a human-readable hook name, and the hook's projections appear as named tabs alongside the raw view. If no manifest exists yet, the namespace shows as a truncated hash and only the raw tab is available — which is your cue to build one.

A namespace can contain state from more than one hook. In that case each hook gets its own tab group within the namespace, with its projections listed beneath it in the sidebar.

All states (raw)

The first tab in every namespace is All states (raw). This is the unfiltered view of everything stored in the namespace, with no decoding applied.

The table shows four columns: HookStateKey, HookStateData, Flags, and OwnerNode — exactly as they exist on the ledger. Keys and values are displayed as full hex strings. This is the ground truth view: no interpretation, no type assumptions, nothing inferred.

It's most useful when you're first exploring an unfamiliar hook and want to see the raw shape of its state before building any projections, when you suspect a projection is missing entries and want to verify against the full set, or when you're debugging a key encoding issue and need to compare raw bytes directly.

The raw table is fully searchable, sortable, and exports to CSV and Excel — so you can pull the complete state of any namespace into a spreadsheet for offline analysis without writing a single API call.

Hooks and their projections

Below the raw tab, each hook installed in the namespace gets its own section. If a manifest exists for the hook, its name appears as the tab label and its projections are listed beneath it in the sidebar — each one a named, filtered view into a subset of that hook's state entries.

The Evernode Governor Hook, for instance, carries over 25,000 state entries across projections ranging from single-entry config values like Issuer Address and Mint Limit, to large paginated sets like Host Address (12,029 entries) and Token Id (12,086 entries). All decoded, all browsable, all exportable — because a manifest exists for it. Without the manifest, you'd be looking at 25,000 rows of raw hex.

The projection

A projection is a named view over a subset of a hook's HookState entries. It defines how to decode the key bytes and the value bytes into typed columns, applies optional filters to scope which entries appear, and gives each column a human-readable label.

You can think of it as a schema-driven query: show me all HookState entries where the key matches this pattern, decode them as these types, and display the result as a table.

One important detail: a projection doesn't claim exclusive ownership of the HookState entries it targets. The same state entry can appear in multiple projections simultaneously, and this is intentional. A hook might expose one projection showing all fields of a record for technical auditing, and a second projection scoped to the same entries presenting only the fields relevant to a specific integration — different column selections, different filters, different renderers, same underlying state. This is how a single hook with a complex storage schema can surface multiple clean, purpose-built views without duplicating any data on-chain.

Each hook manifest can contain as many projections as needed, and several of them can deliberately overlap on shared state keys by design.

Building a projection

To create a projection, click Add projection in the Data Viewer. This opens the Edit Projection modal.

At the top you select which hook this projection belongs to and give it a name and optional description.

The modal has four tabs: HookStateKey, HookStateData, Projection preview, and ABI.

Defining the key (HookStateKey tab)

The HookState key bytes appear as a row of clickable hex buttons. You select a span of bytes by clicking — selecting byte N means you've selected bytes 1 through N as a single segment. As you do, the UI immediately shows how many state entries in the namespace match that byte pattern so far. This live match count updates in real time as you narrow the key definition, giving you instant feedback on whether your filter is scoping entries correctly before you've committed to anything.

Once you've selected a span, the type picker appears showing every ABI type that fits that exact byte length. The Suggest button runs the same autoscan as the Hook State Converter — it scans across all supported types simultaneously and surfaces the most plausible matches with decoded values shown inline.

After selecting a type, a segment options panel appears. When you have unapplied changes the panel is highlighted with an orange border and a "You have unapplied changes" warning — a useful guardrail against navigating away mid-edit without realising you haven't committed a segment:

Column title — the label shown in the projection table header.

Description — optional documentation for the field.

Exclude from view — mark this segment as hidden. Useful for padding bytes, fixed sentinel values, or type prefix bytes you're using only for filtering.

Filtering rule — define a literal term or pattern (with encoding: ASCII, hex, etc.) that this segment must match for an entry to appear in the projection. A single type-byte filter is often all it takes to scope a projection from thousands of total namespace entries down to precisely the records you want.

Render as — controls display format for timestamps, amounts, account IDs, and other types with multiple meaningful representations.

Hit Apply to lock-in the segment.

Defining the value (HookStateData tab)

The value bytes follow exactly the same flow. Select a span, pick a type, configure segment options, apply. Repeat until all bytes are accounted for and the tab is marked Solved.

To give a sense of scale: the Host Address projection in the Evernode Governor manifest decodes 22 typed fields from each entry's raw value bytes — registration ledger, fee, instance counts, heartbeat index, version, timestamps, reputation, lease amount, and more. All of it packed into raw bytes on-chain; all of it readable in the projection table.

Saving and publishing

Once both tabs are Solved, hit Update to save the projection locally. The projection now appears in the sidebar and in the main hook view — but it is not yet live. The main hook view shows a Publish changes button that becomes active whenever you have locally saved projections that haven't been pushed to the manifest yet. This two-step flow lets you build and iterate on multiple projections before making any of them public.

Publishing a hook manifest

A manifest is the container that holds all your projections plus metadata about the hook itself. Publishing one makes everything visible to everyone — not just to you in the Data Viewer, but to anyone who navigates to that hook anywhere on the explorer.

Click on green "Publish changes" buttom to make your manifest version live. In next step you will have change to idenfity hook, give it name, icon, description...

Hook name — the display name that replaces the raw namespace hash across the explorer.
Hook icon — a square image, minimum 256×256px, provided as a URL or direct file upload.
Short description — one or two sentences shown in the manifest header.
Readme — a full markdown field rendered in the About tab on the hook's manifest page. Use it for documentation, storage schema explanation, version history, or anything useful to auditors and integrators coming to the hook cold.
Repository URL — renders as a "Source code" link directly on the hook page.
License — a standard identifier (MIT, GPL-3.0, Apache-2.0) or leave blank for unlicensed.
Publishers — one or more entries, each with a type (Individual or Organization), a name, and an optional URL. Multiple publishers can be added to the same manifest. Publishers are displayed in the manifest header and their combined account weight determines how this version is ranked against others.
ABI — the aggregate JSON of all your projection definitions, auto-populated from your saved projections. A "View/Edit JSON manifest ABI (advanced)" button opens a full editor for direct manipulation when needed.

Hit Publish. The manifest is stored and associated with the hook hash. From this point on, anyone visiting that hook on xahau.xrplwin.com sees the decoded namespace name, the projections as tabs, and the full manifest metadata.

Community manifests and version weight

Anyone with an account on XPLWin can publish a manifest for any hook — not just the hook author. If a hook is deployed and widely used but the author hasn't published a manifest, a community member, an auditor, or an integration builder can step in and create one.

This openness creates an obvious question: if multiple people publish manifests for the same hook, which version does the explorer show by default?

The answer is account weight. Each website account carries a weight value, and when multiple manifest versions exist for the same hook, the explorer sorts them by the combined weight of their publishers. The highest-weight version is shown as the default. Users can switch between available versions at any time using the version selector on the hook page — so no version is hidden, just ranked.

The Evernode Governor Hook is a practical example: built and deployed by Evernode Labs, manifest created and published by XRPLWin. The "Manifest by xrplwin" badge on the hook page reflects this — hook author and manifest author are different entities, and the system handles that cleanly.

In practice this means the hook author, or an established community member with a higher-weight account, will naturally surface at the top. But a lower-weight account can still contribute a manifest — their version remains accessible and switchable. The system accommodates multiple valid interpretations of the same hook's storage schema coexisting without conflict.

The full loop

Part one covered the decoding problem and the Converter that solves it for a single hex string. This article covers what comes after.

The intended flow is:

Write and deploy your hook
Grab a sample HookState key + value from the explorer or your test environment
Run it through the Hook State Converter to produce typed ABI segments
Open the HookState Data Viewer, navigate to your hook's namespace, and build projections — watching the live match count confirm your key patterns as you go
Save projections locally, verify in the Projection preview tab, then hit Publish changes
Fill in the manifest metadata and publish — or build on a community-contributed version if one already exists
Anyone visiting your hook on the explorer now sees decoded, human-readable state — not raw hex

For a hook storing configuration values across dozens of keys, a single afternoon with these two tools produces a manifest that makes it permanently auditable. For something at the scale of Evernode's Governor Hook — 25,000+ entries, community-maintained manifest — it's the clearest demonstration of what this system is designed to enable.

See it in action https://www.youtube.com/watch?v=G86IRZNfNH8

XRPLWin is a explorer for XRPL and Xahau. We build tools for the Xahau ecosystem.

Hook State Converter: Decode Xahau HookState ABI Without the Guesswork

zgrguric — Sun, 12 Apr 2026 23:07:14 +0000

If you've built Hooks on Xahau, you've been here: staring at a raw HookState entry like 5852504C57696E and trying to figure out what it actually means.

Is it a UInt32? A VarString? A timestamp? A ledger index? Big-endian or little-endian?

You either write a throwaway script, crack open a hex calculator, or just guess. None of these are great when you're in the middle of debugging a Hook at 2am.

That's exactly why we built the Hook State Converter

But before we get into the tool, let's talk about why HookState data is so hard to read in the first place — because understanding the problem makes the solution a lot more useful.

Why HookState data is hard to read

Xahau Hooks are small programs that run directly on the ledger. They can read and write persistent state using a key-value store called HookState. Each entry has a 32-byte key and an arbitrary-length value, both stored as raw binary data on the ledger.

That last part is the catch: raw binary data

Unlike a database where you define a schema upfront and the engine enforces types, HookState has no built-in type system. A Hook author decides how to encode data — as a little-endian UInt32, as an XFL float, as a packed struct of multiple fields — and that decision lives only in the Hook's source code. The ledger just stores bytes.

When you look at an account's HookState on an explorer, you see something like this:

Key:   637373746F6D65725F6163636F756E74000000000000000000000000000000000000
Value: 05A528BCFA2189C8E2E7813775ED71B2C4BE349F`

What does the key mean? What type is the value? Is it an AccountID? A hash? A packed amount and timestamp? There is no metadata attached to the entry. The ledger doesn't know and doesn't care — it just stores and retrieves bytes on demand.

This creates a real problem for anyone who isn't the original Hook author:

Auditors trying to verify what state a Hook is reading and writing Developers debugging why a Hook behaved unexpectedly Integration builders trying to read HookState from an external app Explorer users who just want to understand what they're looking at. Even if you are the original author, coming back to a Hook months later and trying to remember your own encoding scheme is painful. And if the Hook is open source but the ABI schema isn't documented anywhere, you're left reading C source code and mentally simulating byte offsets.

The encoding rabbit hole

To illustrate how quickly this gets complicated, consider a simple HookState key that encodes a string like customer_account padded to 32 bytes:

637573746F6D65725F6163636F756E740000000000000000000000000000000000000000

To decode this manually you would:

Split the hex into byte pairs: 63 75 73 74 6F 6D 65 72 5F 61 63 63 ...
Convert each byte from hex to ASCII: c u s t o m e r _ a c c o u n t \0 \0 ...
Recognize it as a null-padded ASCII string
Figure out where the meaningful content ends and the padding begins

That's a relatively simple case. Now imagine the value is a packed struct: 05A528BCFA2189C8E2E7813775ED71B2C4BE349F

Is that 20 bytes? Yes. So it could be a Hash160 or an AccountID. Both are 20 bytes. How do you know which one? You go read the Hook source code. If you're lucky it's commented. Usually it isn't.

Now multiply this across a Hook that stores 10 or 15 different state keys, each with a different encoding scheme, and you start to understand why debugging HookState is one of the more tedious parts of Xahau development.

What the Hook State Converter does

The Hook ABI Conversion Helper is our answer to this problem. It gives you an interactive UI to paste hex, decode it visually, and export a reusable ABI schema — all without writing a single line of code.

The tool accepts three inputs:
HookState key + value pairs — the most common case HookParameter pairs — named parameters passed into Hook invocations Invoke blobs — raw binary payloads attached to Invoke transactions.

Paste hex. Get answers.

Paste your hex into the input fields and the UI immediately does three things:

Splits the hex into individual byte buttons
Marks the key as Solved or Unsolved depending on whether it matches a known schema
Runs an automatic scan and populates suggestions

Each byte is a clickable button. You select bytes by clicking — selecting byte 5 means you've selected bytes 1 through 5 as a single segment. The UI updates in real time to show you every ABI type that fits that exact byte length.

Smart suggestions first

You don't need to know the type upfront. The Suggest button scans your hex across all supported ABI types simultaneously and surfaces the most plausible matches as clickable buttons — each showing the type name and the decoded value inline.

For example, paste 5852504C57696E and you'll instantly see:
VarString XRPLWin
UInt64 32075751449710680
Blob 5852504C57696E

One click to confirm. The tool locks that interpretation and moves on to the remaining bytes. The scan is smart about filtering noise — it suppresses leading null bytes from Null suggestions since those are almost always padding, surfaces VarString matches only when the bytes decode to printable UTF-8, and collapses partial string matches so you see the longest valid string, not every sub-sequence.

Manual byte picking for complex states

If autoscan doesn't nail it, or you're working with a tightly packed multi-field state, the byte picker gives you full control.

Click any byte button to select from byte 1 up to that point. The result panel shows every ABI type that fits that exact byte length — UInt16, UInt16 (BE), Int16 , Timestamp, LedgerIndex — each with the decoded value shown.

Select the type that matches your Hook's logic. The tool locks that segment, advances to the remaining bytes, and a new engine appears for the next segment. You repeat the process until every byte is accounted for.

This chained engine approach means you can decode a 32-byte key that encodes, say, a 4-byte UInt32 flag, a 20-byte AccountID, and 8 bytes of NULL padding — step by step, segment by segment, without losing track of where you are in the buffer.

20+ ABI types supported

Category	Types
Integers	`UInt8/16/32/64`, `Int8/16/32/64` (LE & BE)
Floats	`XFL` (LE & BE)
Amounts	`Amount`, `NativeAmount`, `IOUAmount`
Strings	`VarString`
Hashes	`Hash128/160/256/512`
Identity	`AccountID`
Ledger	`Timestamp`, `LedgerIndex`
Raw	`Blob`, `Null`

Both little-endian and big-endian variants are available for integer and float types, since Hooks developers sometimes store values in BE when interfacing with external systems.

Per-segment options

Once you select a type, a small options panel appears for that segment. You can:

Rename the label — give it a meaningful name like customer_account instead of VarString
Add a description — document what this field represents.
Set a filtering rule — define a literal pattern or regex that this segment must match for the decoding to be valid. Useful for sentinel bytes or magic values that identify the schema version.
Exclude from view — mark padding or fixed bytes as hidden so they don't clutter the final table.
Set a renderer — control how the decoded value is displayed, for example there are various Timestamp renderers.

Hit Apply and the finalized table updates immediately.

Export the ABI schema

Once every byte is accounted for, the tool renders a full breakdown table with raw and rendered values side by side, and below it — the Segment ABI as JSON.

A 32-byte key encoding the string customer_account produces:

[
  {
    "type": "VarString",
    "byteLength": 32,
    "label": "Customer Account"
  }
]

This JSON is the reusable schema and it's part of the Hook manifest format that XRPLWin uses internally. When a Hook manifest is registered with the explorer, it includes ABI definitions like this one — and XRPLWin uses them to automatically decode and display HookState entries in a human-readable way for anyone viewing that Hook on the explorer. You won't need to copy or paste anything manually — a dedicated projection builder UI is available that will use this conversion helper under the hood to generate manifest segments interactively.

XRPLWin is a explorer for XRPL and Xahau. We build tools for the Xahau ecosystem at xahau.xrplwin.com.