design: funding model for attestation storage

[pbeza]

Background

submit_participant_info takes no deposit and the contract funds attestation storage from its own balance — true of every deployed version, not just since #3940. Any account can create unlimited entries at roughly 1/7th of what each costs the contract, and once the balance no longer covers the contract's own storage it cannot write state at all, which halts signing. Measurements are in the drain analysis below.

This issue covers agreeing the funding model. Implementation is tracked separately in #4015.

The design has to work around two protocol constraints: a function-call access key cannot attach a deposit (not even inside a meta-transaction), and report_data binds the quote to env::signer_account_pk(), so an operator cannot submit on a node's behalf. Payment and submission therefore have to be separate transactions.

Acceptance Criteria

• A funding model is agreed that keeps the node self-submitting with its function-call key and moves the storage cost to whoever onboards it.
• The decision record names what was chosen, what was rejected, and why — including the alternatives that cannot work (full-access node keys, meta-transactions, operator-submits-on-behalf) and those that were judged not worth it (per-account entry caps, refundable bonds, an owner-callable release method, gating Attestation::Mock).
• The bound is stated: what the contract can still be made to fund, and what is accepted as residual.
• The operator-facing impact is described, including how many steps change.
• Design doc merged under docs/design/, reviewed by the team.

Outcome

Settled on a grant counter: one prepayment buys one grant, a grant permits one stored attestation entry, and a grant returns when its entry is reclaimed. The contract stores counts rather than amounts, nothing is refunded, and multi-node or migrating operators simply prepay again — so there is no cap constant, no participant-status check, and no assumption about how many nodes share an account.

