advice-provider-hygiene

name	advice-provider-hygiene
description	Use when writing kernel, account, or note MASM code that reads from or writes to the advice provider (advice stack / advice map) — validate advice data.

Advice Provider Hygiene

Rules

The advice provider is untrusted input supplied by the (potentially adversarial) prover. Any kernel, account, or note procedure that touches it must follow three rules.

1. Validate advice data against a commitment

Before consuming data loaded from the advice provider:

1. Read the data from the advice stack / advice map into memory.
2. Compute its hash with Poseidon2 over the loaded region.
3. Assert the computed hash equals an expected commitment that the kernel already trusts — on-chain storage, a prior input, or a value already on the stack.

Do not consume advice data before this check passes. The advice provider's only role is to supply witness data for commitments the kernel has already received.

2. Key advice map entries by content hash

When inserting into the advice map, the key must be a hash of the value it indexes (or a derived commitment of the same data):

• Use Poseidon2(value) (or whichever commitment matches the consumer's check) as the key.
• Do not hard-code keys like 0x0000_0000_0000_0001, ADVICE_KEY_NOTE_DATA, or per-procedure magic constants.

Readers retrieve the entry by recomputing the same hash from data they already trust; rule 1's commitment check binds the lookup result to that trusted hash.

3. Missing advice is an error

A missing advice-map entry, an empty advice stack, or an absent required value is an error — not a default. Surface it with assert.err=ERR_.... Don't substitute zero / empty / a fallback and continue.

Why

The advice provider is filled by a potentially adversarial prover. Validating every value against a commitment the kernel already trusts, keying map entries by content hash, and erroring on missing entries are what stop untrusted advice from silently corrupting the kernel's invariants.