---
referrals: 3
kind: program
payer: domain:dex.example
code: example_dex
category: onchain
status: open
at: 2026-10-30T00:00:00Z
---
# Example swap builder code share

Rates, amounts and names in this file are placeholders, not recommendations or market rates. Each party sets its own terms.

In plain words: a front end that puts its public builder code on a swap earns 13% of the fee on that swap. A reorg takes it back. If the same transaction is mined again, it counts as a new fact and earns again.

Ask a lawyer about: whether pay tied to a sale or trade of tokens needs a license where you and the front end operate, and what your sanctions and identity checks must cover. A check here says nothing about either.

Change first: `payer`, `code`, the rate and the asset. The asset, addresses and hashes below are made up. A builder code is a public claim, equal to an unsigned token: anyone can copy it, or put it on volume they made. Log chain events only after your own finality rule.

## Rules

### fee_share

- on: chain_swap
- basis: percent
- rate: 13%
- of: fee

## Attribution

- model: last_touch
- window_days: 30
- match: token, code
- allowed_kinds: builder_code

## Settlement

- holdback_days: 30
- clawback_days: 60
- cycle: monthly
- payout_asset: caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001
- rails: stablecoin

## Assets

| asset | scale |
|---|---|
| caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001 | 6 |

## Example

Made-up lines. A chain event has no `owner`, so anyone with the transaction list derives the same ids. Its `source` is the chain, the transaction, the log index and the block hash. The swap is reorged out and then mined again in a new block, with a new block hash.

To run it, save this file as `REFERRALS.md` and these lines as `referrals.jsonl`, then run `node referrals.mjs run REFERRALS.md referrals.jsonl --as-of 2027-01-15T00:00:00Z`.

As of: 2027-01-15T00:00:00Z

```jsonl
{"type":"agreement","code":"front_end","partner":"domain:frontend.example"}
{"type":"event","at":"2026-11-03T00:00:00Z","kind":"chain_swap","source":"chain:eip155:8453:0x7a1f000000000000000000000000000000000000000000000000000000000c01:7:0xb100000000000000000000000000000000000000000000000000000000000001","program":"rp_1fa37fa553147dc332d2d964","wallet":"eip155:8453:0x00000000000000000000000000000000000000aa","amount":"5000.000000","fee":"12.500000","asset":"caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001","codes":["front_end"],"carrier":"erc8021_suffix","chain":{"caip2":"eip155:8453","tx":"0x7a1f000000000000000000000000000000000000000000000000000000000c01","log":7,"block":100,"block_hash":"0xb100000000000000000000000000000000000000000000000000000000000001","from":"0x00000000000000000000000000000000000000aa","to":"0x00000000000000000000000000000000000000bb"}}
{"type":"event","at":"2026-11-03T01:00:00Z","kind":"reorg","source":"chain:eip155:8453:0x7a1f000000000000000000000000000000000000000000000000000000000c01:7:0xb100000000000000000000000000000000000000000000000000000000000001eorg","program":"rp_1fa37fa553147dc332d2d964","wallet":"eip155:8453:0x00000000000000000000000000000000000000aa","asset":"caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001","reverses":"ev_fa055b80c8ca2e577d7fab9c","chain":{"caip2":"eip155:8453","tx":"0x7a1f000000000000000000000000000000000000000000000000000000000c01","log":7,"block":100,"block_hash":"0xb100000000000000000000000000000000000000000000000000000000000001","from":"0x00000000000000000000000000000000000000aa","to":"0x00000000000000000000000000000000000000bb"}}
{"type":"event","at":"2026-11-03T02:00:00Z","kind":"chain_swap","source":"chain:eip155:8453:0x7a1f000000000000000000000000000000000000000000000000000000000c01:7:0xb200000000000000000000000000000000000000000000000000000000000002","program":"rp_1fa37fa553147dc332d2d964","wallet":"eip155:8453:0x00000000000000000000000000000000000000aa","amount":"5000.000000","fee":"12.500000","asset":"caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001","codes":["front_end"],"carrier":"erc8021_suffix","chain":{"caip2":"eip155:8453","tx":"0x7a1f000000000000000000000000000000000000000000000000000000000c01","log":7,"block":101,"block_hash":"0xb200000000000000000000000000000000000000000000000000000000000002","from":"0x00000000000000000000000000000000000000aa","to":"0x00000000000000000000000000000000000000bb"}}
```

## Worked result

Computed by `run_ledger` as of 2027-01-15T00:00:00Z, on the made-up lines above. Computed amounts are arithmetic on the records and terms you sent. They do not say what anyone owes. Your contract decides that.

| Event | Who | Working | Computed | Note |
|---|---|---|---|---|
| chain_swap, 2026-11-03 | front_end | 13% of 12.500000 | 1.625000 |  |
| reorg, 2026-11-03 | front_end | Reverses what was computed on chain_swap, 2026-11-03 | -1.625000 |  |
| chain_swap, 2026-11-03 | front_end | 13% of 12.500000 | 1.625000 |  |

| Payee | Asset | Earned | Reversed | Net | Held | Payable |
|---|---|---|---|---|---|---|
| front_end | caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001 | 3.250000 | -1.625000 | 1.625000 | 0.000000 | 1.625000 |


## Why these settings

Paying on `fee` rather than `amount` removes the reason to swap with yourself for the pay, and a block hash in the source id keeps a re-mined transaction from being lost.