fix(mpp): harden subscription activation

[EfeDurmaz16]

Summary

• hardens MPP subscription activation construction and verification across TypeScript and Rust
• validates the complete canonical instruction sequence, account identities, privileges, ATAs, program IDs, event authority, and compute budget
• reserves activation signatures atomically before broadcast and releases the claim only on a definitive retryable failure
• aligns the public Rust client default compute limit with the server's sponsored transaction safety cap
• makes Rust and TypeScript subscription code generation reproducible and fail-fast, including awaited generation and byte-for-byte drift checks

Security invariants

• a valid signature cannot authorize extra instructions, substituted accounts, privilege escalation, or an alternate token/subscription program
• concurrent identical activations admit exactly one broadcast
• ambiguous or successful settlement cannot be replayed through a second verifier instance sharing the store
• generated clients and public pay-kit adapters preserve the hardened activation API
• subscription users receive an explicit atomic replay-store contract; the process-local helper is named and documented as unsafe, while production examples require a shared or durable store
• shipped examples bind the full on-chain plan snapshot instead of accepting a bare plan address

Verification

• Rust 35 focused subscription tests and the full 376-test kit suite; rustfmt clean
• TypeScript 30 focused subscription tests and the full 482-test suite; PayKit typecheck, ESLint, and Prettier clean
• shipped playground TypeScript compilation against the rebuilt public package
• generated Rust and TypeScript subscription clients regenerate byte-for-byte with a fail-fast synchronization check
• multiple adversarial review/fix rounds, including compute-budget parity

Repository-wide TypeScript typecheck still reports the existing TS2742 declaration-portability errors in the MPP client/server factories; this branch does not introduce a new error class. Repository-wide Rust Clippy likewise reaches only pre-existing err().expect() warnings in unchanged protocol tests.

Base is #219. This is a protocol PR because the activation transaction contract and replay invariant are shared by the TypeScript and Rust SDKs.

[EfeDurmaz16]

@greptile-apps please review the current head.

[greptile-apps]

Greptile Summary

This PR hardens MPP subscription activation across TypeScript and Rust by validating the complete canonical instruction sequence, plan-snapshot field binding, account identities and privileges, ATAs, and compute-budget limits before co-signing. It also reserves activation signatures atomically in the replay store before broadcast and releases the claim only on definitively-retryable failures, eliminating replay and double-settlement races.

• Instruction-level validation: the server now decodes and byte-checks every instruction in the activation transaction (subscribe + transferSubscription + idempotent ATAs + compute budget) against re-derived PDAs, plan-snapshot fields, and privilege bits before co-signing.
• Atomic replay guard: consumedKey is derived from the co-signed transaction's fee-payer signature and claimed via store.reserve before the transaction reaches the RPC; the guard is released on transient errors so legitimate retries proceed while confirmed activations stay permanently blocked.
• Codama-generated decoders replace hand-rolled byte layouts; the Rust default compute limit is aligned to the server's 200k sponsored-transaction cap.

Confidence Score: 5/5

Safe to merge; all identified findings are non-blocking style or minor behavioral nuances rather than defects in the hardened activation path.

The activation hardening logic is coherent and well-tested across 482 TypeScript and 376 Rust tests. All three findings are minor: an unnecessary blockhash RPC fetch when authority already existed, the feePayer consistency check being deferred from configure() to gate construction, and subscription challenges now carrying an expiry that they previously did not.

The Rust server subscription.rs (+3,800 lines) warrants close secondary review given its volume. The decodeSubscriptionDelegation mapping (header.delegatee to planPda) relies on the Codama IDL being in sync with the deployed on-chain program.

Important Files Changed

