FACTA

register.file

Version
0.1.0
Terms named on this page

Reads each identity's registration file under fixed fetch rules, keeps a hash of it, keeps only a short list of validated fields, and records every change.

Changelog

Changelog
VersionDateChange
0.1.0
2026-11-11
First version.

What it measures

  • Whether the file behind the registration URI can be read under the fetch rules, and whether it is a registration file.
  • The SHA-256 of the file's bytes, as fetched.
  • A short list of fields the operator declares: a name, a description, up to 16 services, x402Support, active, up to 8 supportedTrust entries, and whether the file names this identity in its registrations.

Everything in those fields is the operator's own words. It is data about the subject, never a term, a status or an instruction from FACTA. Every surface shows it as a quotation under the label "Declared by the subject, not checked", after the terms.

It does not check that a declared field is true.

Inputs

The URI from register.identity. Three kinds are read:

  • https:// URLs, fetched over the network.
  • Inline data: URIs, decoded locally.
  • ipfs:// URIs, through a public gateway, when the URI is a content identifier of letters and digits with a path that holds no .., ?, # or backslash. When the identifier names the file's bytes by their own SHA-256 (a CIDv1 of raw bytes hashed with sha2-256, with no path under it), what a gateway serves must hash to that digest: other bytes are not the file, and the next gateway is asked. The answer then says the file was checked against its content identifier. Any other identifier, such as a CIDv0 (Qm...), a CIDv1 of dag-pb or a path under one, names a block that encodes the file, and the bytes cannot be checked against it without that block: they are as the gateway served them, and the answer says they were not checked against the content identifier.

Every other scheme, http:// included, is not requested: the detail reads Not requested: the scheme is not allowed. A URI that is no link at all, such as free text an operator registered, is not requested either, and the detail reads Not requested: the registration URI is not a link. So is a URI that starts as https:// and is no URL, such as https:// alone or a template's https://<your-domain>/agent.json, with the same detail; its scheme on record stays https. Either way the identity is Unreachable, and the URI is shown as the subject's own words, never as a link. Its scheme on record is other (register.identity), its file status is unreachable, and FACTA's own read of the file, kept among the probe results, is not_probed with that detail.

The scheme other with the file status invalid marks one thing only: a URI the full read could not read within its limits. A URI longer than 16,384 bytes is kept as its first 256 characters, and an identity whose answer was over the response cap even alone is kept with no URI. Neither is requested, and the detail says which: Not requested: the registration URI is longer than 16384 bytes, or Not requested: the registration URI could not be read within the response size limit.

The fetch rules

A registration URL is treated as hostile until proven otherwise:

  • No IP-literal host in any spelling, no localhost, no internal or single-label name, no credentials in the URL, no port other than 443 or one from 1024 up, never one of FACTA's own hosts.
  • At most three redirects, only to https://, each checked again by the same rules.
  • Five seconds. 256 KB of body. JSON or text only. No cookies. Fixed protocol headers only.
  • At most ten requests to one host in any 60 seconds.
  • The crawler says what it is in its User-Agent and links the page that explains it. An operator who wants it to stop writes to the contact on that page; the host is then never requested again, and its identities read Unreachable with that reason.
  • robots.txt is not read: the crawler fetches only the address an operator registered on-chain for its own agent.

What a registration file is

A JSON object whose type is https://eips.ethereum.org/EIPS/eip-8004#registration-v1. Services are read from services and from endpoints: older files use the second name. A file binds itself to this identity when an entry of registrations names the registry eip155:4663:0x8004a169fb4a3325136eb29fa0ceb6d2e539a432 (compared without case) and this identity's ID.

The validator is written by hand. It keeps only the fields listed above, cleans every string of control, format and invisible characters, and cuts it to its limit. A service endpoint longer than its limit is dropped, never cut: a cut URL is a different URL. Everything else in the file is dropped without being kept.

What a body may cost before it is parsed

