PPOps/ manual
Browse the beta.3 manual
skills/ppops/SKILL.md0.1.0-beta.3 / release

Agent Skill

The complete repository skill, including its safety boundaries and workflow references.

View source

This manual targets 0.1.0-beta.3. Read the source and availability policy before installing. Historical reports retain their original scope.

The skill is shipped in the beta.3 source tree under skills/ppops/. Install that complete directory, including references, scripts and assets, using your agent's skill mechanism. This page is a reading copy, not an installer. Source availability.

Operate and integrate PPOps through its existing CLI and HTTP API. Treat the merchant daemon as a view-only reconciliation service and the reference payer as a separate spending trust domain.

Enforce the trust boundary

  • Never request, load, copy, transform, or store a merchant mnemonic or RAILGUN spending key. PPOps accepts only the merchant shareable viewing key.
  • Ask for secret file paths, never secret values. Never print viewing keys, API tokens, signing keys, database-encryption keys, webhook keys, payer mnemonics, or EVM private keys.
  • Keep secrets and configuration in owner-only regular files (0600). Never commit them or place them in URLs, CLI arguments, screenshots, logs, or evidence artifacts.
  • Keep payer spending material off the PPOps merchant host. Use tools/ppops-payer only on the payer-controlled host.
  • Never treat OBSERVED or FINALIZED alone as payment. Fulfill only from the authenticated payment.confirmed event or an authenticated intent whose derived state is PAID/PAID_LATE; PPOps requires finality, SPENDABLE PPOI, and a valid match.
  • Do not submit a payer transaction or spend funds without explicit user approval of the network, asset, amount, fee ceiling, submission mode, and intended payment intent. Run prepare/no-send checks first.
  • Keep the v0.1 production profile on Arbitrum One (42161) and native USDC (0xaf88d065e77c8cC2239327C5EDb3A432268e5831, 6 decimals). Do not silently substitute another network, token, finality policy, RPC, or PPOI service.

Read references/SECURITY.md before any setup, integration, deployment, payer, or incident task.

Select the workflow

Set up a merchant instance

  1. Read references/QUICKSTART.md.
  2. Inspect package.json, node dist/cli.js help, and the selected release before proposing commands. Prefer an immutable release tag/container digest.
  3. Accept only an existing merchant viewing-key file. Do not help export or recover spending material as part of the daemon setup.
  4. Run the repository scripts/verify-install.sh against the source checkout. Its default verifies only the merchant; --with-payer is for release reviewers.
  5. Initialize PPOps with at least two independent RPC origins; recommend three for 2-of-3 availability. Do not select a paid provider or PPOI operator without the user’s direction.
  6. Run config-validate, preflight, then start the daemon.
  7. Run ppops doctor --offline, ppops preflight, then ppops status after starting. These commands never create an intent or submit a payment.
  8. Create a low-value intent only after the daemon is ready. State clearly that the payer must already have enough private native USDC in the Spendable bucket; first-time shield/PPOI onboarding and historical scan time have no fixed setup guarantee.

Integrate a merchant application

  1. Read references/API.md.
  2. Inspect the application. Use raw HTTP or the source package’s ppops/client helpers; the package is not published on npm. Read the canonical API/OpenAPI and use the runnable merchant example for webhook handling.
  3. Create intents server-side with a stable Idempotency-Key; persist the merchant order to PPOps intent-ID mapping.
  4. Expose only the unguessable checkout URL/request to the payer. Keep the API token and externalReference server-side.
  5. Verify webhook HMAC against the raw body, enforce timestamp freshness, and atomically deduplicate PPOps-Event-Id before fulfillment.
  6. Test duplicate delivery and non-2xx retry behavior.

Work on a payer integration

Read references/PAYER.md. Verify the descriptor against an expected merchant signer obtained independently of the checkout. The reference payer is testing/integration tooling, not a consumer wallet. Prepare first; submit only with explicit financial authorization.

Troubleshoot an installation

Read references/TROUBLESHOOTING.md. Preserve fail-closed behavior. Do not fix quorum, PPOI, scan, or webhook failures by weakening payment criteria or manually marking an intent paid.

Run an independent pilot

Read references/EXTERNAL-PILOT.md. Prefer an independently controlled merchant installation over payer-only validation. Collect consented, metadata-minimal evidence; never collect wallet secrets, transaction hashes, memo references, addresses, or invoice/customer IDs.

Completion criteria

For merchant setup, report success only when:

  • the pinned release/build verifies;
  • config-validate and network/PPOI preflight pass;
  • the daemon is live and ready;
  • authenticated runtime and metrics checks pass;
  • the merchant signer is recorded through an independent payer trust channel;
  • a backup/restore plan and real webhook receiver are documented.

For an end-to-end pilot, additionally require one actual private transfer to reach FINALIZED + SPENDABLE + MATCHED, one exact-once confirmation at the merchant application, and privacy-safe operator feedback. Document the exact verification environment and operational scope clearly.