ixo-chain

Read-only IXO chain data for the model: live balances, account overviews, 30 lookup kinds over the chain and IXO Blocksync, and names for addresses and DIDs.

Use the ixo-chain plugin when your oracle should answer questions about an IXO account from public chain data: balances, claims, staking, DAOs and transactions. It only reads, it ships with the Cloudflare Workers runtime only, and it loads unless IXO_CHAIN_TOOLS=off.

Source: packages/oracle-runtime-workers/src/plugins/ixo-chain/

AttributeValue
Feature keyixo-chain
RuntimeCloudflare Workers runtime only (@ixo/oracle-runtime-workers 0.28.0 and later). This page describes 0.34.1.
Visibilityon-demand
Stabilitybeta
Categorydata
Default stateOn unless IXO_CHAIN_TOOLS=off
Depends onNone
Requires (UCAN)None (everything it reads is public)

Summary

The ixo-chain plugin gives the model four read-only tools over public IXO chain data, so it can answer questions such as "what is my IXO balance?", "tell me about my account", "did I get paid for my claims in collection 8250?" or "who is ixo1…?". It is part of BUNDLED_WORKERS_PLUGINS, so an oracle that spreads that list into the plugins of createOracleWorker loads it unless IXO_CHAIN_TOOLS=off. The Node.js runtime (@ixo/oracle-runtime) does not ship it.

ToolReadsFreshness
get_account_balancesChain REST (LCD) gateway: bank balances, denom metadata, IBC denom tracesLive chain state
get_account_overviewThe balances read and existing lookup kinds, one section per topicAs each part's source; an answer is reused for 20 s
chain_lookupPer kind: chain REST reads, or one IXO Blocksync GraphQL (BLOCKSYNC_GRAPHQL_URL) document per callchain kinds live; blocksync kinds the index, seconds behind the chain
describe_chain_kindsNothing: the kind catalogue, or a named kind's arguments and explanationStatic

The tools use progressive discovery. chain_lookup names its kinds in an enum, and the model asks describe_chain_kinds for a kind's arguments, an example and what the result means. From 0.39.0 the chain_lookup description also lists the argument names of every kind that takes more than address and first, so the usual lookup needs no describe_chain_kinds call; the argument schemas stay out of the definition.

Answers call people and things by name: get_account_balances, get_account_overview and chain_lookup add a names map from the shared IXO Names worker. See Names.

Every account field defaults to the user. The user's IXO account address is the suffix of their did:ixo:ixo1… DID (see What the model is told about the user). A user with a did:key: or did:web: DID has no address, and a request that needs it answers invalid_input ("the user has no IXO account address; give one"). An account field also takes any ixo1… address or did:ixo:ixo1… DID.

Load it on every turn

The plugin is on-demand: its tools exist on a turn only after the model loads it with load_capability, or after the runtime's capability router preloads it (from 0.39.0 a preload is a load on the thread, not for that turn only). To bind the tools on every turn instead, override its visibility tier with manifestOverrides:

// src/index.ts
import {
  createOracleWorker,
  BUNDLED_WORKERS_PLUGINS,
} from '@ixo/oracle-runtime-workers';

export default createOracleWorker({
  config,
  plugins: [...BUNDLED_WORKERS_PLUGINS],
  manifestOverrides: {
    'ixo-chain': { visibility: 'always' },
  },
});

The override is shallow-merged onto the plugin's manifest at boot and validated like an authored manifest; see Retune a bundled plugin's manifest. The rules the model needs (live versus indexed data, units, read-only, untrusted text, names) are in the plugin's operating guide and in the descriptions of the tools whose answers need them, so each tool reads correctly on its own.

Environment variables

