Production safety

The built-in ledger and a raw private-key signer are convenient for development. An unattended machine needs durable payment state, protected signing, and a separate decision path for physical actions.

Provide a durable ledger

InMemoryRobotPaymentLedger is process-local. It cannot enforce a shared budget across replicas and loses receipts on restart. Production fleets should implement RobotPaymentLedger with durable storage:

interface RobotPaymentLedger {
  findByIdempotencyKey(
    robotId: string,
    idempotencyKey: string
  ): Promise<RobotSpendRecord | undefined>;

  getUsage(query: RobotSpendQuery): Promise<{
    amountAtomic: string;
    paymentCount: number;
  }>;

  record(record: RobotSpendRecord): Promise<void>;
}

Budget reservation must be atomic when multiple processes can pay from the same policy. The current client serializes payments only inside one client instance; the ledger is responsible for fleet-wide concurrency control.

Preserve idempotency

Use one stable idempotency key for one business action, for example a mission ID plus a charging attempt number. A completed or ambiguous payment receipt blocks reuse of that key.

If the SDK throws payment_outcome_unknown, the signed authorization may have reached the service even though its response did not reach the machine. Persist the attached receipt, reconcile through the service or chain, and do not create a replacement key automatically.

Protect signing authority

• Keep signing outside browser bundles and source control.
• Prefer a hardware-backed key or isolated edge wallet service.
• Limit wallet funds in addition to enforcing software policy.
• Rotate recipients and policies through an authenticated fleet-control channel.
• Require explicit policy entries before enabling a mainnet network or asset.

Keep payment separate from motion

A settled payment is commercial authorization. It is not proof that a charger, door, vehicle, or robot is physically safe to activate.

The hardware control layer should still enforce device identity, station state, telemetry freshness, mechanical interlocks, emergency stops, and operator policy. If settlement succeeds but hardware activation fails, record a compensation or refund case instead of repeatedly sending the command.

Operational checklist

• Use a durable, atomic ledger shared by every payer for the same budget.
• Alert on outcome_unknown, ledger_write_failed, and repeated policy denials.
• Reconcile submitted receipts against the service or chain.
• Keep redirect handling manual and resource URL matching enabled.
• Test recipient, price, asset, and network changes as denial cases.
• Exercise settlement-success/hardware-failure compensation before launch.
• Keep a human override outside the payment execution path.