Feat/cep 8 update

[ContextVM-org]

Summary

This PR updates CEP-8 to introduce a new explicit_gating payment lifecycle convention and clarify how it should be used alongside the existing transparent payment flow.

Before this change, CEP-8 was centered on the notification-based payment flow. This PR adds a second, opt-in lifecycle for cases where payment requirements need to be surfaced directly to the client as part of the invocation result, instead of being handled transparently by transport or middleware.

What this PR adds

• introduces explicit_gating as a new CEP-8 payment interaction mode
• keeps transparent as the default and backward-compatible lifecycle
• defines negotiation of payment behavior through the payment_interaction tag
• specifies JSON-RPC payment gating errors for explicit mode:
  • -32042 Payment Required
  • -32043 Payment Pending
• clarifies that in explicit gating mode, the underlying MCP handler is not invoked until payment has been authorized and a matching invocation is retried
• defines authorization and idempotency expectations for explicit-gating payment flows
• clarifies that payment enforcement is a transport concern and MCP handlers may remain unaware of payment processing

Why

The existing CEP-8 text did not clearly separate two different payment interaction models:

• the existing notification-driven flow, where payment handling can remain transport-level and mostly invisible to the application handler
• the new explicit gating flow, where payment is intentionally surfaced to the client as a gate before execution

This PR makes that distinction explicit and documents the intended behavior of the new lifecycle so implementers can support agent-visible payment gates without ambiguity.

Compatibility

This change is additive:

• existing CEP-8 implementations can continue using the transparent notification flow
• explicit_gating is opt-in and only applies when negotiated
• pricing and payment support remain backward compatible while expanding CEP-8 to cover explicit payment-gated invocation semantics

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
contextvm-docs	Ready	Preview, Comment	Jun 6, 2026 10:59am

[1amKhush]

@ContextVM-org Really like where this is headed, the transparent vs explicit_gating split is clean and it's exactly what's needed for agent-driven payment flows.

Just a small point; Step 10 says the server "consumes one authorization atomically" before forwarding to the handler. But what happens if the server successfully consumes the auth, calls the MCP handler, and then the response never makes it back to the client (maybe something like a relay drop)? From the client's perspective, they paid, retried, and got nothing. The authorization is gone. Their only option is to pay again for the same invocation.

[ContextVM-org]

@1amKhush, thanks for your feedback. Yes, it effectively works that way. I think network conditions and other possible quirks are out of scope for this PR. I can’t think of an easy way to handle those cases without introducing some out‑of‑band interaction between the client and server, something like a channel for feedback or other communications. Do you have anything else in mind?

[harsh04044]

@ContextVM-org the transparent vs. explicit_gating split is clean and it's the right shape for agent-driven payments. Two things:

1. How does a client know the server actually accepted explicit_gating? On a stateless first message the client commits to the mode before it's seen any server response, and server support is only a MAY. If the server falls back to transparent, the client ends up waiting for a -32042 while a payment_required notification arrives instead. Could the server echo the effective payment_interaction on its first direct response, and could we spell out what the client should do if it observes the other lifecycle?

2. The "Correlation and Idempotency" section reads as transparent-only. It's framed around retrying the same request event id ("MUST NOT charge more than once for the same request"), but explicit_gating keys authorization on pubkey + hash(method+params) rather than the id. Could we add a sentence on how that section is meant to apply once gating is in play i.e. what "the same request" means for the explicit path?

Nit: after the reorg, "Discovery methods" / "Stateless operation" ended up nested under Payment Interaction Negotiation instead of PMI Discovery, looks like they got stranded when "PMI Discovery" was trimmed.

Otherwise LGTM.

[1amKhush]

@1amKhush, thanks for your feedback. Yes, it effectively works that way. I think network conditions and other possible quirks are out of scope for this PR. I can’t think of an easy way to handle those cases without introducing some out‑of‑band interaction between the client and server, something like a channel for feedback or other communications. Do you have anything else in mind?