Doc: docs/design/operator-prepaid-attestation-storage.md (#4011).

Resources & Additional Notes

• Implementation: feat(contract): operator-prepaid attestation storage (grant counter) #4015.
• Follows fix(contract): drop the deposit for submit_participant_info #3940, which made contract-funded storage intentional rather than accidental.
• Related: refactor(contract): drop fail_attestation_submission now that the deposit is gone #3991 (fail_attestation_submission becomes removable — the chosen model needs no charge to survive a failing callback, so it is not blocked on this), fix(contract): make mock attestations cleanable via expiry #3785 (mock attestation expiry, merged, which makes abandoned entries sweepable).
• Slack: https://nearone.slack.com/archives/C0912BTG51T/p1785402605441239?thread_ts=1784896517.987259&cid=C0912BTG51T

[barakeinav1]

Added two notes to the description from the #3940 review, both of which affect how this gets built:

1. The drain this fixes needs no TEE. Mock::Valid always verifies, submit_participant_info has no participant gate, entries are keyed by TLS key with no per-account limit, and mock entries are never reclaimed by clean_invalid_attestations (they never expire). So one ordinary account can mint unbounded contract-funded entries for gas only — the "single TEE" framing from Slack understates it. A flat deposit does fix this, but gating Attestation::Mock behind a feature flag would kill the cheap variant independently.

2. Size the deposit off the mock branch. The largest stored entry is Mock::WithConstraints{all Some} at 450 borsh bytes, not Dstack at 445 — 604 bytes / ~0.006 NEAR once IterableMap overhead is counted. Deriving the flat deposit from the Dstack worst case would leave it 5 bytes short.

Also worth flagging against the fourth AC: MAX_ATTESTATION_ENTRY_STORAGE_COST as it stands measures the storage delta (new − old) on updates rather than absolute entry size, so it can't be used to size a deposit as-is. That's under discussion on #3940.

[barakeinav1]

One more item for this issue, deferred from #3940.

The worst-case entry size is now pinned in submit_participant_info__should_store_exactly_the_pinned_entry_size (599 bytes Dstack / 604 bytes Mock, WORST_CASE_ENTRY_BYTES = 604), and that test carries a TODO(#3972) noting the flat deposit should be derived from it.

Before deriving the deposit, confirm those numbers against a real runtime. They are measured through near-sdk's mocked VM (testing_env! + env::storage_usage()), not nearcore. I believe the accounting is identical — same 40-byte per-record overhead, same key+value rules — but I haven't verified it. A sandbox assertion on worker.view_account(contract.id()).await?.storage_usage around a submit_participant_info call would settle it; the removed submit_participant_info__should_reject_new_attestation_below_flat_fee test already had that pattern.

Tolerable while it only backs a <= ceiling with headroom. Not tolerable once a deposit is sized off it, since an undercount means the deposit doesn't cover the entry and the contract silently eats the difference.

[barakeinav1]

The pay-on-behalf acceptance criterion is not implementable as written.

• A different account (the operator) can pay the first submission on the node's behalf.

A Dstack submission is bound to its submitter, so an operator cannot make it at all — the call fails verification before any deposit logic runs:

1. submit_participant_info sets account_public_key from env::signer_account_pk() (crates/contract/src/lib.rs:792) and puts it in the NodeId.
2. expected_report_data(node_id) builds ReportDataV1::new(tls_public_key, account_public_key) (crates/contract/src/tee/tee_state.rs).
3. verify_with_report enforces it: self.verify_report_data(&expected_report_data, report_data)? (crates/attestation/src/attestation.rs:146).

The enclave baked hash(tls_pk, node's account pk) into the quote. An operator signing with their own key yields a different expected_report_data, and the comparison fails. assert_caller_is_signer() closes the proxy-contract route too, since predecessor must equal signer.

This isn't theoretical — it already bit the e2e setup on #3940. From b1ab8eb6:

fund each new participant's first attestation before resharing, signed with the node's near_signer_key so the stored account_public_key matches the key the node later uses for key-event votes (an operator key would store the wrong key and stall resharing).

So there's a second-order failure even where verification doesn't gate it (the Mock path, which skips report-data): the stored account_public_key would be the operator's, and lookup_node_id_by_signer_pk then fails to resolve the node for key-event votes.

Suggested direction

Split paying from submitting rather than trying to let one account do both:

• Operator calls a payable storage_deposit(node_account_id)-style method (NEP-145 shape), crediting a per-node storage balance.
• The node later self-submits with its function-call key as it does today; store_verified_attestation draws from that node's credited balance instead of env::attached_deposit().
• Re-submissions that grow nothing draw nothing, so the deposit-less fc key keeps working.

That keeps the report-data binding intact — which is load-bearing, it's what proves the enclave produced the quote for this submitter — and still gets the storage off the contract's balance, which is the actual goal here.

Worth @kevindeforth's input when he's back, since this contradicts the original proposal rather than just refining it.

[barakeinav1]

Sequencing note: #3991 (drop fail_attestation_submission) should land after this issue is decided, not before.

That method exists so a failing resolve_verification can still commit the refund and any partial store — a panic in the same receipt would roll them back. #3940 removed the deposit, so today nothing needs to survive the error branch and the indirection is dead weight.

But this issue puts payment back. If the charge ends up inside the callback, the same "must commit while failing" constraint returns and fail_attestation_submission would have to be rebuilt. So whichever shape this lands in should settle first.

Worth checking against the direction suggested above — an operator-funded prepay drawn down by the node's own later submission. If the charge happens against a pre-credited balance rather than an attached deposit, there may be nothing to refund on failure, and #3991 stays safe to do.

[netrome]

Setting P1 as the absence of a deposit is a potential (but costly) griefing attack.

[barakeinav1]

attack cost estimations:

Metric	Value
Storage per Mock::Valid entry	267 bytes
Contract balance locked per entry	0.00267 NEAR
Gas per submit	3.70 TGas
Attacker cost per entry (mainnet price 1e8 yocto/gas, verified live)	0.00037 NEAR
Amplification	≈ 7.2×

Against live v1.signer (2,257.60 NEAR, 15.22 already staked, ~2,242 free): ~840,000 entries exhausts the free balance, adding ~224 MB of state for ~311 NEAR of attacker gas

[barakeinav1]

Alternatives assessed

• Gate Attestation::Mock off in production — rejected, mock attestations are still needed.
• Cap entries per account — not worth it. Implicit accounts cost 0.00182 NEAR (recoverable via DeleteAccount) and 0.446 TGas to create, so with a cap of one the attacker pays ~0.00046 NEAR per entry against 0.00267 — amplification only drops 7.2× → ~5.8×. It triples transactions per entry, which is friction and more visible, but it is not a fix, and prepay makes it redundant.
• Restrict submission to current-or-proposed participants — not possible today, but considering as its own issue. vote_new_parameters calls reverify_and_cleanup_participants(proposal.participants(), …) and rejects a proposal naming any participant without a valid attestation, so the order is forced: attest, then propose. That is exactly why submit_participant_info must be permissionless. Reordering to propose → submit → remaining votes would enable it, but note the only production callers of that function are vote_new_parameters (proposed set) and verify_tee (current set); nothing validates the proposed set at the Running→Resharing transition, so the gate would have to be added there rather than simply relaxed at vote time. Worth pursuing separately: a governance gate removes the attack surface rather than pricing it, which is strictly stronger than any deposit.

Related in flight

• fix(contract): make mock attestations cleanable via expiry #3785 (mock attestation expiry, incl. migration of existing on-chain entries) is complementary and lands the same mitigation from the other side: it turns a one-shot drain into a sustained cost. Caveat on reclamation rate — clean_invalid_attestations is permissionless while Running, but the automatic post-reshare sweep uses RESHARE_CLEAN_INVALID_ATTESTATIONS_MAX_SCAN = 100, so clearing a large backlog needs deliberate looping with a bigger max_scan.