Skip to content

Document dataSuffix for Base Pay attribution #1177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
spencerstock wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Document dataSuffix for Base Pay attribution #1177

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/base-account/guides/accept-payments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -313,6 +313,27 @@ See full props and theming options in the [Button Reference](/base-account/refer
If you intend on using the BasePayButton, please follow the [Brand Guidelines](/base-account/reference/ui-elements/brand-guidelines) to ensure consistency across your application.
</Warning>

## Attribution (dataSuffix)

Pass a `dataSuffix` to attribute payments to your app via [Builder Codes](/base-chain/builder-codes/builder-codes). The suffix is appended to the transaction calldata and must be a `0x`-prefixed hex string with no fixed length requirement.

```ts Payment with Attribution (dataSuffix)
import { pay } from '@base-org/account';

// Replace with your app's ERC-8021 data suffix from Builder Codes.
const DATA_SUFFIX = '0x07626173656170700080218021802180218021802180218021';

const payment = await pay({
amount: '10.50',
to: '0xRecipient',
dataSuffix: DATA_SUFFIX,
});
```

<Tip>
If your suffix is not a valid `0x`-prefixed hex string, `pay()` will throw a validation error before submitting the transaction.
</Tip>

## Test on Base Sepolia

1. Get test USDC from the <a href="https://faucet.circle.com" target="_blank">Circle Faucet</a> (select "Base Sepolia").
Expand Down
22 changes: 22 additions & 0 deletions docs/base-account/reference/base-pay/pay.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ Ethereum address to send USDC to (must start with 0x).
**Pattern:** `^0x[0-9a-fA-F]{40}$`
</ParamField>

<ParamField body="dataSuffix" type="`0x${string}`">
Optional attribution data suffix to append to the transaction calldata. Must be a `0x`-prefixed hex string (e.g., `"0xabc123"`). Use this to pass [Builder Codes](/base-chain/builder-codes/builder-codes) or other onchain attribution identifiers. No fixed length requirement.
</ParamField>

<ParamField body="testnet" type="boolean">
Set to true to use Base Sepolia testnet instead of mainnet. Default: false
</ParamField>
Expand Down Expand Up @@ -98,6 +102,24 @@ try {
}
```

```typescript Payment with Attribution (dataSuffix)
import { pay } from '@base-org/account';

// Replace with your app's ERC-8021 data suffix from Builder Codes.
const DATA_SUFFIX = "0x07626173656170700080218021802180218021802180218021";

try {
const payment = await pay({
amount: "10.50",
to: "0x1234567890123456789012345678901234567890",
dataSuffix: DATA_SUFFIX,
});
console.log(`Payment sent! Transaction ID: ${payment.id}`);
} catch (error) {
console.error(`Payment failed: ${error.message}`);
}
```

```typescript Payment with Data Collection
try {
const payment = await pay({
Expand Down
4 changes: 2 additions & 2 deletions docs/base-account/reference/core/createBaseAccount.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,11 +40,11 @@ Attribution configuration for Smart Wallet transactions.

<Expandable title="Attribution properties">
<ParamField body="auto" type="boolean">
When true, Smart Wallet will generate a 16 byte hex string from the app's origin.
When true, Smart Wallet will generate a deterministic hex suffix from the app's origin.
</ParamField>

<ParamField body="dataSuffix" type="`0x${string}`">
Custom 16 byte hex string appended to initCode and executeBatch calldata. Cannot be used with `auto: true`.
Custom `0x`-prefixed hex string appended to initCode and executeBatch calldata. Cannot be used with `auto: true`.
</ParamField>
</Expandable>
</ParamField>
Expand Down