aere-docs/AERE-VSM.md

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