@horizen/x402-private-vela-fixed

@horizen/x402-private-vela-fixed

x402 payment scheme implementation for Vela private transfers. Implements the private-vela-fixed scheme for all three x402 roles: facilitator, client (buyer), and resource server (seller).

What it provides

• Facilitator: verify and settle payments via submitRequestFor() on ProcessorEndpoint. /settle blocks until the TEE emits the matching AppEvent — a successful response is cryptographic proof that the transfer landed as specified.
• Client: build, sign, and encrypt transfer payloads (EIP-712 + EIP-2612 + P-521 ECIES)
• Resource server: configure PaymentRequirements with vela-nova invoiceId tracking
• computeTransferReceiptHash: helper that recomputes vela-nova's AppEvent.eventSubType hash, for off-facilitator monitoring.

Installation

npm install @horizen/x402-private-vela-fixed @x402/core ethers

Requires @horizen/vela-common-ts for client-side P-521 encryption.

---

Facilitator usage

Register the scheme on an x402Facilitator instance from @x402/core:

import { x402Facilitator } from "@x402/core/facilitator";
import { registerPrivateVelaFixedScheme } from "@horizen/x402-private-vela-fixed";
import { ethers } from "ethers";

const facilitator = new x402Facilitator();

// Returns a Promise: the CAIP-2 network is derived from the RPC's chainId.
await registerPrivateVelaFixedScheme(facilitator, {
  rpcUrl: "https://rpc.vela.network",
  contractAddress: "0x<ProcessorEndpoint address>",
  signer: new ethers.Wallet(process.env.FACILITATOR_PRIVATE_KEY!),
  maxFeeValue: 0n,          // ETH in wei for service fees
  applicationId: 1n,        // vela-nova app ID
  // Optional: how long `/settle` waits for the TEE AppEvent (defaults 2s / 60s).
  appEventPollIntervalMs: 2_000,
  appEventPollTimeoutMs: 60_000,
});

The facilitator will handle POST /verify and POST /settle for the private-vela-fixed scheme. On /settle, the facilitator submits the request on-chain and then polls for the TEE's AppEvent matching the computed receipt hash before returning success; on timeout it returns errorReason: "tee_processing_timeout" while still reporting the on-chain requestId in extensions.

VelaSchemeConfig

Field	Type	Description
rpcUrl	string	Ethereum JSON-RPC URL. The CAIP-2 network identifier (eip155:<chainId>) is derived from this at registration time.
contractAddress	string	ProcessorEndpoint contract address
signer	ethers.Signer	Facilitator wallet (pays gas)
maxFeeValue	bigint	ETH in wei sent as msg.value for service fees
applicationId	bigint	vela-nova application ID
appEventPollIntervalMs	number?	Poll interval for the TEE AppEvent (default 2000)
appEventPollTimeoutMs	number?	Timeout before /settle returns tee_processing_timeout (default 60000)

---

Client (buyer) usage

Register the scheme on an x402Client instance to enable automatic payment on 402 responses:

import { x402Client } from "@x402/core/client";
import { registerPrivateVelaFixedClient } from "@horizen/x402-private-vela-fixed";
import { ethers } from "ethers";

const client = new x402Client("https://my-facilitator.example.com");

// Returns a Promise: the CAIP-2 network is derived from the RPC's chainId.
await registerPrivateVelaFixedClient(client, {
  signer: buyerSigner,           // ethers.Signer for EIP-712 + EIP-2612
  p521PrivateKey: buyerP521Key,  // buyer's P-521 CryptoKey (from vela-common-ts)
  teePublicKey: teeP521Key,      // TEE's P-521 CryptoKey (from ProcessorEndpoint.getPubSecp521r1())
  rpcUrl: "https://rpc.vela.network",
  contractAddress: "0x<ProcessorEndpoint address>",
});

// Automatically handles 402 responses:
const response = await client.fetch("https://seller.example.com/protected-content");

When the resource server returns a 402 Payment Required, the client:

1. Reads the current nonce from facilitatorNonces[sender] on-chain
2. Builds the PayloadInstructions JSON: { type: "transfer", transfer: { to, amount, invoice_id } }
3. Encrypts the payload with the TEE's P-521 public key using ECIES (via @horizen/vela-common-ts)
4. Signs the RequestAuthorization with EIP-712
5. Signs an EIP-2612 permit for the ERC-20 deposit
6. Retries the request with the payment payload in the X-PAYMENT header

VelaClientConfig