VarRequiredDescription
IXO_CHAIN_TOOLSnoon (default) or off. off leaves the plugin out of the oracle.
CHAIN_REST_URLnoChain REST (LCD) base URL for balances, denom metadata, the overview's chain sections and the chain kinds of chain_lookup. https, no credentials, query or fragment (a /rest path is fine). Defaults per NETWORK, below.
IXO_CHAIN_IBC_DENOMSnoMore verified IBC tokens, merged over the built-in ones of the oracle's NETWORK (mainnet: USDC from noble-1 and from injective-1). A JSON object, as a string or an object vars entry: { "ibc/<64 upper-case hex>": { "symbol": "…", "decimals": 0-18, "origin"?: "chain id" } }. symbol is 1 to 20 of A-Z a-z 0-9 . -. An entry shows that denom verified with those decimals and origin, without a lookup. Invalid JSON or an invalid entry fails boot validation.
IXO_NAMES_URLnoThe IXO Names worker's origin. https, no credentials, query or fragment; a path is ignored. Defaults per NETWORK, below.
IXO_NAMESnoon (default) or off. off leaves names out of every answer and asks the worker nothing.
BLOCKSYNC_GRAPHQL_URLn/aRead but not owned (core). The IXO Blocksync endpoint chain_lookup queries. A value that is not an http or https URL makes chain_lookup answer unavailable without sending a request.
NETWORKn/aRead but not owned (core). Selects the default REST gateway and Names worker, and is named in every result.
NetworkChain REST defaultBlocksync GraphQL (BLOCKSYNC_GRAPHQL_URL)Names worker default
mainnethttps://impacthub.ixo.world/resthttps://blocksync-graphql.ixo.earth/graphqlhttps://names.ixo.earth
testnethttps://testnet.ixo.earth/resthttps://testnet-blocksync-graphql.ixo.earth/graphqlhttps://testnet.names.ixo.earth
devnethttps://devnet.ixo.earth/resthttps://devnet-blocksync-graphql.ixo.earth/graphqlhttps://devnet.names.ixo.earth

What it contributes

  • Tools: get_account_balances, get_account_overview, chain_lookup, describe_chain_kinds (all effect: 'read').
  • Sub-agents: none.
  • Middleware: none.
  • HTTP routes: none.
  • Shared state: none durable. Caches and limits live per isolate.

get_account_balances

