Skip to content

Commit 831d922

Browse files
mintlify[bot]mintlify[bot]
authored
docs(sdk): add forwardToArbiter page and document named address constants
- New page for forwardToArbiter() with payload shape, error handling, and address re-exports - Updated installation page to show named constant imports alongside getChainConfig - Updated helpers card description in SDK overview - Added forwardToArbiter link to refundable() next steps Generated-By: mintlify-agent
1 parent c55572d commit 831d922

5 files changed

Lines changed: 179 additions & 10 deletions

File tree

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,7 @@
102102
"pages": [
103103
"sdk/merchant/getting-started",
104104
"sdk/helpers/refundable",
105+
"sdk/helpers/forward-to-arbiter",
105106
"sdk/merchant/quickstart",
106107
"sdk/merchant/refund-handling"
107108
]

‎sdk/helpers/forward-to-arbiter.mdx‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: "forwardToArbiter()"
3+
description: "Forward settlement data to an arbiter service for quality evaluation"
4+
icon: "arrow-right"
5+
---
6+
7+
The `forwardToArbiter()` function creates an `onAfterSettle` hook that forwards the response body and payment payload to an arbiter service. It runs fire-and-forget so it never blocks the response to the client.
8+
9+
- Only fires for successful **commerce** scheme settlements
10+
- POSTs `{ responseBody, transaction, paymentPayload }` to `{arbiterUrl}/verify`
11+
- Errors are silently caught so an unavailable arbiter cannot break the payment flow
12+
13+
## Usage
14+
15+
```typescript
16+
import { forwardToArbiter } from '@x402r/helpers';
17+
18+
const resourceServer = new x402ResourceServer(facilitatorClient)
19+
.register(networkId, new EscrowServerScheme())
20+
.onAfterSettle(
21+
forwardToArbiter('http://arbiter:3001')
22+
);
23+
```
24+
25+
## Function signature
26+
27+
```typescript
28+
function forwardToArbiter(
29+
arbiterUrl: string,
30+
options?: ForwardToArbiterOptions
31+
): (context: SettleResultContext) => Promise<void>
32+
```
33+
34+
### Parameters
35+
36+
| Parameter | Type | Description |
37+
|-----------|------|-------------|
38+
| `arbiterUrl` | `string` | Base URL of your arbiter service (e.g. `http://arbiter:3001`) |
39+
| `options` | `ForwardToArbiterOptions` | Optional configuration (see below) |
40+
41+
### Options
42+
43+
```typescript
44+
interface ForwardToArbiterOptions {
45+
/** Custom error handler. Defaults to `console.warn`. */
46+
onError?: (error: unknown) => void;
47+
}
48+
```
49+
50+
## Payload shape
51+
52+
When a commerce settlement succeeds, the hook POSTs the following JSON to `{arbiterUrl}/verify`:
53+
54+
```typescript
55+
{
56+
responseBody: string; // UTF-8 encoded response body
57+
transaction: string; // Settlement transaction hash
58+
paymentPayload: {
59+
x402Version: number;
60+
accepted: {
61+
scheme: string; // e.g. "commerce"
62+
network: string; // e.g. "eip155:84532"
63+
// ...other accepted fields
64+
};
65+
payload: {
66+
paymentInfo: {
67+
operator: string;
68+
payer: string;
69+
receiver: string;
70+
// ...full PaymentInfo
71+
};
72+
};
73+
};
74+
}
75+
```
76+
77+
<Tip>
78+
Arbiters that need `paymentInfo` for `release()` can read it directly from `paymentPayload.payload.paymentInfo` — no extra RPC call needed.
79+
</Tip>
80+
81+
## Error handling
82+
83+
By default, fetch errors are logged with `console.warn`. You can override this with a custom handler:
84+
85+
```typescript
86+
import { forwardToArbiter } from '@x402r/helpers';
87+
88+
const resourceServer = new x402ResourceServer(facilitatorClient)
89+
.register(networkId, new EscrowServerScheme())
90+
.onAfterSettle(
91+
forwardToArbiter('http://arbiter:3001', {
92+
onError: (err) => sentry.captureException(err),
93+
})
94+
);
95+
```
96+
97+
Errors are wrapped in an `X402rError` with the arbiter URL and request details for easier debugging.
98+
99+
## Skipped scenarios
100+
101+
The hook silently returns without making a request when:
102+
103+
- The settlement was not successful (`context.result.success === false`)
104+
- The scheme is not `commerce` (e.g. direct or other custom schemes)
105+
- No response body is available in the transport context
106+
107+
## Address re-exports
108+
109+
The `@x402r/helpers` package re-exports chain-invariant address constants from `@x402r/core` for convenience:
110+
111+
```typescript
112+
import {
113+
authCaptureEscrow,
114+
tokenCollector,
115+
protocolFeeConfig,
116+
arbiterRegistry,
117+
receiverRefundCollector,
118+
usdcTvlLimit,
119+
factories,
120+
conditions,
121+
getChainConfig,
122+
supportedChainIds,
123+
} from '@x402r/helpers';
124+
```
125+
126+
These are the same CREATE3 addresses available from `@x402r/core`. You can import from either package depending on which you already have installed.
127+
128+
## Next steps
129+
130+
<CardGroup cols={2}>
131+
<Card title="refundable()" icon="wrench" href="/sdk/helpers/refundable">
132+
Configure escrow options and fee bounds.
133+
</Card>
134+
<Card title="Arbiter SDK" icon="gavel" href="/sdk/arbiter/quickstart">
135+
Build an arbiter that processes forwarded settlements.
136+
</Card>
137+
<Card title="Examples" icon="code" href="/sdk/examples">
138+
See working merchant server examples.
139+
</Card>
140+
</CardGroup>