A step has 10 ms of CPU, and parsing is where it goes. A body's cost is not its length: it is its structure. The parser pays for every array, every object, every key and every value, and nothing for a long string.

Before a body is parsed, one scan counts two things:

  • How deep it nests. More than 64 levels is invalid without being parsed.
  • Its parts: every opening bracket, every comma and every colon outside a string. An object of n keys counts 2n, an array of n values counts n, a string counts nothing. More than 4,000 parts is invalid without being parsed. A file that lists 500 services, each with a name, an endpoint and a version, is about 3,500 parts.

Measured in Node 24.17 on 2026-11-11, medians, each body 256 KB:

What a body may cost before it is parsed
BodyScan and parse
One long string
0.4 ms
One object of about 25,000 short keys. Refused now, in under 1 ms
16.8 ms
9,990 objects of one key each, every key different. Refused now, in under 1 ms
20.8 ms
[ repeated. Refused, in under 1 ms
about 15 ms to refuse in the parser
The worst body still parsed: about 1,330 objects of one key each, every key different, or one object of about 2,000 keys
1.5 ms

A step parses at most 300,000 bytes and at most 8,000 parts in all its files together. Bytes alone do not bound a step: a body at its limit of parts can be as small as 15 KB. Each file is counted before it is parsed. One that does not fit what is left of the step is not parsed: it is not an attempt, it stays due, the step takes no more files, and the next step starts with it and has the whole budget for it. A file whose bytes are the ones on file is hashed and not parsed, and costs nothing of the budget.

Outcomes

Outcomes
OutcomeFile statusTerm this method sets
A valid file that declares no service that could be asked (no https endpoint)
ok
Card only
A valid file that declares services
ok
none: register.liveness probes them
What came back is not a registration file
invalid
Unreachable
A URI the full read could not read within its limits; not requested
invalid
Unreachable
A URI of another scheme, or no link at all; not requested
unreachable
Unreachable
HTTP 404, 410 or another refusal by the server; a refusal by the fetch rules; a host whose operator asked the crawler to stay away
unreachable
Unreachable
HTTP 429, any 5xx, a timeout or a network error, the first and second time in a row
unchanged
unchanged
The same, the third time in a row
unreachable
Unreachable
The per-host limit or the request budget held the request back
unchanged
unchanged; not an attempt
The chain no longer names the URI on record
unchanged
unchanged; not requested, not an attempt
Read with a URI the chain moved to one longer than any a row holds, and not told apart from it in that step
unchanged
unchanged; not requested, not an attempt; read again at the next pass

A valid file that replaces another keeps the liveness term only when the probes the term rests on are exactly the probes the new file gets; otherwise the term is cleared and register.liveness probes the new services (see that page).

The term this method sets rests on FACTA's own read of the file. That read is kept among the probe results, marked kind: 'file': FACTA's read, never a service the subject declared.

A term never gets worse on one failed attempt. A passing failure keeps what the row had and is due again six hours later. Only the third in a row is a result. Meanwhile the answer names the registration file under stale: what is shown comes from an earlier read, given with that read's time, or, for a file at this URI that has not been read yet, it says so and gives no time as a read; and it says from when the file is due again. A file not requested for more than 14 days is named too, with the time of its last good read, and the answer says no time can be given for the next one.

A timeout or a network error is a failed attempt whether it comes before the response headers or after them. A host can send HTTP 200 and then stall the body past the five seconds, or drop the connection in the middle of it. The file is in the body, and the body did not arrive: that attempt failed like any other, its detail reads HTTP 200, then no full answer: timeout (or network error), and it is never recorded as unreachable on its own. One case is decided by the status: when the headers carried a status that is a result by itself (a redirect that cannot be followed, a 404, a 410, another 4xx except 429), that status is the result, because the body of such an answer is never read as a file. A 429 and a 5xx stay passing failures with or without their body.

A file is read as the agent's only while the chain still names its URI. The full read (register.identity) reads each identity about once a window, so the URI on record can be a day or two behind the chain. A file fetched from an address the agent has left is not the agent's file, whatever it holds: its 404 would make the agent Unreachable, and another file there would be recorded as a change of the agent's file. So, right after it reads its rows and before it fetches any file, a step reads tokenURI of every row it is about to fetch from a URL, at the head of the chain, in one request. A row whose URI the chain no longer names is not fetched: nothing is written, and it stays due until the full read has recorded the URI the chain names. It does not hold the sweep: the step goes on past it, and the next pass of the table meets it again. An inline file is the URI itself and needs no such read. A read that fails fails the step. An upload from the batch lane is checked the same way, and an item whose URI the chain no longer names is rejected alone.

A URI the chain moved to a longer one never stops the sweep. The answer to that read carries every URI whole, and it is capped at 300,000 bytes. When it is over the cap, the rows are cut into parts of at most eight and read again, at most five requests a step in all. A URI a row holds is at most 16,384 bytes, and those of eight rows always fit the cap. So a part of eight rows or fewer that is still over it holds a URI the chain has moved to one longer than any a row holds: that part is cut in two and read again while the step has requests left, and a URI over the cap alone is not the one on record. The rows of such a part that the step could not tell apart are passed as a moved row is: not fetched, still due, and met again by the next pass. A row whose part the reads did not reach is fetched by a later step, which starts with it. When the first read is over the cap, the second holds the step's first rows, and the step settles them whatever the chain names: its cursor never stays where it was for a URI.

A read is written only onto the row it was made from. A step reads a row, fetches its file, and writes. The write applies only while the row still has the URI that was fetched and has not been written by any job since the step read it. Otherwise it is dropped: a file fetched from an old URI is never stored under the new one, and a liveness term another job set meanwhile is not overwritten from an older view of the row. The row keeps what the other job wrote, stays due where it is still due, and the sweep reads it again as it then is. An upload from the batch lane is written under the same condition.

A notice is recorded only with the write it belongs to. A write that records a changed file is followed, in the same batch, by a check that the row now holds what the write set. When the write was dropped, the check fails, and the database undoes the whole batch, notice included. The step counts as a failed attempt and runs again from the row as it then is; an upload is answered as not saved, to be sent again. No notice describes a file the row does not hold.

Thresholds

Thresholds
ThresholdValue
Files a step
30
Files from one host a step
10
URIs read on chain before the files
Every row the step fetches from a URL, at the head, in one request. An answer over the size cap cuts the rows into parts of at most eight, and a part of eight or fewer still over it in two, at most five requests a step
Parsed a step
At most 300,000 bytes and 8,000 parts, counted before each file is parsed. A file that does not fit what is left stays due, and the step takes no more files
Body cap
256 KB
Structure of one body before parsing
At most 64 levels of nesting and 4,000 parts (opening brackets, commas and colons outside strings); more is invalid
Timeout
5 seconds
Attempts before a passing failure is a result
3, six hours apart
A step's page
The due rows among the next 500 IDs past the cursor, at most 200 of them. Reading the page reads at most 502 rows, whatever the rows hold, and each write one more
Sweep window
7 days. A pass reads the table page by page and is followed by a wait of six hours; an identity added meanwhile is found by the next pass. The run ends with the first pass that ends after its window
Services kept
16
Text limits
name 200, description 1,000, service name 64, endpoint 512, version 32, trust entry 64 characters
Stale
14 days without a request of the file, or a last attempt that failed for a passing reason

A file whose hash equals the stored one is not parsed again.

Evidence

Evidence
FigureValueEvidence
registration_file_hash
0x and 64 hex characters
The URL, the time of the fetch that returned this hash, and the SHA-256 of the body; for an inline file, the tokenURI(uint256) call that holds it

The row keeps two times, and they are not the same thing:

  • The last attempt, whatever its outcome. It tells the sweep when the file is due again. A timeout, a 404 and a refusal move it.
  • The last fetch that returned the hash on file. Only a fetch that returned a body moves it: a valid file, the same bytes again (hashed, not parsed), or a body that is not a registration file. A fetch that failed, was cut off or was refused leaves it alone.

The figure's evidence cites the second: the fetch that returned the hash, never a later attempt that failed. A hash whose fetch has no time on file has no figure. The answer's record gives both: the hash with the time of the fetch that returned it (file.hashAt), and the last attempt (file.fetchedAt), which is never shown as the time the file was read.

When a file changes

A changed hash is a registration_file_changed notice. Its evidence holds two fetches that each returned a body: the fetch that returned the old hash, with its time, and the fetch that returned the new hash, with its time. since is the time of the first of the two: the last fetch that returned the old hash.

  • A failed fetch dates nothing and is evidence of nothing. A change found after failed attempts is dated from the last fetch that returned the old hash, however long ago that was. The window is as wide as what was observed: usually about a week, and longer when attempts in between failed.
  • A body that is not a registration file has a hash too. A change from a valid file to such a body is a notice, and so is the change from that body to the next valid file.
  • A first read is not a change. With no time on file for the stored hash, the row is updated and no notice is written: a notice names the fetch that showed the old file.
  • When the registration URI itself changes, the hash on file and its time are cleared, so the first read of the new URI is compared with nothing. That change is a notice of register.identity, which carries no file hash.

Recomputation

pnpm tool packages/register/recompute.ts --envelope <answer.json> --rpc <endpoint>

It reads the URI from the chain, fetches the file under the same fetch rules, and compares the SHA-256 with the published registration_file_hash. A file that changed since the answer was made shows as a mismatch.

The batch lane reads files with the same function as the step lane and uploads them. An upload says unreachable only of a file the batch lane requested, and the server records it with the detail Batch read: requested, and no registration file came back. A URI the fetch rules do not request (free text, another scheme, a host whose operator asked the crawler to stay away, a URL refused before sending) is reported as nothing to record, and the step lane records it as not requested, with the reason. Whatever an upload says, the server writes a URI that is never requested (free text, another scheme, an https URI that is no URL) as not requested, in the step lane's words, and refuses an item that says such a file was read. The server reads every inline file of an upload again, and three other files chosen at random, whatever the upload says of them, with the same functions. From what it fetched it derives each of those items again: its status, its hash and its fields. It refuses the whole upload when one of them differs, when a file the upload calls unreachable reads, when its own fetcher would not request a file the upload calls unreachable, when it cannot read a sampled file again, or when the sample would take more parsing than one step may do: 300,000 bytes and 8,000 parts.

Known ways to game it, and what the method does

Known ways to game it, and what the method does
WayWhat the method does
A huge body, deep nesting, or a body that never ends
256 KB and five seconds at most; a body that does not parse is invalid. A body that never ends is a failed attempt, tried again six hours later, and the file is unreachable after the third in a row
256 KB of [, of empty arrays, or of one object with tens of thousands of keys, to spend a step's CPU in the parser
Refused before parsing by the structure limits: invalid. In Node the scan refused each in under 1 ms, and the sweep goes on to the next file
Many small files that are each dense in structure, registered under neighbouring IDs, so that one step parses many of them
A step parses at most 8,000 parts in all: two files at the limit of one. The others stay due for the next steps
A second large file right after the first, so that a step parses both
Each file is counted before it is parsed. The one that does not fit what is left of the step is not parsed and stays due
A script, a direction-override character or a vocabulary term in the name
The name is kept as text, cleaned of invisible characters, and shown only as a quotation under its label. No term is ever read from a file
500 services
16 are kept. A file of more than 4,000 parts is invalid whatever it lists
Serving one file to the crawler and another to people
The method records what it was served, with its hash. It cannot see what others are served
Changing the file often, to fill the notice feed
Each read finds at most one change; the file is read about weekly
Changing the file, then failing one fetch on purpose, to choose when the change appears to have happened. The crawler names itself, so a server can tell its requests apart
A failed fetch moves only the time the file is due again. The notice's window starts at the last fetch that returned the old hash, and its evidence names that fetch
Moving the registration URI, then serving something else, or a 404, at the old address before the full read sees the move
The URI on chain is read before any file is fetched. A row whose URI the chain no longer names is not fetched, and nothing is written for it until the new URI is on record
Moving the URI again and again, or registering a URI such as https://, so that the sweep keeps one row due and reads the whole table for it at every step
Each step reads one page of 500 IDs, whatever its rows hold, and moves past a row whose URI has moved. A URI that is no URL is recorded as not requested at once. A run reads the table once a pass, a pass is followed by six hours, and the run ends after its window: in a test on 25,000 identities with one such row, a day took 150 steps and 75,297 rows read, where it took 300 steps and 7,500,000 rows
Moving many URIs to tens of kilobytes on chain before the full read sees it, so that every read of the URIs is over the size cap and the sweep stops at them
The rows are cut into parts of at most eight, within five requests a step. The URIs of eight rows always fit the cap, at the longest a row holds, so a part of eight or fewer that is still over it holds a moved URI: its rows are passed like moved rows, stay due, and the sweep goes on. A part the reads did not reach is read by the next step. In a test on 25,000 identities, read through the same reader as the Worker's, sixteen URIs moved to 40,000 bytes cost a day of 150 steps and 75,346 rows read, and every other due file was read that day. Before this rule the same day took 300 steps at them and read no file after them, until the full read recorded the long URIs. What it still costs is under Limits
Many identities on one host, to slow the sweep
Ten files a host a minute: the host's own files are read more slowly; nobody else's are
A redirect to a private address, a loop, or a credentials URL
Refused by the fetch rules: Unreachable
A gateway that serves other bytes for an agent's ipfs:// file
For an identifier that names the bytes by their SHA-256, a gateway's other bytes are refused and the next gateway is asked. For any other identifier the method cannot tell, and the answer says the file was not checked against its content identifier. The two default gateways, ipfs.io and dweb.link, are run by one operator
An upload from the batch lane that carries fields a file never held under the file's correct hash, or calls a readable file unreachable
Only a signed upload is read. The server reads a sample of each upload again and derives the items itself, fields included; one that differs refuses the whole upload

Limits

  • A file that is not of the ERC-8004 registration type is invalid, even when it carries a name and services. The type is stated by the ERC.
  • A registration file of more than 4,000 parts is invalid, also when it is well formed. The limit is on what parsing costs, and it is the same for every file.
  • A large file that arrives when a step has little of its parse budget left is fetched twice: once by that step, which does not parse it, and once by the next.
  • A file is read about once a week; a change between two reads is seen at the second. The method does not know when in between it happened, and a change that was undone between two reads is not seen.
  • When the URI changes on chain, the file at the new URI is read only once the full read has recorded the change, up to one window of the full read later, and then at the sweep's next pass. Until then the answer shows the old URI and what was read there, with their times.
  • A pass reads every page of the table, also when few rows are due: a pass of 25,000 identities is 50 steps.
  • Each step that fetches files from URLs makes two more requests first: the head of the chain, and the read of their URIs at it.
  • What a long new URI costs. A URI the chain moved to one longer than any a row holds is not known as such until the full read records it, up to one window of the full read later. Until then, each step that reaches its row reads the URIs again in parts, up to five requests where it makes two. And the rows read with it in a part of eight or fewer that is over the size cap are passed with it: up to seven other rows wait for the next pass, and wait again at each pass while the long URIs stay unrecorded. Nothing is written for them meanwhile: what is shown of their files is the last read, with its time, when there is one.
  • Fields are what the operator declares. Nothing here checks them.

What exists elsewhere

Toll's agent census (https://t0ll.xyz/agents/census) reads every identity's card and counts the broken ones: 11,070 of 22,843 on 2026-11-10. Its test of a broken card is its own; this page states FACTA's, so the two totals can differ. 8004scan (https://8004scan.io) and a provider-run ERC-8004 explorer show registration files too.