Input: { address? }, an ixo1… address or did:ixo:ixo1… DID; default the user's account. The tool reads one page of up to 50 bank balances from the chain REST gateway and shows each denom through the chain's own bank metadata:

  • uixo is shown as IXO with 6 decimals, verified, and is never looked up.
  • An ibc/… denom in the IBC table (the built-in entries of the oracle's NETWORK and IXO_CHAIN_IBC_DENOMS) takes that entry's symbol, decimals and origin, verified, and is never looked up.
  • Any other denom is looked up in the bank metadata. It is verified when the metadata lists its display unit in denom_units with an exponent of 0 to 18; that exponent becomes its decimals, and its symbol is the metadata symbol or, when that is empty, the display unit upper-cased. So 5,740,000 upay reads as 5.74 PAY.
  • An ibc/… denom the metadata does not verify gets its denom trace read. The token stays unverified, with trace: { baseDenom, claimedChain, path } beside it. A trace is a claim by the sending side, never what the token is: anyone can create a light client that claims any chain id and send any base denom over a channel on it.
  • A denom with no metadata, or whose display unit is not listed, is unverified: 0 decimals, in base units, named by its full denom.
  • A token whose metadata could not be read (a failed read, or no time left in the tool's budget) is shown unverified with metadataUnavailable: true: it may still be verified.

Answer:

{ ok, network, source: 'chain', fetchedAt, address, subject,
  tokens: [{ denom, symbol, decimals, verified, amountBaseUnits, amount,
             origin?, trace?, metadataUnavailable? }],
  moreDenoms?, truncated?, names? }

amount is a decimal string in display units (9000000 uixo is "9"). Tokens are sorted uixo first, then verified tokens, then by amount. moreDenoms: true means the account holds more than 50 denoms. An empty list is an answer, not an error. origin is the source chain id of a verified IBC token. Two tokens can share a symbol (mainnet has USDC from noble-1 and from injective-1), and the model is told to say the origin when they do.

get_account_overview

Input: { address?, sections? }. address defaults to the user's account. sections is any of the ten below, default all. The tool is broad and costs several reads, so the model is told to use it for broad account questions and to use get_account_balances or chain_lookup for one fact.

SectionReads
balancesThe get_account_balances read
fee_grantsFee grants received. Grants given are not read by default; notRead carries the request that reads them.
authzAuthz grants received and given
smart_accountAuthenticators on the account
accountWhat the address is on chain
stakingDelegations, unbonding and rewards
liquid_stakingPools and what the account holds in them
claimsClaims, performance deposits and team-member budgets
governanceProposals in voting, with the account's vote
daosThe account's DAOs and their open proposals

Every part of every section runs in one call, under the same limits as chain_lookup, and list parts read 3 rows.

Answer:

{ ok: true, network, fetchedAt, address, subject,
  sections: { [name]:
    { ok: true, summary: { counts, totals?, top }, more?, notRead?, failed?, truncated? }
    | { ok: false, reason, detail, retryable } },
  names? }
  • top holds at most 3 rows, as their kinds give them.
  • counts holds a number per part, or "N+" when more exist than were read.
  • more is the request that reads the rest: { kind, args } for chain_lookup, or { tool: 'get_account_balances', args }.
  • failed lists parts that failed beside parts that answered. A section whose parts all failed is that failure. One section never fails another.

A complete answer is reused for 20 s per isolate. An answer with a failed part is read again by the next call.

chain_lookup

Input: { requests: [{ kind, args? }] }, 1 to 8 requests. Before 0.30.0 a request's fields sat flat beside kind; that shape is refused. All Blocksync requests of a call go as one GraphQL request, chain REST requests run alongside, and each answers on its own. Batch related questions into one call.

Every account field defaults to the user. first is the rows a list reads, 1 to 20, default 10.

Core kinds (IXO Blocksync, source: 'blocksync'):

kindWhat it answersargs
claimsClaims submitted by an account, newest first, with each claim's evaluation and payment statusagent?, collectionId? (from 0.39.0 only with agent; a collection's totals are in claim_collection), first?, after? (the previous page's endCursor)
claimOne claim and its current evaluationclaimId (a CID, for example bafkrei…)
claim_collectionOne claim collection: counts, state and payment termsid (for example "8250")
claim_collectionsCollections by admin or by entity, newest start date firstentity?, admin?, first?
entitiesEntities owned by an accountowner?, type? (for example "dao"), first?
entityOne entity. From 0.44.0 it adds governingGroup: the core address of the DAO DAO group that governs it, as the Portal's Decisions tab reads it (absent when there is none or two links disagree)id (did:ixo:entity: followed by 32 hex characters)
did_documentOne DID documentid? (any did:ixo:… DID)
token_balances1155 tokens an account holdsaddress?, first?
transactionsTransactions an account signed, or messages it receivedaddress?, direction? (signed, the default, or received), first?
transactionOne transaction, with its signers, fee and up to 50 messageshash (64 hex characters)

Chain kinds (live chain REST reads, source: 'chain'):

kindWhat it answersargs
fee_grantsFee grants an account received or gavedirection? (received, the default, or given), address?, first?
authz_grantsWho may act for an account, or for whom it may actdirection?, address?, first?
smart_accountExtra signing rules (authenticators) on an accountaddress?
accountWhat an address is on chain: regular, module, vesting or contractaddress?
stakingDelegations, unbonding and rewards waiting to be claimedaddress?
validatorsValidators: name, address, commission, active or notname? (part of the moniker, any case), first?
spendableHow much of each token an account can spend now, and how much is lockedaddress?
liquid_stakingLiquid staking pools such as PAY: rates, totals and what an account holdsaddress?
network_economicsHow new IXO is minted: provisions per epoch, the next reduction, where it goesnone
gov_proposalsGovernance proposals with the tally and the account's votestatus? (voting, the default, passed, rejected, deposit or all), voter?, first? (at most 10)
claim_intentsAn agent's claim intents: payments reserved in escrow before a claim is submittedaddress?, collectionId?, first?
collection_membershipAn account's team-member budget and performance deposit in one collectioncollectionId, address?

Indexed kinds (IXO Blocksync, source: 'blocksync'):

kindWhat it answersargs
token_history1155 token movements: received, sent, retired or cancelledaddress?, direction? (in, out, retired or cancelled; default in and out), first?
evaluationsClaim evaluations of one claim, a collection, or by an evaluatorAt most one of claimId?, collectionId?, evaluator?; first?
member_budgetsSpending budgets of a team member of claim collectionsaddress?, collectionId?, first?
agent_depositsPerformance deposits an agent holds, and when each can be withdrawnaddress?, collectionId?, first?
disputesDisputes against a claim, or those an account filedclaimId? or address?, first?
daosDAOs an account is a member of, how, and its share of the voting power; each proposal list's proposalModule and, from 0.44.0, its intake (where new proposals are sent)address?, first?
dao_proposalsProposals of a DAO, or of the account's DAOs, with its vote on eachdao? or address?, status? (open, the default, or all), first?
liquid_stake_historyStakes and unstakes per pool, newest firstaddress?, first?

The tool layer checks only the envelope. An unknown kind, a key beside kind and args, args that is not an object, or more than 8 requests rejects the whole call with a tool error that names the mismatch. Everything inside args belongs to the kind: an unknown key, a missing id or a first outside 1 to 20 answers invalid_input for that request alone and points the model to describe_chain_kinds. From 0.39.0 the answer also lists the kind's valid keys ("Its args: agent, collectionId, first, after."), so the model can fix a guessed key without another call. The other requests still run.

Answer:

{ ok: true, network, fetchedAt,
  results: [ { kind, source, ok: true, subject?, first?, data, truncated? }
           | { kind, source, ok: false, reason, detail, retryable } ],
  names? }

The whole answer is never ok: false: a failed request to IXO Blocksync fails each Blocksync request with its reason, and the chain requests still answer. What data holds in the core kinds:

  • Claim and evaluation status as words (pending, approved, rejected, disputed, invalidated, flagged); collection state open, paused or closed. claims carries hasNextPage and endCursor for after.
  • Transactions as { hash, height, time, code, succeeded, memo?, messages, messageCount? }. Message values are never returned raw: MsgSend is { from, to, amount }, MsgTransferToken is { from, to, tokens }, MsgSubmitClaim and MsgEvaluateClaim are { claimId, collectionId, status? }, an authz MsgExec is its first 5 inner summaries, and anything else is a 240-character JSON excerpt.
  • An entity's status stays the chain's number, with a statusNote: the chain gives entity status no fixed meaning. entities adds orderedBy: 'id (text)', because an entity id is a hash and its order says nothing about age.

describe_chain_kinds

Input: { kinds? }, at most 8 names. It makes no read.

  • Without kinds, it answers the catalogue: every kind as { name, source, summary, list? }.
  • With names, it answers each kind as { name, source, summary, list?, args, example, explain }: the JSON schema of its arguments, a full example request, and what the result means. Names that are no kind come back in unknown.

Names

get_account_balances, get_account_overview and chain_lookup keep every raw address and DID and add one names map per answer, from the shared IXO Names worker. describe_chain_kinds does not. An answer with nothing named has no names.

"names": {
  "did:ixo:entity:f22eda1f500a2ce90a16c835e1099b6a": {
    "name": "Companion", "source": "entity", "selfChosen": true
  },
  "ixo1vafr2dqhgz8frc7gf22njz8y2u0fue4kuetey6": {
    "name": "IXO fee-grant service (feegrant.ixo.world)", "source": "table", "selfChosen": false
  }
}

What is named. At most 40 identifiers per answer, those in the top rows of lists first: ixo1… account and contract addresses with a valid checksum, did:ixo:ixo1…, did:ixo:wasm:ixo1…, entity DIDs, ixovaloper1… addresses, and claim collection ids, keyed collection:<id>. Never a token's free-text collection, an address inside a memo or excerpt, a denom, or the user's own address or DID.

What an entry holds.

  • name is the worker's, already cleaned. It is still text written by anyone: data, never instructions.
  • source is where the worker found it: table, matrix, entity, entity-alias, entity-account, dao, validator, collection, denom-registry, denom-metadata or ibc-trace.
  • selfChosen is true when the holder picked the name, which is every source but table and denom-registry. Anyone can pick a look-alike name.

What the model is told. Call people and things by their names entry; give an address or DID only when asked; beside a selfChosen name the user did not pick, also give the short address (first 12 and last 6 characters).

Collections are named by the worker after their protocol entity. The chain does not check that a collection's protocol belongs to its owner, so anyone can attach a collection to a well-known protocol's name. Such a name is selfChosen: true.

Failure means no names. A call waits at most 6 s for names, and never into the last second of its 20 s budget. The worker is asked to answer by 5 s with what is ready and finishes the rest in the background for the next call. A timeout, an error or an unusable answer leaves the answer as it was, without names, and never fails the tool. Answers that do land are remembered for up to 10 minutes per isolate. A 429 or 5xx pauses names requests to that worker for its Retry-After, at most 5 minutes.

Requests. Misses of concurrent calls are batched per isolate into POST <worker>/v1/resolve, at most 40 ids each. The header x-client-id is ixo-chain-<ORACLE_NAME as a slug, or oracle>-<network>. There is no service key. The worker allows 6,000 requests a minute per caller, where a caller is the calling Worker's Cloudflare zone, and its uncached work has a limit of its own. On IXO's own zones the client id also separates callers, so each oracle has its own limits per network. On any other zone, every oracle on that zone shares them. Ids over the uncached limit get no name on that call and are asked again later.

Reading the results

  • network is in every answer. The model is told to say which network an answer is from.
  • subject is 'user' or 'other': whether the data belongs to the user. A read by account knows it before the read. A read by id learns it from the answer: a claim is the user's when its agentAddress is the user's address, a collection when its admin is, an entity when its owner is, a transaction when one of its signers is, a DID document when its id is the user's DID. claim_collections by entity alone carries no subject.
  • amount versus amountBaseUnits. get_account_balances, get_account_overview and the chain and indexed kinds show a bank coin as { denom, symbol, amount, amountBaseUnits, verified, origin?, trace?, metadataUnavailable? }, with amount in display units. The 10 core kinds keep base units: every bank coin (a claim's or evaluation's amount, a MsgSend amount, a transaction fee, a collection payment) and every cw20 payment amount is { denom, amountBaseUnits }, where uixo ÷ 1,000,000 = IXO.
  • 1155 tokens are whole units. The IXO token module stores no decimals, so token_balances rows, token_history, MsgTransferToken amounts and cw1155 payments keep amount in whole units. token_balances rows are { tokenId, name, class, collection, amount, retired, contractAddress }.
  • Failures are results, each with one plain-sentence detail the model can relay:
reasonWhenretryable
rate_limitedHTTP 429 twice, a Retry-After over 5 s, or the upstream is marked unhealthy after a 429true
timeoutAn attempt, or the tool's budget, ran out of timetrue
index_timeoutIXO Blocksync's statement timeout for that request ("ask for fewer rows or a narrower filter")false
unavailable5xx, 404, network error, redirect, unreadable body, a field error, a request the answer does not carry, no valid BLOCKSYNC_GRAPHQL_URL, a kind that failed inside the oracletrue for 502 to 504, network, transient and missing-request errors
not_foundA by-id read answered null with no errorfalse
too_largeThe body was over the read limit, or a request was left out to keep the answer smallfalse (ask for it on its own)
invalid_inputargs the kind refuses, a field that fails its pattern, or no IXO account address for the user. From 0.44.0 also a contract read the contract refuses, or of an address with no contract on it, with the chain's words (before, unavailable)false

Limits

LimitValue
Requests per chain_lookup call1 to 8; the Blocksync ones go as one GraphQL request
Rows per list (first)1 to 20, default 10. With n > 1 requests in a call, each list reads at most max(5, floor(40 / n)) (2 requests: 20, 4: 10, 8: 5); every list result reports the first it used.
Bank balancesOne page of 50 denoms (moreDenoms: true beyond that)
Nested listsA transaction in a list: its first 5 messages, with messageCount for the total. One transaction: up to 10 signers and 50 messages. Collection payment lists: 10. Entity and DID document lists: 20.
StringsClipped: ids, addresses, hashes and dates 120 characters; names and labels 200; memos 256; excerpts 240
Answer sizeAt most 12,000 JSON characters, names included. Each result gets a share; a result over its share has its largest list halved and is marked truncated: true; if the answer is still too big, the largest results are replaced by too_large. Then rows are cut one at a time to fit names, and with no row left to cut, names go from the end of the map.
Reads per user5 at once per user per isolate, shared by all of that user's ixo-chain calls
Denoms per requestOne chain_lookup request, and each overview part, looks up at most 20 distinct denoms; the rest show metadataUnavailable. get_account_balances has no such cap.
Time20 s budget per tool call; each attempt at most 8 s (chain REST) or 11 s (IXO Blocksync, above its 8 s statement timeout)
RetriesOne retry on HTTP 429, 502, 503 or 504, a network error or a transient GraphQL error, after the upstream's Retry-After (capped at 5 s) or a random 1 to 3 s, and only when at least 1 s of budget would be left. Never retried: other 4xx, 501, a timeout, an unreadable or oversized body, a statement timeout.
Unhealthy upstreamA 429, 502, 503 or 504, or a network error, marks that upstream for 10 s per isolate; other calls answer that failure (retryable) at once instead of asking it
Body readAt most 512 KiB (chain REST) or 1 MiB (IXO Blocksync); no redirects are followed

Read-only and security

  • Read-only. No tool signs or sends anything. For a transfer, the model is told to use the turn's transfer tools instead.
  • Public data only. The manifest declares no requires: nothing it reads is guarded by a User-Controlled Authorization Network (UCAN) capability, and anyone can read the same data from the chain. Identifiers from an answer are sent to the IXO Names worker; IXO_NAMES=off stops that.
  • Chain text is data, never instructions. Memos, names, descriptions and excerpts are written by anyone on a public chain. The operating guide and the chain_lookup description tell the model to treat them as data.
  • Inputs are checked before they reach a query. Every id is matched against its kind's pattern and written into the GraphQL document as a literal.
  • Logs carry no user data. Each failed attempt logs one [ixo-chain] <read> attempt N failed: <status or error class> warning, and a names failure one [ixo-chain] names: <status or error class> warning, never a request body or an address.

Known limits

  • Large histories can time out. IXO Blocksync has no composite index for reading claims, signed transactions or received messages of one account in order: each read filters on the account and sorts what it finds, so an address with a very large history can hit the 8 s statement timeout (index_timeout).
  • Received transactions come from each message's recipient field. A MsgMultiSend output, and a send that is not the first message inside an authz MsgExec, are not seen.
  • IBC tokens can show unverified. The IBC transfer module registers metadata whose display unit is the trace path with only the base unit listed, so the chain's own metadata cannot verify an IBC token. A token outside the IBC table shows unverified, in base units, with its trace. Add it with IXO_CHAIN_IBC_DENOMS.
  • Core kinds keep base units. Only the chain and indexed kinds, the overview and get_account_balances convert bank coins.
  • Arguments are checked per request. The chain_lookup schema names the kinds but not their arguments (from 0.39.0 the description lists their names only), so a wrong key or value costs a round trip through invalid_input instead of a tool error.
  • Names can be missing or look-alike. A name that does not arrive in time, or a worker that is down, leaves an address unnamed. A selfChosen name proves nothing about who holds the address.
  • On-demand by default. The model must load the plugin, or the capability router preload it, before the tools exist on a thread. Use the override above to have them on every turn.

When to use it

  • The user asks about their IXO balance or tokens.
  • The user asks a broad question about their account.
  • The user asks about staking, grants, governance or their DAOs.
  • The user asks about their claims, a claim collection, or an entity or DID.
  • The user asks what happened on chain (sent or received transactions).
  • The user asks what a did:ixo:… identifier is, or who an address belongs to.

When not to use it

  • Preparing or sending a transfer. These tools only read. In a Portal chat, ixo-transaction prepares chain transactions and DAO DAO steps for the user's wallet, using the addresses these tools find.
  • Anything that is not public chain data.