Skip to main content
Version: v0.15.2

Integration Patterns

These patterns wire PEAC records into the systems you already run: MCP tool calls, OpenTelemetry, API gateways, and W3C trace context. Each uses an existing PEAC surface; none introduces a new protocol or extension group. PEAC carries and records evidence; it does not orchestrate, settle, or enforce.

W3C trace context to PEAC correlation​

Carry the distributed-trace identity into a PEAC record so a signed record can be correlated with a trace. Extract the traceparent from inbound headers and attach correlation fields under the org.peacprotocol/correlation extension key.

trace-correlation.ts
import { extractTraceparentFromHeaders, parseTraceparent } from '@peac/telemetry-otel';

const traceparent = extractTraceparentFromHeaders(req.headers);
const ctx = traceparent ? parseTraceparent(traceparent) : null;

const ext = ctx
  ? [{ 'org.peacprotocol/correlation': { trace_id: ctx.traceId, span_id: ctx.spanId } }]
  : [];

The correlation extension carries trace_id, span_id, workflow_id, parent_jti, and depends_on.

PEAC to OpenTelemetry span attributes​

Surface a record's identity on the active OTel span without putting the record body in telemetry. Configure the provider once, and PEAC sets peac.receipt.ref, peac.version, and peac.valid as span attributes.

otel-bridge.ts
import { createOtelProvider } from '@peac/telemetry-otel';
import { setTelemetryProvider } from '@peac/telemetry';

setTelemetryProvider(createOtelProvider());

Only the receipt_ref (a digest) reaches telemetry by default; the full record never does.

MCP _meta carrier​

Attach a record to an MCP tool response and read it back on the consuming side. The carrier embeds org.peacprotocol/receipt_ref and org.peacprotocol/receipt_jws in _meta, with an 8 KB embed limit.

mcp-carrier.ts
import { attachReceiptToMeta, computeReceiptRef } from '@peac/mappings-mcp';
import { issue } from '@peac/protocol';

const record = await issue({ iss, sub, typ: 'access' }, privateKey);
const meta = await attachReceiptToMeta({}, record, computeReceiptRef(record));

return { content: [{ type: 'text', text: result }], _meta: meta };

On the client, read it back with extractReceiptFromMetaAsync(response._meta) and verify offline.

Gateway and API export​

Records a gateway export with validateGatewayExport() from @peac/schema. This is observe-and-export: PEAC records the settlement state the caller reported under the org.peacprotocol/gateway-export extension key; it does not make the decision.

gateway-export.ts
import { validateGatewayExport } from '@peac/schema';

const result = validateGatewayExport({
  typ: 'access',
  ext: [{
    'org.peacprotocol/gateway-export': {
      event_kind: 'gateway-settlement-confirmed-observed',
      gateway_ref: 'urn:gateway:edge-1',
      payment_ref: 'urn:payment:abc',
      observed_at: new Date().toISOString(),
    },
  }],
});