@ContextVM-org Yeah fair point, I don't think it needs a full out-of-band channel either. What I had in mind is simpler than that, imo the components are actually already in the spec.

The server already computes a canonical invocation identity (client pubkey + JCS hash of method/params) for authorization matching. After it consumes the authorization and gets the result back from the handler, it could just cache (canonical_id, client_pubkey) → result for a short window; say the same TTL as the original payment option, or some server-defined grace period.

If the client retries with the same canonical identity and the server sees no unused authorization but does have a cached result for that identity, it returns the cached result instead of sending back a fresh -32042. Its a simple approach but i guess it does the work. Lmk your thoughts on this

[ContextVM-org]

@harsh04044 Thanks, both points make sense. I updated CEP-8 to make the effective payment lifecycle explicit during the first direct message exchange.

For explicit_gating, the client still requests the mode with a single payment_interaction=explicit_gating tag on the first direct client-to-server message. The server now has to make the effective mode observable on its first direct response when the client requested a non-default mode. If the server accepts explicit gating, it echoes payment_interaction=explicit_gating; if it does not support or does not accept it, it must not silently fall back. It should either return an unsupported/unavailable negotiation error, or explicitly disclose payment_interaction=transparent and use the transparent lifecycle.

I also clarified the client side: a client that requested or requires explicit gating should treat an effective transparent response, lack of effective-mode disclosure, or receipt of transparent notifications/payment_required messages as failure to negotiate explicit gating, and then abort or fall back according to local policy.

On the “same request” / idempotency point, I rewrote the section as Correlation, Authorization Identity, and Idempotency. It now separates the two lifecycles:

• transparent mode correlates payment notifications by the outer Nostr request event id via the e tag, and “same request” means the same outer event id;
• explicit gating correlates authorization and retries by the explicit-gating authorization identity: client pubkey plus the JCS/SHA-256 hash of the inner MCP method and params. JSON-RPC id, outer event id, timestamps, signatures, and tags are explicitly excluded, so a retry can use a different JSON-RPC id/event id and still match if method/params and client pubkey are unchanged.

I also fixed the section nesting nit: Discovery methods and Stateless operation are now under PMI Discovery instead of being stranded under payment interaction negotiation. Lmk what are your thoughts on this

[ContextVM-org]

@1amKhush Thanks, that replay-cache approach is a useful implementation strategy, but I intentionally did not add it to CEP-8 as standardized behavior, even as a MAY.

Once the spec mentions result replay caches, clients may start expecting that behavior, and doing it correctly would likely require additional protocol surface: discovery/negotiation, TTL semantics, cache keys, streaming behavior, large or sensitive results, side-effect semantics, and replay eligibility.

The updated text instead keeps CEP-8’s boundary narrower: explicit gating authorizes execution, not guaranteed result replay. The server must atomically claim or consume a matching paid authorization before forwarding the invocation to the underlying MCP handler, so the same authorization cannot cause concurrent double execution. If the invocation is executed and the response is lost due to transport loss, relay behavior, client disconnect, or similar delivery failure, CEP-8 does not require the server to replay the completed result. A later matching invocation with no unused authorization may be treated as unpaid and may receive a fresh Payment Required, unless server-specific policy provides another remedy.

That keeps the payment lifecycle interoperable without imposing result retention requirements or partially specifying a replay mechanism.

[harsh04044]

@ContextVM-org this all looks great. the effective-mode disclosure (plus must-not-silently-fall-back and the -32602 path) closes the negotiation gap cleanly and splitting correlation by lifecycle makes "the same request" unambiguous. nice touch documenting the executed-but-undelivered case explicitly as policy-deferred - that also settles the earlier relay-drop thread. nit's fixed too. LGTM!

[1amKhush]

@ContextVM-org That's a fair call. You're right that even a MAY would set an expectation. rest the latest changes make the CEP behavior unambiguous, LGTM 👍