Reward authority rotation primitive (RewardPool)

[rickyrombo]

Goal

Add a CometBFT-side abstraction — RewardPool — so the set of eth addresses authorized to attest for programmatic rewards under a given Solana reward manager (RM) can be updated without reissuing the reward rows. Today every core_rewards row carries an immutable inline claim_authorities array, set at create time. Rotating an authority means deleting and recreating every row that references it.

A leaked launchpad-derived per-mint claim authority key currently retains permanent attestation rights on every reward under that mint until those rows are individually deleted and re-created. Programmatic-reward attestations have been disabled behind a kill switch (#215) since this gap was identified. This PR is the unblock.

What ships (logical chunks)

This PR bundles three sequenced changes that previously lived as separate stacked PRs (#222 / #225 / #228). They were merged onto one branch off main because reviewing them in isolation kept producing the same circular questions about cross-PR invariants. The commit history preserves the chunk boundaries.

1. Schema + migration (pkg/core/db/sql/migrations/00034_reward_pools.sql)

• New table core_reward_pools (rewards_manager_pubkey TEXT PRIMARY KEY, authorities TEXT[], …). Pool identity is the Solana RM pubkey — there is no separate pool_id.
• New column core_rewards.rewards_manager_pubkey (FK → core_reward_pools). The old claim_authorities column on core_rewards is dropped; reads now do LEFT JOIN core_reward_pools p and alias coalesce(p.authorities, '{}') as claim_authorities. Existing read queries don't notice.
• Seed table launchpad_authority_rm mapping each known per-mint claim authority (lowercased eth) → its Solana RM. Values are produced by running DeriveEthAddressForMint(domain="claimAuthority", secret, mint) for every launchpad mint init event. Used by the migration backfill and (transitively) by the wire-compat replay path.
• Backfill: per RM, take the UNION of authorities across every reward whose claim_authorities contains any per-mint key for that RM. Rows whose authorities don't match any seed entry stay with rewards_manager_pubkey = NULL and are unrecoverable — see "Gaps."

2. CometBFT transactions (pkg/core/server/reward_pools.go, pkg/core/server/rewards_legacy.go, proto)

• Body+signature envelope: Tx { TxBody body; signatures[] } — signature lifted off individual actions onto a wrapping envelope (cosmos-style). This is wire-incompatible with the pre-pool shape, which had deadline + signature embedded inside each action.
• Two new pool-management actions: CreateRewardPool and SetRewardPoolAuthorities. Both gated by:
  • validateRewardsManagerPubkey (must be valid base58, exactly 32 bytes, not whitespace, not the AUDIO RM).
  • validateAuthorityList (non-empty, every entry valid eth address).
  • For Create: signer ∈ initial authorities. For Set: signer ∈ current pool authorities.
• CreateReward proto: claim_authorities, deadline_block_height, signature removed (tags 4-6 reserved); rewards_manager_pubkey at tag 7. New CreateReward requires an existing pool. validateCreateReward checks signer ∈ pool.authorities.
• Wire-compat: legacy-shape bytes are rejected at validate (CheckTx + ProcessProposal) so no new legacy txs can be accepted, but applied at finalize so block-sync replay reproduces historical state. tryParseLegacyReward recovers the original tag 1000/1001 bytes via proto-go's preserved unknown fields.

3. Validator endpoint cutover (pkg/core/server/connect.go)

• GetRewardAttestation: restored from Temporarily block artist-coin attestations at the node #215. Auth check uses dbReward.ClaimAuthorities, which is sourced from coalesce(p.authorities, '{}') — i.e., the current pool membership. Rotating an authority out via SetRewardPoolAuthorities immediately revokes their ability to authenticate claims.
• GetRewardSenderAttestation / GetDeleteRewardSenderAttestation: per-RM gate. If a pool exists for the requested RM, sign iff addr ∈ pool.authorities (Add) or addr ∉ pool.authorities (Delete — the rotation-out signal). If no pool exists, fall through to the validator/AAO trust set only for the configured AUDIO RM; every other no-pool RM returns InvalidArgument.

Tradeoffs and key decisions

RewardClaim.Compile does not bind to RewardAddress

The proto field exists, and Compile has a 3-piece RewardAddress:RewardID:Specifier disbursement_id branch — but the bytes Compile produces are exactly what the Solana reward manager program reconstructs in evaluate_attestations, and that program expects the 2-piece RewardID:Specifier form. Populating RewardAddress here would break on-chain signature verification.

Consequence: cross-reward replay protection relies on Specifier being disbursement-unique (per recipient + per event), which is the existing client contract. A signature for (RewardID, Specifier, recipient, amount, authority) is valid for any reward sharing all five with a pool containing authority. In practice Specifier collisions across rewards don't occur; documented inline at the RewardClaim construction site so a future reader doesn't "fix" it.

AUDIO stays on the validator/AAO trust set

AUDIO is intentionally outside the pool primitive. validateRewardsManagerPubkey actively refuses to create a pool whose RM matches the configured AUDIO RM. Without this denylist an attacker could create a pool for the AUDIO RM with their own initial authorities and have validators sign AUDIO sender attestations on their behalf.

The AUDIO RM constants live in pkg/core/config/rewards.go per env. Stage is intentionally empty (staging doesn't run a real AUDIO mint, so the denylist would never legitimately fire). Dev and Prod are populated.

Privilege escalation in legacy finalizeCreateReward

Reverted in development: an early version of the legacy create path upserted authorities into the resolved real-RM pool. Because legacy validateCreateReward only checked the tx signature (not signer ∈ pool.authorities), an attacker could submit a legacy CreateReward with [legitimate_per_mint_key, attacker_key] and inject attacker_key into the legitimate pool. The current code uses lookup-only: resolve the RM, bind the reward to the existing pool if one exists, leave NULL otherwise. Pool authorities mutate only via CreateRewardPool / SetRewardPoolAuthorities.

Migration UNION ↔ replay UNION (apphash determinism)

Earlier review found a divergence: migration step 1 produced pool.authorities = UNION(every legacy reward's authorities), but the replay-time upsert was a hard overwrite, producing pool.authorities = last-replayed-reward.authorities. An in-place-upgraded node and a from-genesis-syncing node would end up with different DB state → different validation outcomes → apphash divergence.

Fixed: UpsertLegacyReplayRewardPool (renamed from the misleading UpsertSyntheticRewardPool) now uses true union semantics in DO UPDATE. Today's data has at most one authority per reward, so the bug doesn't manifest currently — this is insurance against multi-authority drift.

Body+signature envelope is wire-incompatible with the pre-pool shape

This isn't a soft cutover. The pre-pool wire shape has no field at tag 1 (where the new Body lives), so the new proto unmarshals legacy bytes with Body == nil. The wire-compat layer (rewards_legacy.go) is the bridge for replay; live legacy traffic is rejected. Clients (SDK, API repo) must be updated in lockstep — the SDK update is in this PR; the API repo is NOT (deferred per stack plan).

Down migration is best-effort

core_rewards.claim_authorities is restored from the pool's authorities on a Down. Rows with rewards_manager_pubkey = NULL (no launchpad match) lose their authorities permanently — there's no pool to restore from. Documented in the migration; production rollback would happen at the chain level, not via SQL Down.

Gaps / things to know

• launchpad_authority_rm lifetime. This table is queried at replay time by finalizeLegacyCreateReward. It must remain populated as long as legacy bytes can be replayed. PR Remove legacy reward wire-compat layer (post-restart cleanup) #232 (separate, post-restart cleanup) drops the table after the wire-compat layer is removed. Do not drop sooner.
• Specifier uniqueness is the only cross-reward replay defense. See "RewardClaim.Compile" above.
• AUDIO denylist is env-dependent. AudioRewardsManagerPubkey() reads GetRuntimeEnvironment(). A node misconfigured to run with env=dev against prod data would skip the prod AUDIO denylist. Not currently asserted at startup.
• State-sync table dump still includes launchpad_authority_rm. Required while wire-compat is in place; PR Remove legacy reward wire-compat layer (post-restart cleanup) #232 removes it together with the table drop.
• "Empty" non-AUDIO RM handling. senderGateForRM returns ErrSenderGateUnknownRM (mapped to InvalidArgument) for any RM with no pool that isn't the AUDIO RM. Earlier behavior would silently fall through to validator/AAO, which is more permissive than desired now that pools exist.
• API repo is NOT part of this PR. Downstream apps/api create-reward call sites need to issue CreateRewardPool before CreateReward for new mints. Until they do, new launchpad mints will fail at validateCreateReward's pool existence check. Deferred intentionally; will land separately.

Deployment

• This bundle plus PR Remove legacy reward wire-compat layer (post-restart cleanup) #232 (cleanup) plus a network restart with fresh genesis. The restart is what makes PR Remove legacy reward wire-compat layer (post-restart cleanup) #232 safe to ship: post-restart there is no chain history to replay, so the wire-compat layer becomes dead code.
• Without a restart: the bundle is still safe (replay UNION matches migration UNION post-fix); PR Remove legacy reward wire-compat layer (post-restart cleanup) #232 must NOT ship, as the wire-compat layer is still load-bearing for replay from genesis.

Test plan

• go test ./pkg/core/server/ ./pkg/rewards/ ./pkg/common/ — unit tests for pool tx validation, AUDIO denylist, sender gate, legacy decode/replay, attestation flow.
• Integration tests in pkg/integration_tests/13_reward_pools_test.go (new) and 12_rewards_test.go (updated) — round-trip pool creation, authority rotation, and attestation gating against a live devnet.
• Apply migration against a snapshot of staging (or a fixture with rewards under multiple RMs) and confirm: one pool per RM, pool authorities = UNION of contributing rewards' authorities, every row has a non-NULL FK or is in the documented "no launchpad match" bucket.
• Verify validateCreateRewardPool refuses the configured Prod/Dev AUDIO RM.
• Verify GetRewardSenderAttestation returns InvalidArgument for an arbitrary RM with no pool that isn't AUDIO.
• Manual: rotate an authority via SetRewardPoolAuthorities, re-attempt GetRewardAttestation with the rotated-out key — expect PermissionDenied. Re-attempt with the rotated-in key — expect success.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a CometBFT-side RewardPool primitive keyed by Solana rewards_manager_pubkey so programmatic reward claim authorities can be rotated without rewriting reward rows, while keeping historical chain replay deterministic via a legacy wire-compat layer.

Changes:

• Introduces core_reward_pools + migration/backfill, moves rewards’ authorities to pool membership, and adds state-sync coverage for new tables.
• Adds a new body+signature transaction envelope, reward-pool management transactions (CreateRewardPool, SetRewardPoolAuthorities), and legacy reward replay decoding/signature recovery.
• Restores and updates validator Connect endpoints to gate attestations/sender attestations by pool membership (with AUDIO remaining on the validator/AAO trust model), plus SDK + integration test updates.

Reviewed changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
proto/core/v1/types.proto	Adds RewardBody/RewardMessage envelope, RewardPool* messages, legacy reward wire types, and reward-pool RPC types.
proto/core/v1/service.proto	Adds GetRewardPool RPC.
pkg/api/core/v1/types.pb.go	Regenerated protobuf Go types for new reward/pool envelopes and RPC types.
pkg/api/core/v1/service.pb.go	Regenerated CoreService protobuf bindings to include GetRewardPool.
pkg/api/core/v1/v1connect/service.connect.go	Regenerated Connect client/server bindings to include GetRewardPool.
pkg/core/db/sql/migrations/00033_reward_pools.sql	Creates core_reward_pools + launchpad_authority_rm, backfills pools/RM FKs, drops inline claim_authorities.
pkg/core/db/sql/reads.sql	Updates reward reads to join pools and adds reward-pool + launchpad RM lookup queries.
pkg/core/db/sql/writes.sql	Updates reward writes to store rewards_manager_pubkey and adds pool insert/update + legacy replay upsert.
pkg/core/db/reads.sql.go	Regenerated sqlc read layer for new JOIN-based reward reads and pool queries.
pkg/core/db/writes.sql.go	Regenerated sqlc write layer for RM-based rewards and pool mutations.
pkg/core/db/models.go	Adds CoreRewardPool / LaunchpadAuthorityRm models and updates reward model fields.
pkg/core/server/state_sync.go	Includes core_reward_pools and launchpad_authority_rm in PG dump state sync.
pkg/core/server/abci.go	Wires reward-pool tx validation/finalization into ABCI flow.
pkg/core/server/rewards.go	Switches reward tx validation/finalization to body+signature envelope; adds deadline signer recovery and legacy dispatch.
pkg/core/server/rewards_legacy.go	Implements legacy reward decode + signer recovery + replay-time RM/pool binding.
pkg/core/server/rewards_legacy_test.go	Tests unknown-field legacy decode + validate-time legacy rejection.
pkg/core/server/reward_pools.go	Adds reward-pool tx validation/finalization, authority validation, and RM pubkey validation/denylist.
pkg/core/server/reward_pools_test.go	Unit tests for RM pubkey shape checks and AUDIO denylist behavior.
pkg/core/server/connect.go	Restores reward attestation, normalizes GetRewards authority lookup, adds GetRewardPool, and implements per-RM sender attestation gating.
pkg/core/config/rewards.go	Adds per-env AUDIO RM pubkeys and accessor used for denylisting pool creation.
pkg/common/proto.go	Implements deterministic-proto signing/recovery helpers for envelope bodies.
pkg/common/proto_test.go	Adds tests for ProtoSign/ProtoRecover correctness and oneof discrimination.
pkg/common/legacy_reward_signing.go	Reintroduces legacy reward signing helpers for historical replay signer recovery.
pkg/common/reward_signing.go	Removes pre-envelope reward signing helpers.
pkg/rewards/reward_pool.go	Adds canonicalization helper for pool authority sets.
pkg/rewards/reward_pool_test.go	Tests canonical authority normalization behavior.
pkg/sdk/rewards/rewards.go	Updates SDK to sign/send envelope bodies and adds pool + sender-attestation helpers.
pkg/integration_tests/12_rewards_test.go	Updates integration tests to create pools and restores attestation assertions.
pkg/integration_tests/13_reward_pools_test.go	Adds integration test coverage for pool lifecycle, rotation, and sender attestation gating.
examples/rewards/main.go	Updates example to create a pool first and then create a reward using rewards_manager_pubkey.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 30 changed files in this pull request and generated 7 comments.

Files not reviewed (5)

• pkg/api/core/v1/service.pb.go: Language not supported
• pkg/api/core/v1/v1connect/service.connect.go: Language not supported
• pkg/core/db/models.go: Language not supported
• pkg/core/db/reads.sql.go: Language not supported
• pkg/core/db/writes.sql.go: Language not supported

[raymondjacobson]

Consider a case where two create reward pool TXs exist in the same block and the second fails to finalize. Do we need an ON CONFLICT DO NOTHING ?

[Copilot]

Pull request overview

Copilot reviewed 24 out of 30 changed files in this pull request and generated 2 comments.

Files not reviewed (5)

• pkg/api/core/v1/service.pb.go: Language not supported
• pkg/api/core/v1/v1connect/service.connect.go: Language not supported
• pkg/core/db/models.go: Language not supported
• pkg/core/db/reads.sql.go: Language not supported
• pkg/core/db/writes.sql.go: Language not supported