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 1, 2026 9:24am

[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