e4cead319d
Aere Network public source. Everything here can be checked against the live chain (chain id 2800, https://rpc.aere.network). Scope note, stated up front rather than buried: consensus on chain 2800 is classical secp256k1 ECDSA QBFT. The post-quantum work in this repository is at the signature, precompile, account and transport layers. Nothing here makes the consensus post-quantum, and no document in it should be read as claiming so.
251 lines
13 KiB
Markdown
251 lines
13 KiB
Markdown
# Aere VSM: Verifiable Semantic Memory for AI Agents
|
|
|
|
Status: on-chain registry, attested retrieval, and AERE402 paid query are BUILT and TESTED [VERIFY].
|
|
The embedding model, the vector similarity search, and the raw vector data are OFF-CHAIN [MEASURE].
|
|
|
|
Contract: `aerenew/contracts/contracts/agentic/AereVectorStore.sol` (solc 0.8.23).
|
|
Tests: `aerenew/contracts/test/aere-vector-store.test.js` (8 passing, Falcon mocked in test).
|
|
|
|
---
|
|
|
|
## 1. What this is
|
|
|
|
An AI agent's long-term memory is a vector store: text, decisions, and preferences are turned
|
|
into embeddings and indexed for nearest-neighbour retrieval. Today that memory has no clear
|
|
owner, no verifiable history, and no way for a consumer to check that a returned result was
|
|
really part of the memory the agent claims to hold. Switch provider and the memory dies with
|
|
the vendor.
|
|
|
|
Aere VSM gives an agent's vector store three on-chain properties it does not have anywhere else:
|
|
|
|
1. A clear OWNER, an account or an agent identity that the memory is bound to.
|
|
2. A verifiable, APPEND-ONLY HISTORY of committed memory states, each optionally authenticated
|
|
by a post-quantum Falcon-512 signature verified in full on-chain.
|
|
3. PAID, ATTESTED RETRIEVAL, so a retrieval provider can attest "for this query, against this
|
|
committed memory version, these are the results", metered through the existing AERE402
|
|
agentic payment rail, and a consumer can verify a returned vector was actually committed.
|
|
|
|
This is the "decentralized AI memory" idea anchored to Aere's live post-quantum precompiles and
|
|
its existing payment rail. It is deliberately honest about the boundary between what a chain can
|
|
prove (provenance, ownership, that a retrieval named a committed version) and what it cannot
|
|
(that the embeddings are semantically good).
|
|
|
|
---
|
|
|
|
## 2. Architecture
|
|
|
|
```
|
|
OFF-CHAIN [MEASURE] ON-CHAIN [VERIFY] (chain 2800)
|
|
------------------------------ ------------------------------------------
|
|
documents / events / prefs
|
|
|
|
|
v embedding model AereVectorStore.sol
|
|
vectors + metadata ------------------------------------------
|
|
| createStore(storeId, falconPubKey?, token?,
|
|
v build index + Merkle root price?, recipient?)
|
|
vectorRoot = Merkle/commitment -------> commit(storeId, vectorRoot, vectorCount,
|
|
over the vectors uri, falconSig)
|
|
| - post-quantum store: falconSig verified
|
|
v publish snapshot via 0x0AE1 (Falcon-512), fail-closed
|
|
uri (ipfs:// / https://) - classical store: msg.sender == owner
|
|
- append-only version history
|
|
|
|
query embedding paidQuery(storeId, queryHash, agentId, amount,
|
|
| nonce, deadline, authSig)
|
|
v similarity search (ANN) - settles on the AERE402 rail (references
|
|
candidate vectors -------------------> AERE402Facilitator, does not redeploy it)
|
|
| - mints a receipt bound to (store, query)
|
|
v Merkle proofs + resultRoot
|
|
result set attestRetrieval(storeId, version, queryHash,
|
|
resultRoot, receiptId)
|
|
- version must exist (fail-closed)
|
|
- priced store: consumes a paid receipt
|
|
- records the provider's attestation
|
|
|
|
consumer holds a returned vector -------> verifyVectorInclusion(storeId, version,
|
|
leaf, proof) -> membership in the
|
|
committed vectorRoot
|
|
verifyResultInclusion(retrievalId, leaf, proof)
|
|
-> membership in the attested resultRoot
|
|
```
|
|
|
|
The flow is: embed and index OFF-CHAIN, commit the root ON-CHAIN, attest retrieval ON-CHAIN,
|
|
pay for the query on the AERE402 rail, and let the consumer verify inclusion against the
|
|
committed root.
|
|
|
|
---
|
|
|
|
## 3. The on-chain object model
|
|
|
|
### Store
|
|
|
|
A store is created once and its configuration is FIXED at creation (no setter for the Falcon
|
|
key, the price, the settlement token, or the recipient). A store is either:
|
|
|
|
- CLASSICAL: no Falcon key. Commits require `msg.sender == owner`.
|
|
- POST-QUANTUM: a 897-byte Falcon-512 public key (header `0x09`). Commits require a Falcon
|
|
signature that verifies on-chain via the live precompile at `0x0AE1`. Authorship IS the
|
|
signature, so any relayer may submit the transaction and only the key holder can produce a
|
|
valid commit.
|
|
|
|
### Version (append-only)
|
|
|
|
Each `commit` appends a new `Version { vectorRoot, vectorCount, committedAt, blockNumber, uri }`.
|
|
Version numbers start at 1 and increase by exactly one. No function can overwrite or delete a
|
|
committed version. The current root and every past version stay queryable forever. There is no
|
|
admin, no owner override, and no upgrade hook, so there is nothing that can rewrite a committed
|
|
root.
|
|
|
|
### Retrieval attestation
|
|
|
|
`attestRetrieval(storeId, version, queryHash, resultRoot, receiptId)` records that a provider
|
|
(the transaction sender) attests: for `queryHash`, run against committed store `version`, the
|
|
returned result set is committed by `resultRoot`. The named version MUST exist (1..current) or
|
|
the call reverts, so an attestation can never point at a store state that was never committed.
|
|
|
|
### Paid query receipt
|
|
|
|
On a priced store, `paidQuery` settles a payment on the AERE402 rail and mints a
|
|
`QueryReceipt` bound to `(storeId, queryHash, agentId, nonce)`. A retrieval attestation on a
|
|
priced store must cite a matching, unconsumed receipt; the receipt is consumed one-shot.
|
|
|
|
---
|
|
|
|
## 4. Post-quantum authentication
|
|
|
|
A post-quantum store's commit is authenticated by a Falcon-512 signature over a per-version
|
|
challenge:
|
|
|
|
```
|
|
challenge = keccak256(abi.encode(
|
|
COMMIT_DOMAIN, block.chainid, address(this),
|
|
storeId, version, vectorRoot, vectorCount, keccak256(bytes(uri))))
|
|
```
|
|
|
|
The challenge binds the chain, this contract, the store, the exact version, the committed root,
|
|
the vector count, and the URI. Because `version` is part of the challenge and advances by one
|
|
per commit, a signature is single-use and cannot be replayed onto a later version.
|
|
|
|
Verification uses the same input construction as `AerePQCAttestation.sol`, restricted to
|
|
Falcon-512 at `0x0AE1`:
|
|
|
|
```
|
|
falconSig = nonce(40) || esig (the envelope handed to commit)
|
|
input = pk(897) || sm
|
|
sm = sigLen(2, big-endian) || nonce(40) || challenge(32) || esig
|
|
esig = 0x29 || compressedSig, sigLen == esig.length
|
|
```
|
|
|
|
The precompile returns a 32-byte word, `0x..01` for valid and `0x..00` otherwise. An empty or
|
|
zero return, which is what a pre-fork node with no precompile would produce, is treated as
|
|
INVALID, so a stale caller can never record a commit. A commit whose Falcon signature does not
|
|
verify reverts `PQCVerificationFailed` and records nothing (fail-closed).
|
|
|
|
The live Falcon-512 precompile at `0x0AE1` was activated on mainnet 2800 at block 9,189,161
|
|
(see `besu_pqc_fork_proven_2026-07-11`). In the Hardhat test suite the precompile is mocked
|
|
(`MockPQCPrecompile`, installed at `0x0AE1` via `hardhat_setCode`), which parses the input at
|
|
the precompile's spec offsets; the real Falcon-512 encoding is proven separately against the
|
|
LIVE mainnet precompile by the `AerePQCAttestation` verification path [VERIFY].
|
|
|
|
---
|
|
|
|
## 5. Paid query on the AERE402 rail
|
|
|
|
Aere VSM references the existing `AERE402Facilitator` (the agentic payment rail); it does NOT
|
|
redeploy or fork it, and it introduces NO new token. Queries settle in whatever ERC-20 the store
|
|
owner selects (for example WAERE or USDC.e).
|
|
|
|
`paidQuery` works as an on-chain AERE402 provider endpoint:
|
|
|
|
1. The paying agent authorizes the payment with its EIP-712 `PaymentAuth` signature to the
|
|
facilitator, exactly as any AERE402 payment, with the vector store as the `payee`.
|
|
2. `paidQuery` calls `FACILITATOR.settle(...)`. Because the vector store is both the caller and
|
|
the payee, the facilitator's own `msg.sender == payee` guard is satisfied. The facilitator
|
|
debits the agent's prepaid balance, takes the 25-bps protocol fee to AereSink, and transfers
|
|
the remainder to the vector store.
|
|
3. The vector store measures the exact amount it received (a balance delta, robust to a changed
|
|
fee) and forwards it, in the same transaction, to the store's payment recipient. The contract
|
|
custodies no balance across calls, and it never holds an agent's funds.
|
|
4. A receipt is minted, bound to `(store, query)`, that a retrieval provider can later cite.
|
|
|
|
On a priced store, `attestRetrieval` reverts `PaymentRequired` when no valid receipt is cited,
|
|
`ReceiptConsumed` on reuse, and `ReceiptMismatch` when the receipt was paid for a different
|
|
store or query. This is the payment gate: a metered retrieval must be backed by a real,
|
|
on-chain settlement on the AERE402 rail.
|
|
|
|
---
|
|
|
|
## 6. Trust model
|
|
|
|
### What the on-chain part GUARANTEES [VERIFY]
|
|
|
|
- AUTHENTICITY of a committed root. A post-quantum store's commit carries a Falcon-512 signature
|
|
verified in full on-chain. An invalid signature records nothing.
|
|
- APPEND-ONLY HISTORY and IMMUTABILITY. No path rewrites or deletes a committed version; there is
|
|
no admin and no owner override over committed roots.
|
|
- OWNERSHIP. Every store is bound to an owner at creation; a classical store's commits require
|
|
the owner, a post-quantum store's commits require the Falcon key.
|
|
- RETRIEVAL AGAINST A COMMITTED VERSION. An attestation can only name a version that was actually
|
|
committed, and it records who attested it.
|
|
- INCLUSION. A consumer can prove, on-chain, that a returned vector was a member of a committed
|
|
version's `vectorRoot` (`verifyVectorInclusion`) and of a provider's attested `resultRoot`
|
|
(`verifyResultInclusion`).
|
|
- PAID, METERED RETRIEVAL. On a priced store, a retrieval attestation is backed one-for-one by an
|
|
AERE402 payment.
|
|
|
|
### What the on-chain part does NOT guarantee (OFF-CHAIN, [MEASURE])
|
|
|
|
- It does NOT compute embeddings, does NOT run the similarity search, and does NOT hold the
|
|
vectors. The embedding model, the nearest-neighbour index, and the raw vector data all live
|
|
off-chain.
|
|
- It does NOT and CANNOT prove that the embeddings are SEMANTICALLY GOOD, that the index is
|
|
well-built, or that the provider ran an honest similarity search. On-chain attestation proves
|
|
PROVENANCE and OWNERSHIP of a committed root and that a retrieval named a committed version. It
|
|
does NOT prove RELEVANCE. Semantic quality is an off-chain property, measured off-chain
|
|
[MEASURE].
|
|
- Inclusion in `resultRoot` proves the provider committed to returning that result; it does not
|
|
prove the result was the best or the correct nearest neighbour for the query.
|
|
|
|
### Scope boundary
|
|
|
|
Aere VSM is application-layer PQC authentication plus settlement. It does NOT change Aere
|
|
consensus: blocks are still produced and signed by Besu QBFT validators with classical ECDSA
|
|
(secp256k1). PQC-authenticated memory commits do NOT make consensus post-quantum. What is
|
|
post-quantum here is the AUTHENTICITY of a store commit, through the live Falcon-512 precompile.
|
|
|
|
---
|
|
|
|
## 7. Honest status
|
|
|
|
| Component | Status | Flag |
|
|
| --- | --- | --- |
|
|
| On-chain commit registry, versioned + append-only | Built, tested | [VERIFY] |
|
|
| Falcon-512 authenticated commits via `0x0AE1` | Built, tested (Falcon mocked in test) | [VERIFY] |
|
|
| Falcon-512 encoding vs the LIVE mainnet precompile | Proven separately (AerePQCAttestation) | [VERIFY] |
|
|
| Retrieval attestation, fail-closed on a missing version | Built, tested | [VERIFY] |
|
|
| Inclusion proofs (vectorRoot, resultRoot) | Built, tested | [VERIFY] |
|
|
| AERE402 paid-query gate | Built, tested against the real facilitator | [VERIFY] |
|
|
| Embedding model | Off-chain | [MEASURE] |
|
|
| Vector similarity search / index | Off-chain | [MEASURE] |
|
|
| Raw vector data + semantic quality / relevance | Off-chain | [MEASURE] |
|
|
|
|
The on-chain layer is built and tested. The semantic layer (embeddings, similarity search, and
|
|
the vector data) is off-chain research-frontier work, and its quality is measured off-chain, not
|
|
proven on-chain.
|
|
|
|
---
|
|
|
|
## 8. Test result
|
|
|
|
`npx hardhat test test/aere-vector-store.test.js`, run from `aerenew/contracts`, reports
|
|
8 passing:
|
|
|
|
1. commits a PQC store version 1, then version 2, preserving history append-only
|
|
2. rejects a tampered Falcon signature fail-closed (nothing recorded)
|
|
3. treats an empty precompile return (pre-fork / stale node) as invalid
|
|
4. records a retrieval attestation against a committed version and reverts on a missing version
|
|
5. verifies an inclusion proof for a committed vector and rejects a non-member
|
|
6. meters a priced store on the AERE402 rail and gates attestRetrieval on payment
|
|
7. classical store: only the owner may commit
|
|
8. createStore rejects a malformed Falcon key and inconsistent price config
|