Field	Type	Description
signer	ethers.Signer	Buyer's Ethereum signer
p521PrivateKey	CryptoKey	Buyer's P-521 ECDH private key
teePublicKey	CryptoKey	TEE's P-521 ECDH public key
rpcUrl	string	Ethereum JSON-RPC URL. The CAIP-2 network identifier is derived from this.
contractAddress	string	ProcessorEndpoint contract address
applicationId	bigint?	vela-nova application ID (defaults to 1n)
skipOnchainDeposit	boolean?	If true, settle is a pure private-state transfer (no on-chain deposit / no permit). The buyer must have already deposited beforehand. Default false.

---

Resource server (seller) usage

Register the scheme on an x402ResourceServer to protect routes with payment requirements:

import { x402ResourceServer } from "@x402/core/server";
import { registerPrivateVelaFixedServer } from "@horizen/x402-private-vela-fixed";

const facilitatorClient = /* fetch-based facilitator client */;
const resourceServer = new x402ResourceServer(facilitatorClient);

registerPrivateVelaFixedServer(resourceServer, {
  network: "eip155:2651420",
  payTo: "0x<seller address>",
  tokenAddress: "0x<ERC-20 token address>",
  contractAddress: "0x<ProcessorEndpoint address>",
});

// Express middleware example:
app.use("/paid-content", resourceServer.middleware({
  amount: "1000000",         // token units
  extra: { invoiceId: "INV-001" },  // seller tracks this via TEE events
}));

The seller configures an invoiceId per-route in PaymentRequirements.extra. The facilitator cannot verify it (payload is encrypted), so the seller checks the invoice_id in the TEE event emitted after the TEE processes the transfer.

VelaServerConfig

Field	Type	Description
network	string	CAIP-2 network identifier
payTo	string	Seller's Ethereum address
tokenAddress	string	ERC-20 token for payments
contractAddress	string	ProcessorEndpoint contract address

---

EIP-712 domain and types

Domain:

name: "Vela"
version: "0"
chainId: <chain ID>
verifyingContract: <ProcessorEndpoint address>

RequestAuthorization type hash:

RequestAuthorization(
  address sender,
  uint8 protocolVersion,
  uint64 applicationId,
  uint8 requestType,
  bytes32 payloadHash,
  address tokenAddress,
  uint256 assetAmount,
  uint256 nonce,
  uint256 deadline
)

Request type constants:

• REQUEST_TYPE_PROCESS = 1 — private transfer
• REQUEST_TYPE_ASSOCIATEKEY = 3 — P-521 key registration

---

Exported types and interfaces

// From "@horizen/x402-private-vela-fixed"

// EIP-712 typed data
interface RequestAuthorization { sender, protocolVersion, applicationId, requestType, payloadHash, tokenAddress, assetAmount, nonce, deadline }

// EIP-2612 permit
interface DepositPermit { owner, spender, value, nonce, deadline, v, r, s }

// Full x402 payment payload
interface VelaPaymentPayload { sender, requestSignature, depositPermit, requestAuthorization, payload }

// Payload sent to TEE (encrypted)
interface PayloadInstructions { type: "transfer"; transfer: TransferInstruction }
interface TransferInstruction { to, amount, invoice_id, asset }

// Config types
interface VelaSchemeConfig { ... }   // facilitator
interface VelaClientConfig { ... }   // buyer
interface VelaServerConfig { ... }   // seller

---

Transfer receipt hash

computeTransferReceiptHash is a TypeScript port of the hash vela-nova emits as AppEvent.eventSubType when the TEE successfully processes a transfer with a non-empty invoiceId:

keccak256(
  uint32_be(len(invoiceId)) ||
  invoiceId                 ||
  sender        (20 bytes)  ||
  tokenAddress  (20 bytes)  ||
  amount        (32 bytes, big-endian zero-padded) ||
  recipient     (20 bytes)
)

Because the hash binds invoiceId + sender + tokenAddress + amount + recipient, a matching AppEvent is cryptographic proof that the TEE executed exactly that transfer. The facilitator uses this internally in /settle; sellers can use it to subscribe to the right AppEvent independently:

import { computeTransferReceiptHash } from "@horizen/x402-private-vela-fixed";

const expected = computeTransferReceiptHash({
  invoiceId: "INV-001",
  sender: buyerAddress,
  tokenAddress,
  amount: 1_000_000n,
  recipient: sellerAddress,
});

// Subscribe via VelaClient.getAppEvents(fromBlock, toBlock, appId, requestId, expected)

Compatibility note

This scheme uses EIP-2612 permit() for gasless ERC-20 approval (sequential nonces). Coinbase's reference x402 scheme uses EIP-3009 transferWithAuthorization instead. The two are not interchangeable — the ProcessorEndpoint.submitRequestFor() contract function specifically accepts EIP-2612 permit signatures, not EIP-3009.

References

• x402 protocol — Payment protocol specification
• ProcessorEndpoint.sol — On-chain contract
• vela-nova payload format — PayloadInstructions types
• vela-starterkit — Private transfer app docs