feat(rpc): add optional paymentIdentifier to RpcSubmitPaymentArgsSchema for V2 parity

[whoabuddy]

Motivation

CanonicalDomainBoundary.transportBoundaries.sharedDomain defines the semantic contract that must hold across both HTTP and RPC transports. The x402 V2 HTTP transport already has caller-controlled idempotency via the payment-identifier extension and a payment_identifier_conflict error reason. The RPC transport had no equivalent — this PR closes that gap.

Closes #28.

What's added

1. PaymentIdentifierSchema (src/core/primitives.ts, exported from @aibtc/tx-schemas/core): shared Zod schema for caller-controlled idempotency keys. Charset [a-zA-Z0-9_-]{16,128}. Distinct from PaymentIdSchema (relay-assigned, requires pay_ prefix) — the identifier is caller-provided, not relay-generated.

2. RpcSubmitPaymentRequestSchema.paymentIdentifier (optional field): lets RPC callers attach an idempotency key to submitPayment. Semantics mirror the HTTP extension: same identifier + same txHex reuses the existing paymentId; same identifier + different txHex is rejected with the new error code.

3. RPC_PAYMENT_IDENTIFIER_CONFLICT added to RpcErrorCodeSchema: RPC-transport parity for the HTTP-side payment_identifier_conflict error reason. Follows existing RPC_* naming convention.

4. CanonicalDomainBoundary.transportBoundaries.sharedDomain updated to include "paymentIdentifier idempotency", making the cross-transport contract explicit in the canonical boundary definition.

DRY improvement: HttpPaymentIdentifierExtensionSchema.info.id now uses the new shared PaymentIdentifierSchema instead of PaymentIdSchema. This corrects a subtle mismatch — extension IDs are caller-provided, so the pay_ prefix requirement was inappropriate.

Backward compatibility

Purely additive — the paymentIdentifier field is optional. Existing callers that don't set it are unaffected. No breaking changes to any existing schema.

Downstream chain

• Relay PR #351 will consume paymentIdentifier in the RPC submitPayment handler via PaymentIdService
• landing-page/#635 and agent-news/#624 adopt after the relay ships

Test plan

• npm run typecheck — passes clean
• npm run build — passes clean
• npm test — 225 tests pass (6 new tests covering paymentIdentifier accept/reject cases and RPC_PAYMENT_IDENTIFIER_CONFLICT)
• Backward compat: submit request without paymentIdentifier parses successfully
• Charset validation: too-short, too-long, and disallowed-char values all rejected

[Copilot]

Pull request overview

Adds a shared caller-controlled idempotency identifier schema and wires it into the RPC submitPayment request to match x402 V2 HTTP behavior, including an RPC-side conflict error code and an explicit note in the canonical cross-transport boundary.

Changes:

• Introduce PaymentIdentifierSchema ([a-zA-Z0-9_-]{16,128}) as a shared primitive for caller-provided idempotency keys.
• Add optional paymentIdentifier to RpcSubmitPaymentRequestSchema and add RPC_PAYMENT_IDENTIFIER_CONFLICT to RpcErrorCodeSchema.
• Update HTTP payment-identifier extension to validate with PaymentIdentifierSchema and document parity in CanonicalDomainBoundary.transportBoundaries.sharedDomain.

Reviewed changes

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

Show a summary per file

File	Description
src/core/primitives.ts	Adds PaymentIdentifierSchema primitive for caller-provided idempotency keys.
src/rpc/schemas.ts	Extends RPC submit request with optional paymentIdentifier; adds new RPC conflict error code.
src/http/schemas.ts	Switches HTTP payment-identifier extension validation to PaymentIdentifierSchema.
src/core/enums.ts	Updates canonical boundary metadata to explicitly include paymentIdentifier parity across transports.
tests/rpc.test.ts	Adds tests for optional paymentIdentifier validation and new RPC error code.

---

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

[Copilot]

Switching HttpPaymentIdentifierExtensionSchema.info.id from PaymentIdSchema to PaymentIdentifierSchema is a stricter validation change for some previously-accepted inputs (e.g., "pay_123" would have parsed before but now fails due to the 16+ length requirement). That makes the PR not purely additive as described; either (a) update the backward-compatibility notes/versioning to reflect the tightened HTTP validation, or (b) consider accepting both schemas here (e.g., union) if you need to preserve old callers while migrating.

[Copilot]

The acceptance test for PaymentIdentifierSchema uses a value with a "pay_" prefix, which can unintentionally suggest that the prefix is required (even though PaymentIdentifierSchema is meant to be distinct from relay-assigned PaymentIdSchema). Consider using a clearly caller-generated identifier without the "pay_" prefix in this test to better capture the intended contract.

Suggested change

	paymentIdentifier: "pay_01JMVP9QE8XA3BDGM5",
	});
	expect(req.paymentIdentifier).toBe("pay_01JMVP9QE8XA3BDGM5");
	paymentIdentifier: "client_01JMVP9QE8XA3BDGM5",
	});
	expect(req.paymentIdentifier).toBe("client_01JMVP9QE8XA3BDGM5");

[Copilot]

RPC_PAYMENT_IDENTIFIER_CONFLICT is the only entry in RPC_ERROR_CODES with an RPC_ prefix; all other RPC error codes in this enum use the unprefixed UPPER_SNAKE style (e.g., INVALID_TRANSACTION, NONCE_CONFLICT). For consistency (and to avoid downstream clients needing special-casing), consider renaming this code to match the existing pattern (or document why the prefix exception is necessary).