‎sdk/helpers/refundable.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,9 @@ app.get('/api/resource', (req, res) => {
155155
## Next Steps
156156

157157
<CardGroup cols={2}>
158+
<Card title="forwardToArbiter()" icon="arrow-right" href="/sdk/helpers/forward-to-arbiter">
159+
Forward settlement data to an arbiter for evaluation.
160+
</Card>
158161
<Card title="Deploy Operator" icon="rocket" href="/sdk/deploy-operator">
159162
Deploy a PaymentOperator to use with refundable().
160163
</Card>

‎sdk/installation.mdx‎

Lines changed: 34 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -37,18 +37,43 @@ Create `publicClient` and `walletClient` using [viem](https://viem.sh/docs/clien
3737

3838
## Contract Addresses
3939

40-
Get the deployed contract addresses from the network config:
40+
All protocol contracts use CREATE3 addresses that are the same on every supported chain. You can import them directly as named constants or look them up from a chain config:
4141

42-
```typescript
43-
import { getNetworkConfig } from '@x402r/core';
42+
<Tabs>
43+
<Tab title="Named constants">
44+
```typescript
45+
import {
46+
authCaptureEscrow,
47+
tokenCollector,
48+
protocolFeeConfig,
49+
arbiterRegistry,
50+
receiverRefundCollector,
51+
usdcTvlLimit,
52+
factories,
53+
conditions,
54+
} from '@x402r/core';
55+
56+
console.log(authCaptureEscrow); // 0xBC15…
57+
console.log(factories.paymentOperator); // 0x3Cd5…
58+
console.log(conditions.payer); // 0x808b…
59+
```
60+
</Tab>
61+
<Tab title="Chain config">
62+
```typescript
63+
import { getChainConfig } from '@x402r/core';
4464

45-
const config = getNetworkConfig('eip155:84532'); // Base Sepolia
65+
const config = getChainConfig(84532); // Base Sepolia
66+
67+
console.log(config.authCaptureEscrow); // Escrow contract
68+
console.log(config.arbiterRegistry); // ArbiterRegistry contract
69+
console.log(config.usdc); // USDC token address (chain-specific)
70+
```
71+
</Tab>
72+
</Tabs>
4673

47-
console.log(config.authCaptureEscrow); // Escrow contract
48-
console.log(config.refundRequest); // RefundRequest contract
49-
console.log(config.arbiterRegistry); // ArbiterRegistry contract
50-
console.log(config.usdc); // USDC token address
51-
```
74+
<Tip>
75+
The named constants and `getChainConfig()` return identical addresses. Use named constants when you don't need the chain-specific USDC address.
76+
</Tip>
5277

5378
<Note>
5479
Network identifiers use the [EIP-155](https://eips.ethereum.org/EIPS/eip-155) format: `eip155:<chainId>`. For Base Sepolia, use `'eip155:84532'`. For Base Mainnet, use `'eip155:8453'`.

‎sdk/overview.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ The SDK is organized into packages designed for specific roles in the payment ec
2828
SDK for arbiters to resolve disputes and manage refund decisions.
2929
</Card>
3030
<Card title="@x402r/helpers" icon="wrench" href="/sdk/helpers/refundable">
31-
Framework-agnostic helper to mark x402 payment options as refundable with escrow configuration.
31+
Framework-agnostic helpers: `refundable()` for escrow configuration, `forwardToArbiter()` for arbiter integration, and re-exported address constants.
3232
</Card>
3333
</CardGroup>
3434

0 commit comments

Comments
 (0)