feat(gateway): structured logging, tracing, and error taxonomy across gateway + SDKs

[aguilar1x]

Context

Failures in the gateway or SDK today surface as opaque errors with no correlation between a client-side failure and the corresponding gateway request. There's no way to trace a checkout end-to-end or classify failures by cause.

Scope

• Structured JSON logging in connect-gateway with request IDs propagated from connect-core's REST client through to gateway responses.
• A shared error taxonomy (e.g. PACTO_AUTH, PACTO_RATE_LIMIT, PACTO_UPSTREAM, PACTO_VALIDATION) surfaced consistently in SDK error objects.
• Basic tracing spans around the handshake → quote → escrow → webhook lifecycle, exportable to OpenTelemetry.

Acceptance criteria

• A failed checkout can be traced from connect-react error to the specific gateway log line via a shared request ID.
• SDK consumers can branch on error .code, not on parsing message strings.
• Tracing spans are emitted for at least the handshake and escrow-creation paths.

[OluRemiFour]

Hi Maintainer,
Interested in working on this issue. I'll implement the requested changes and ensure everything is properly tested before submission.

Payout wallet (Stellar): GALHFNUOYOY4S5CNRK7OI7NKS7UNWYGSJII2POQ6XQKWMUVLKZ2SAWMP GrantFox OSS campaign — smart escrow payout on merge.

[yunus-dev-codecrafter]

Hi! I've carefully reviewed the entire task description and fully understand the requirements and expected outcome.
I have experience working on similar tasks and I'm confident I can complete this within about an hour. I'd be happy to take ownership of this issue and submit a clean, well-tested solution promptly.
If it's available, please assign it to me. Thank you!

[Macnelson9]

Hi team, I'd love to work on this issue.

I'm a Full-Stack Web3 Developer with experience building Rust-based smart contracts and modern frontend applications using React/Next.js and TypeScript. I'm comfortable working across the entire stack, from contract development and integration to creating responsive, user-friendly interfaces.

I can deliver a clean, well-tested implementation that follows the project's standards and will provide regular progress updates throughout development.

Looking forward to contributing.

[Labi-Joy]

Hey, I would like to pick this up.

Right shape is a shared error type + a shared request-id header + tracing spans wired through the
gateway's logger, so a single failure in connect-react maps to a single log line in the gateway.

Plan:

1. Error taxonomy. New shared package @pacto/errors exporting a typed PactoError union: PACTO_AUTH,
   PACTO_RATE_LIMIT, PACTO_UPSTREAM, PACTO_VALIDATION, PACTO_TIMEOUT, PACTO_UNKNOWN. Each carries { code,
   message, requestId?, cause? }. Gateway and SDKs import from here so drift is caught by TS at compile
   time.

2. Request id propagation. Client-side, connect-core's REST client generates X-Request-Id
   (crypto.randomUUID) on every outbound call and stashes it on the resulting error. Gateway middleware
   reads or generates one, echoes it in response headers, and puts it on every log line.

3. Structured logging. Swap ad-hoc logging in the gateway for pino with req_id, path, method,
   duration_ms, status, error_code as top-level fields. Redaction rule so Authorization and any pk-signed
   body never make it into logs.

4. Tracing. OpenTelemetry on the gateway. Spans for pacto.handshake, pacto.quote, pacto.escrow.create,
   pacto.webhook.send, each carrying request_id as an attribute so lookups work. OTLP exporter
   env-configurable.

5. SDK surface. PactoError.code is stable and covered by tests. Consumers branch on .code, never on
   .message. Update the react package's default error UI to display the code.

6. Tests. Unit test per error path (auth, rate limit, upstream timeout, validation). One integration test
   that walks a failure through and asserts the same request_id appears in both the SDK error and the
   gateway log capture.

Timeline: 4 to 5 days, sequenced as (a) errors + request id, (b) logging + redaction, (c) tracing + SDK
surface.