Filename	Overview
typescript/packages/mpp/src/server/Subscription.ts	Major hardening: strict canonical instruction validation, atomic consumed-key reservation before broadcast, plan-snapshot binding checks, and Codama-generated decoders replacing hand-rolled layout readers.
typescript/packages/mpp/src/client/Subscription.ts	Subscription client now requires explicit subscriptionAuthorityInitId, drops broadcast=true support, aligns compute limit to 200k, and uses Codama-generated instructions. The refreshBlockhash=true flag is set even when authority already existed, causing an extra RPC round-trip.
rust/crates/kit/src/mpp/client/subscription.rs	Aligns default compute limit to 200k, adds Token-2022 transfer-hook guard, adds recipient ATA creation, and splits the authority init path to return whether initialization was performed.
rust/crates/kit/src/mpp/server/subscription.rs	Extremely large Rust server hardening mirroring the TypeScript server; warrants careful secondary review given the volume of new code.
typescript/packages/pay-kit/src/adapters/mpp.ts	Subscription gates now thread the operator signer unconditionally, compute a per-request HMAC resource binding, call optionsFor (adding challenge expiry), and enforce a durable+shared store requirement outside localnet.
typescript/packages/pay-kit/src/config.ts	Validation helpers extracted, config freezing separated into freezePayKitConfig, and the feePayer=true/signer.isFeePayer consistency check removed from configure() and deferred to subscription gate creation.
typescript/packages/pay-kit/src/replay-store.ts	atomicReplayStoreView return type widened to include reserve() so the view satisfies both the charge-path and subscription-server store contracts.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client
    participant Server
    participant Store
    participant RPC

    Note over Client,RPC: Subscription activation (fee-sponsored path)
    Client->>Server: GET /subscription-endpoint (challenge request)
    Server->>Client: 402 challenge (HMAC-bound, includes planSnapshot + recentBlockhash)
    Client->>Client: initializeSubscriptionAuthority (if needed)
    Client->>Client: buildSubscriptionActivationTransaction
    Client->>Client: partial-sign as subscriber
    Client->>Server: "credential { transaction: base64 }"
    Server->>Server: assertSubscriptionCredentialBinding
    Server->>Server: validateActivationInstructions
    Server->>Server: coSignBase64Transaction
    Server->>Server: signatureFromWireTransaction to consumedKey
    Server->>Store: claimConsumed(consumedKey) [atomic putIfAbsent]
    alt key already claimed
        Store-->>Server: false
        Server-->>Client: 400 already consumed
    else key free
        Store-->>Server: true
        Server->>RPC: fetchSubscriptionDelegation
        alt delegation already on-chain
            Server->>RPC: isSignatureConfirmed
            RPC-->>Server: confirmed
        else delegation absent
            Server->>RPC: simulateTransaction
            Server->>RPC: sendTransaction
            Server->>RPC: waitForConfirmation
        end
        Server->>RPC: fetchSubscriptionDelegation (verify terms)
        Server-->>Client: Receipt
    end
    Note over Server,Store: On post-settlement error: releaseConsumedBestEffort

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Client
    participant Server
    participant Store
    participant RPC

    Note over Client,RPC: Subscription activation (fee-sponsored path)
    Client->>Server: GET /subscription-endpoint (challenge request)
    Server->>Client: 402 challenge (HMAC-bound, includes planSnapshot + recentBlockhash)
    Client->>Client: initializeSubscriptionAuthority (if needed)
    Client->>Client: buildSubscriptionActivationTransaction
    Client->>Client: partial-sign as subscriber
    Client->>Server: "credential { transaction: base64 }"
    Server->>Server: assertSubscriptionCredentialBinding
    Server->>Server: validateActivationInstructions
    Server->>Server: coSignBase64Transaction
    Server->>Server: signatureFromWireTransaction to consumedKey
    Server->>Store: claimConsumed(consumedKey) [atomic putIfAbsent]
    alt key already claimed
        Store-->>Server: false
        Server-->>Client: 400 already consumed
    else key free
        Store-->>Server: true
        Server->>RPC: fetchSubscriptionDelegation
        alt delegation already on-chain
            Server->>RPC: isSignatureConfirmed
            RPC-->>Server: confirmed
        else delegation absent
            Server->>RPC: simulateTransaction
            Server->>RPC: sendTransaction
            Server->>RPC: waitForConfirmation
        end
        Server->>RPC: fetchSubscriptionDelegation (verify terms)
        Server-->>Client: Receipt
    end
    Note over Server,Store: On post-settlement error: releaseConsumedBestEffort

Loading

_{Reviews (14): Last reviewed commit: "Merge remote-tracking branch 'origin/fix..." | Re-trigger Greptile}

[EfeDurmaz16]

@greptile-apps please re-review the current head after the Rust blockhash parity fix.

[EfeDurmaz16]

@greptile-apps please re-review exact head 2bcee2d. This refreshes activation blockhashes after authority initialization, binds fee-payer identities, preserves fail-closed replay claims, and unifies the TypeScript reserve contract.

[EfeDurmaz16]

@greptile-apps please review

[EfeDurmaz16]

@greptile-apps please review

[EfeDurmaz16]

@greptileai review

[EfeDurmaz16]

@greptileai review

[EfeDurmaz16]

@greptileai review

[lgalabru]

Don't we already have a function doing this in pay-kit?

[EfeDurmaz16]

Right — replaced in ee9dd33: the fixture's hand-rolled network-slug switch is gone; it now passes the env value through pay-kit's exported toNetwork (the same normalization configure runs), so the harness pulls from the lib instead of re-implementing it. Fail-closed on an unknown network is preserved by configure's validateNetwork.

[lgalabru]

We should have a constant for this

[EfeDurmaz16]

Done in e648022: it now reuses programs::ASSOCIATED_TOKEN_PROGRAM (the canonical id in mpp/protocol/solana.rs, already used for the token programs in this file) — the same literal at line 150 got the same treatment.

[lgalabru]

this lib should have access to a block cache.

[EfeDurmaz16]

Agreed — wired in 89dd1fe. The kit already had core::blockhash::BlockhashCache (45s TTL, used by the server challenge builders); the subscription client now routes its fetches through a process-wide per-endpoint instance (shared_blockhash_cache), so activation bursts collapse into one getLatestBlockhash within the TTL. Fail-closed: a failed fetch propagates and nothing past the TTL is ever served. The one deliberately direct fetch left is post-SA-init, which must NOT reuse the just-broadcast tx's blockhash.