alexandria
Preserve heterogeneous lending-protocol captures by digest and expose a narrow, source-bound credit view for Tabularium and Probitas. Use when the user names Alexandria or asks to archive lending data for reproducible, address-scoped credit research. Raw release and registered Aave v4 and Clearpool derivation, disposable indexing, address queries and a checked-in offline demonstration, unsigned in-toto release statements, a bounded Compound v3 Phase 0 method proof and a resumable Ethereum USDC interval collector with per-subject implementation epochs and preserved Compound, Wildcat V1, Wildcat V2 and Aave V3 mainnet intervals are available.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-07
- Stars
- ★ 13
- Forks
- 6
01 前言 Front Matter
- name
- alexandria
- metadata
- { "version": "3.13.0" }
- description
- Preserve heterogeneous lending-protocol captures by digest and expose a narrow, source-bound credit view for Tabularium and Probitas. Use when the user names Alexandria or asks to archive lending data for reproducible, address-scoped credit research. Raw release and registered Aave v4 and Clearpool derivation, disposable indexing, address queries and a checked-in offline demonstration, unsigned in-toto release statements, a bounded Compound v3 Phase 0 method proof and a resumable Ethereum USDC interval collector with per-subject implementation epochs and preserved Compound, Wildcat V1, Wildcat V2 and Aave V3 mainnet intervals are available.
02 资源文件 3
- 参考文档agents/openai.yaml647 B
- 参考文档DEMONSTRATION.md13.0 KB
- 参考文档EVOLUTION.md16.8 KB
03 SKILL.md 正文
<p align="center"> <img src="../../assets/characters/alexandria.png" width="1200"> </p>
Alexandria
Frontier
Alexandria owns its own preservation and credit-view frontier, not Hexaemeron's delivery or Solidity frontier. Its version, held target, next job, and maturity state live in EVOLUTION.md. Do not recommend or run another frontier pass after that ledger becomes mature.
<!-- marketplace-context:start -->
Where this sits
Alexandria preserves heterogeneous lending captures byte for byte, then exposes only the source-bound credit view a reviewed mapping can defend.
Current frontier. Ordinary builds now emit alexandria-interval-receipt/v2, which attributes each preserved proxy log to an implementation epoch by block, transaction index and log index, and check re-derives every owner offline; reconciliation still compares a log without its transaction index, so a second provider that reports a different index for the same log records agreed.
<!-- marketplace-context:end -->
Alexandria is the archive and catalogue behind durable lending-protocol research. Raw captures remain unchanged. Tabularium owns their interpretation as venue-qualified credit events, and Probitas may consume those events in a dossier. Ariadne may bind a finished release to its evidence. Lazarus is the neighbouring specialist for the finite historical Ethereum state and exact RPC traffic one application test needs; it does not replace Alexandria's dataset boundary.
Synkrisis compares validated agent-run observations through a checked cohort, bounded findings, a fixed report, and whole-path verification. It cannot reinterpret an Alexandria release, treat release rows as run observations, or authorise a new capture.
$SKILL_DIR is the directory holding this file. The command lives at
$SKILL_DIR/../../scripts/alexandria.py; resolve it from where you loaded this
skill.
Day to day
Research. A protocol endpoint or hosted indexer may disappear. Preserve the exact response, its capture scope and its gaps before the only cheap copy is gone.
Credit. A counterparty record needs events, position observations and an account of the venues and intervals checked. An empty result without coverage is not a clean history.
Data engineering. Raw GraphQL responses, chain logs and replay fixtures do not need one payload schema. Bind their bytes in one manifest, then build a small, versioned credit view that points back to them.
Raw releases
Prepare a capture plan using the contracts under
$SKILL_DIR/../../schemas/. Every component path is relative to the plan's
directory. Every component has a public, restricted or private access
class and a permitted, restricted, prohibited or unknown redistribution
class. Give every capture a venue, an eip155 chain, a non-secret source
reference, an evidence and finality class, a full-dataset or subject-scoped
boundary and counted coverage or a stated gap. Then ingest it:
python3 "$SKILL_DIR/../../scripts/alexandria.py" ingest \
--plan capture-plan.json --output release
Ingest reads only the plan and its confined local source files. It copies raw
bytes unchanged into digest-derived paths, writes through a temporary sibling
directory and installs the release atomically. It refuses absolute paths,
traversal, symlinks and replacement of a different release. Record the
sha256:... release ID printed on success.
Verify before using or moving a release:
python3 "$SKILL_DIR/../../scripts/alexandria.py" verify release
Verification is offline and read-only. It checks canonical manifest bytes, release identity, object paths, byte counts, digests, component access and redistribution classes, capture source, scope, evidence and finality classes, collection counts, declared gaps, correction links and exact release-tree membership. It does not establish publisher identity, source completeness or chain finality.
A proof-backed-state capture earns that class only during verify: its
component must be a Lazarus manifest, every named fixture file must be present
by digest and byte count, Alexandria must reconstruct and rerun Lazarus, and
the capture must stay within the proved block and targets. Finality must be
unknown because Lazarus proves block binding but reports no finality class.
The scope must be subject-scoped and remain within the proof targets because a
finite proof set is not a full dataset. Missing Lazarus or its pinned packages
is a refusal because the claim is not earned until Lazarus has rechecked it;
install plugins/lazarus/requirements.lock beside this checkout. The refusal
names the capture that failed.
Emit a deterministic statement only after verification:
python3 "$SKILL_DIR/../../scripts/alexandria.py" statement release \
--output release-statement.json
The output must be outside and must not alias the release. The command emits a
canonical unsigned in-toto Statement v1 with one logical release subject, one
subject per manifest component, exact component metadata, and every capture's
declared scope, coverage status and counts, unsupported collections and gaps.
It includes one passed Alexandria offline-verification claim bound to the
release digest and an empty command list.
A single statement must stay within Ariadne's 8,388,608-byte input limit and
its 262,144-character key budget. A release past either bound is refused before
the output path is prepared, by a line naming the bound and a line pointing to
--parts, so a successful output stays inside Ariadne's default reader bounds.
Write such a release as a part set instead:
python3 "$SKILL_DIR/../../scripts/alexandria.py" statement release \
--parts release-statement-parts
The target directory must be absent. A directory beside it named
.<name>.tmp-<16 hexadecimal characters>, with the target's own name and
exactly 16 lowercase hexadecimal characters, refuses the run by name until it
is removed by hand, whatever made it. The target receives index.json and
part/part-<k>.json, each within 6,225,920 bytes and 262,144 key characters,
so Ariadne reads each file with its default bounds, bare or inside a DSSE
envelope whose own fields and signatures fit 87,380 bytes. Each part carries
a contiguous run of components and their captures; the index binds every part
by SHA-256. --parts refuses a release within both
single bounds and names --output, so each release has one statement form.
A holder checks the set with Ariadne verify on the index and on each part,
and each part's SHA-256 against its index subject. The
release statement guide gives
the wire shapes and limits.
Neither form is a DSSE envelope, and Alexandria does not run cosign. It does not authenticate a publisher or prove provider completeness, consensus finality or canonical-chain membership. Ariadne can inspect each statement and run its core gates, but these predicates are unregistered, signatures remain unchecked, and gates 2 and 5 remain unchecked.
Derive the narrow Tabularium view into a new release:
python3 "$SKILL_DIR/../../scripts/alexandria.py" derive raw-release \
--output derived-release
python3 "$SKILL_DIR/../../scripts/alexandria.py" verify derived-release
Derivation first verifies the input and never changes it. Registered Aave v4 and Clearpool mappings emit deterministic credit events and, where the source supplies position state, observations. Every row names the raw release, component digest, source and context selectors, mapping rule, adapter version and evidence class. Verification resolves those selectors, reruns the mappings and reconciles row, family, subject and coverage counts. Capture renames do not change row IDs, and repayment legs remain neutral source amounts unless the native record supplies a principal and interest split. Derivation stops above 100,000 rows or 64 MiB for either JSONL file.
Rebuild the disposable address index and query it:
python3 "$SKILL_DIR/../../scripts/alexandria.py" index derived-release \
--output alexandria.sqlite
python3 "$SKILL_DIR/../../scripts/alexandria.py" query \
--index alexandria.sqlite --address 0x...
Indexing verifies every derived release, refuses to write inside one and retains the derived release, raw release, component, capture and row identities. Querying opens SQLite read-only, checks its exact schema and logical digest, then matches every indexed partition to its release. Equivalent rows shared by cumulative releases appear once. Conflicting content under one row ID is refused.
A zero-row result is empty only when complete capture scope covers every requested address, venue, chain and time boundary and the mapping has no unsupported source records.
Probitas can consume that evidence only when the operator passes its explicit
--alexandria-index option. The translation retains the original venue and
evidence class, combines per-chain coverage conservatively and keeps registry
venues absent from the archive visible as gaps. It does not infer people,
defaults, full repayment or a current balance.
To exercise the whole path without a network, run the fixed demonstration from the repository root:
output="$(mktemp -d)/credit-history-v0"
python3 plugins/alexandria/examples/credit-history-v0/demo.py build --output "$output"
python3 plugins/alexandria/examples/credit-history-v0/demo.py verify "$output"
The plan pins existing Aave v4 and Clearpool files by digest. The result is a reproducibility fixture, not a production corpus. Its Aave v4 source remains provider-reported and its Clearpool source remains subject-scoped with unknown finality.
Compound v3 Phase 0
The Compound method-proof example pins all 28 production Comet deployments at one upstream commit and preserves two Ethereum USDC transactions. Its checker binds old-state access, nested calls, the proxy implementation and code, transaction-start storage, ordered storage writes and a provider-reported finalized boundary.
Generate the fixed registry from a local pinned checkout, or build and check a captured source tree offline:
python3 "$SKILL_DIR/../../scripts/compound_v3_phase0.py" registry \
--comet-repository <comet-checkout> --output registry.json
python3 "$SKILL_DIR/../../scripts/compound_v3_phase0.py" build \
--input <captured-input> --output <release>
python3 "$SKILL_DIR/../../scripts/compound_v3_phase0.py" check <release>
The separate capture subcommand is networked. It requires
ALEXANDRIA_COMPOUND_RPC_URL, omits the endpoint and headers from the release,
and collects only the fixed corpus. Do not describe the result as an interval
history, chain proof or independent finality check.
Collect a declared lending interval
Four commands, of which the first two reach a network:
python3 "$SKILL_DIR/../../scripts/usdc_interval.py" collect --plan plan.json --staging staging
python3 "$SKILL_DIR/../../scripts/usdc_interval.py" reconcile --plan plan.json --staging staging \
--provider-class "<non-secret class>"
python3 "$SKILL_DIR/../../scripts/usdc_interval.py" build --plan plan.json --staging staging \
--registry registry.json --created-at <timestamp> --output release
python3 "$SKILL_DIR/../../scripts/usdc_interval.py" check release
collect dispatches on the plan's registered venue: Compound v3, Wildcat V1,
Wildcat V2 or Aave V3. Compound keeps its single proxy plan; a v2 plan names the exact
subject set its pinned venue registry admits. It walks bounded shards over
the evidence classes the plan declares, binding its end boundary
under the plan's named finality policy before it asks for anything. It reads its
endpoint from ALEXANDRIA_COMPOUND_RPC_URL alone and writes it nowhere, and
sends Content-Type and a constant User-Agent built from the package version.
An explicitly configured bearer credential may be supplied through the supported
HTTPS transport; it never enters the plan, journal or diagnostic text. A checkpoint is
written only after a shard's bytes are fsynced, so a killed run resumes to
byte-identical journals; when a remembered boundary hash has changed, the run
rewinds to the deepest one that still matches, and refuses a reorg deeper than
its bounded trail. After the last shard it makes its opening reads -- the
interval's first block, the implementation slot at that block and at each
upgrade block, and each implementation's runtime code -- into a fourth
epoch-evidence journal under the same checkpoint rule, so a finalized or
safe plan now earns that finality class on every evidence scope with both
boundary hashes bound. Structured failure receipts name the code, shard, unresolved range and provider
class without copying provider or transport text. CLI error strings may instead
name only a read or shard; they do not universally include the provider class.
reconcile runs the finished interval past a second provider and records
agreement or dispute over boundary hashes, ordered transaction hashes and every
log's identity tuple. That tuple does not include the log's transaction index.
It settles nothing: a disputed shard becomes partial or failed, both
providers' bytes are kept, and a provider that cannot answer leaves the
interval unreconciled.
Both network commands take three concurrency limits. --concurrency (1 to 8,
default 4) sets how many shards fetch at once; as many again may wait fetched
behind a slower lower shard, and commits stay in shard order.
--trace-concurrency (1 to 16, default 4) is one total across every shard in
flight, not a window per shard. --rpc-concurrency (1 to 8, default 8) caps
every request, traces included, so a trace limit above it adds no calls. Past
512 MiB of request and response bytes, collect starts no new shard; shards
already started finish and commit, up to a hard stop at 1 GiB.
build emits an ordinary capture plan and calls ingest; check verifies the
release offline, re-derives every shard's record counts from the journals, and
re-hashes each implementation's runtime code out of the implementation-code
component. Implementation epochs come from discover_epochs over every
preserved proxy log, the EIP-1967 slot reads and the runtime code reads in the
epoch-evidence journal, and are bound by code hash because the pinned
CometExt.version() returns the constant string 0. build takes no --epochs
table: there is nothing left for an operator to supply.
A new release carries alexandria-interval-receipt/v2. Its epochs tile
exclusive positions of block, transaction index and log index,
log_attributions names each log's owner, and check re-derives both. An
ordinary log inside the upgrade transaction, an upgrade in the interval's first
block and two upgrades in one block refuse. A v1 release keeps its block-only
meaning, and an owner is an inference from the announcement's position, not
proof of the emitting implementation.
Wildcat releases carry one epoch table per subject, checked against that venue's registry and preserved code. A subject with no sourced deployment block uses preserved first-code evidence and retains the deployment-block gap. Each subject has its own epoch ceiling; the estate's sum is not the limit. Both mainnet captures use traces selected by matching subject logs, so a transaction with no such log is outside their trace coverage. Bounded concurrent requests share one global cap; completed shards alone advance the checkpoint. The combined demonstration rebuilds both estates and Compound without opening a Python socket.
A wildcat-v2 plan may declare wrapper instances in wildcat_v2_wrappers,
{"rule": "wrapper-deployed/v1", "subjects": [...]}, when its subjects
include the registry's wrapper factory. The declared wrappers join every
shard's address filter. After the shards, each one needs a preserved
WrapperDeployed log from that factory that names it and a registry market.
Its one epoch opens at that log's block, where the block's header and the
wrapper's runtime code are read into epoch-evidence. The release binds the
derived set as the wrapper-subjects component. check re-derives it byte
for byte and lists each wrapper, a declared one with its epoch and attributed
log count. Build and check refuse by name an unknown market, a declared
wrapper with no WrapperDeployed, a declared wrapper's WrapperDeployed log
whose block hash differs from the header read of its block, a declared
wrapper with no code at its first block and a wrapper log before its epoch. A
discovered wrapper the plan omits stays listed, and none of its logs is
requested. Wrapper immutability and single-factory provenance are not
established, and every wrapper release says so. Only constructed data has
exercised this path.
The aave-v3 venue captures the Ethereum main market's 356 subjects as twelve
segment releases, each a plan pinned by digest in reviewed code. Its epochs are
chosen per subject by registry role, and only this venue owns an ordinary log in
its upgrade transaction by position. The twelve staging trees are held outside
the repository as one archive bound by one committed manifest;
aave-v3-interval-v0
verify-preserved checks that metadata and rebuilds nothing, and the
proof records each segment's results.
A subject-set plan that declares shards_per_component may also declare
"log_attribution_parts": "journal-ranges". Its attribution rows then leave
the epoch table: part k is the component log-attributions.<k> and holds the
rows of every preserved log in the plan's kth journal range, the range
logs.<k> covers. Such a release carries alexandria-interval-receipt/v4,
which lists each part with its shards and row count, and check compares every
part with the rows it re-derives for that range. build and check refuse a
part above 67,108,864 bytes or 2,000,000 nodes. A release holds at most 16,384
components and 16,384 captures. A plan without the field builds the same bytes
it built before. The
collector document
states the rule in full.
Read the collector document for the
finality, epoch and reconciliation boundaries, run
examples/usdc-interval-v0 to see
the whole path offline over synthetic fixtures,
examples/usdc-interval-epochs-v0
to see positional owners over a synthetic upgrade block, and
examples/usdc-interval-live-v0
to rebuild the preserved live Ethereum mainnet interval. This release
establishes no publisher identity, no provider completeness, no consensus
finality and no canonical-chain membership, and derives no credit event;
Tabularium owns the separate canonical mapping. The
harvest specification still describes more
than this collector covers: one market of the pin's 28, and no state call or
configuration read.
Read the study for the selected construction and the runbook for the implementation boundaries.
Settled boundary
- Raw objects retain their exact bytes and native shapes.
- Release manifests bind components to capture scope and coverage.
- Tabularium mappings own the meaning of derived credit events and position observations.
- SQLite is a disposable address index, not release evidence.
- Probitas retains the original venue on every archive-backed record and keeps unharvested venue coverage visible.
- Lazarus fixtures may support selected observations but are not a universal archive payload.
A digest can establish that bytes match a manifest. It does not establish who published them, that an indexer captured a complete chain history, or that a reported block is canonical. Those claims require separate evidence.
Promise Machine contract
alexandria-raw-release
- Promise: A successful
ingestfollowed byverifypreserves the named local source bytes and binds them to the canonical manifest, release identity, declared capture boundary, coverage and gaps. - Evidence: The capture plan, copied objects, canonical manifest, printed release id and a passing
alexandria.py verifyresult for the same release directory. - Evidence classes: recorded, checked, recomputed
- Boundary: The result does not establish publisher identity, source completeness, chain finality or any fact outside the declared capture scope.
- Authorises: Retention or hand-off of the verified raw release as a bounded preservation artefact.
- Consequence: 2
- Refuses: Installing, moving or describing a release as verified when a source path, digest, byte count, scope, coverage declaration or tree-membership check is absent or fails.
- Recovery: Inspect the named verification failure, repair the plan or source set, ingest into a new output directory and rerun verification.
- Exceptions: none
alexandria-derived-view
- Promise: A successful
derivefollowed byverifyreproduces every emitted credit event and observation from a verified raw release under the named registered mapping and reconciles its selectors and counts. - Evidence: The verified raw release, adapter and mapping versions, derived JSONL, coverage records and a passing verification that reruns the mapping.
- Evidence classes: recorded, checked, recomputed
- Boundary: The view preserves venue and evidence classes; it does not infer default, full repayment, current balance, source completeness or universal event meaning.
- Authorises: Use of the verified derived release as bounded input to Tabularium or an explicitly archive-backed Probitas collection.
- Consequence: 2
- Refuses: Using rows whose source selectors do not resolve, whose counts conflict, whose mapping is unknown or whose raw release did not verify.
- Recovery: Inspect the failed selector, mapping or count, correct the adapter or source release without changing published evidence, derive a new release and verify it.
- Exceptions: none
alexandria-release-statement
- Promise: A successful
statementemits a canonical unsigned in-toto Statement v1 that exactly projects a verified Alexandria release, every component digest and every capture's declared scope, coverage and gaps. - Evidence: The verified release, canonical statement bytes, exact release and component subject set, Alexandria predicate projection and successful command receipt for the same logical release digest.
- Evidence classes: recorded, checked, recomputed
- Boundary: The output has no DSSE envelope or signature check, the Alexandria predicate is unregistered in Ariadne, and the result does not establish publisher identity, provider completeness, consensus finality or canonical-chain membership.
- Authorises: Hand-off of the unsigned statement bytes for Ariadne core-gate inspection or downstream signing without upgrading their evidence claims.
- Consequence: 1
- Refuses: Emitting from a release that does not verify, emitting bytes above Ariadne's default bounded-input limit, writing inside or through an alias of that release, omitting or changing a subject or predicate field, or describing unchecked signatures or predicate-owned gates as passed.
- Recovery: Inspect the verification, projection or output-confinement failure, repair the release or choose a safe external output, rerun
statementand retain only the successful replacement. - Exceptions: none
alexandria-address-query
- Promise: A successful
indexandqueryreturns only rows from verified derived partitions whose identities and logical digest match the disposable index. - Evidence: The verified derived releases, SQLite schema and logical digest checks, partition identities and the exact query result for the requested address.
- Evidence classes: checked, recomputed
- Boundary: SQLite is not release evidence, and zero rows does not mean a clean history unless complete declared coverage spans every requested address, venue, chain and time boundary with no unsupported records.
- Authorises: Presentation or downstream use of the source-bound query result with its coverage and gaps kept visible.
- Consequence: 1
- Refuses: Querying a mutable or mismatched index, collapsing conflicting rows, or presenting an uncovered zero-row result as absence of activity.
- Recovery: Rebuild the disposable index from verified releases, rerun the query and report any remaining coverage gap instead of a clean result.
- Exceptions: none
alexandria-compound-method-proof
- Promise: A successful Compound Phase 0
checkbinds the fixed registry and captured transaction witness to the named Comet revision, proxy implementation, code, old-state reads, calls and ordered writes under the implemented method. - Evidence: The pinned registry, captured input, built release and passing
compound_v3_phase0.py checkresult, including the proof-checked state relation and separately labelled provider records. - Evidence classes: recorded, checked, recomputed, proved: EIP-1186 state relation
- Boundary: The result covers the fixed corpus and implemented method only; it is not an interval history, independent canonical-chain proof, canonical Tabularium mapping or proof of receipts, logs or traces.
- Authorises: Use of the checked Phase 0 witness as bounded method evidence for the named transactions.
- Consequence: 1
- Refuses: Generalising the witness to another deployment, transaction, interval, implementation, layout or evidence class.
- Recovery: Inspect the named registry, implementation, state, call, write or selector mismatch, recapture under an amended fixed plan and rerun the check.
- Exceptions: none
alexandria-proof-backed-state
- Promise: A successful
verifyof a release whose capture claimsproof-backed-stateestablishes that the capture component is an embedded Lazarus fixture manifest, every file it names is present by digest, Lazarus's offline verifier accepted the reconstructed fixture, and the capture's chain, block, finality and subjects claim no more than that fixture proves. - Evidence: The verified Alexandria manifest and components, digest-and-byte-count fixture reconstruction, Lazarus verification report, bound capture fields and executable P/M/O/R/S cases in
plugins/alexandria/tests/test_proof_backed.py. - Evidence classes: recorded, checked, recomputed, proved: EIP-1186 state relation
- Boundary: The result does not establish canonical-chain membership, provider independence, source completeness or anything outside the named proof targets at the bound block; it borrows no verdict because Alexandria reruns Lazarus instead of trusting one.
- Authorises: Retaining or handing off the verified capture's
proof-backed-stateclass for its named subjects at the bound block. - Consequence: 1
- Refuses: Describing such a capture as verified when the sibling verifier is absent, the fixture is incomplete or altered, or the claim exceeds the proof.
- Recovery: Repair the plan or fixture, ingest into a new output and rerun
verify. - Exceptions: none
04 同仓库更多 Skills
example
A deliberately unsupported evidence class fixture.
example
A router fixture target.
promise-machine
A deliberately unresolved router.
example
A deliberately unclassified skill fixture.
example
A deliberately unattributed exception fixture.
example
A deliberately conflated version fixture.