onchain-buttons

Files (5)

• SKILL.md
• openai.yaml · agents/
• hook-pattern.md · references/
• journeys.md · references/
• sites-today.md · references/

SKILL.md (first lines)

# On-chain buttons

**Load `ash-stack` and `ash-frontend` first.** The wallet rules in
[regent-integration](../ash-stack/references/regent-integration.md#wallet-actions) apply
and are not repeated here. For chain events recorded in the database, use `chain-events`;
for a USDC payment's button, `payments`.

## Rules

1. **Every press reaches the wallet**, including a second press while the first is with
   the wallet or on its way to the chain. A reverted or duplicate transaction is an
   accepted outcome. Never hide, debounce, queue or merge presses, and never set
   `pointer-events: none`. Mark a press in progress with a data attribute and CSS only.
   The one exception (founder decisions, 2026-09-28 and 2026-10-06): the site may block a
   press that is certain to fail. When the chain's own current state, read by the server
   at the latest block, makes the transaction certain to fail, the button stays visible
   but `disabled` with a reason of a few words beside it, and it comes back when that
   state changes. Examples: "144/144 Keys sold"; a Buy whose USDC approval is not on the
   chain yet ("Approve first"); a payment larger than the wallet's USDC. A pending
   transaction, a repeat press, or one that only might revert is never a reason to
   disable. See [hook pattern](references/hook-pattern.md#markup).
2. **A hook's own click listener handles the press.** LiveView ignores a second
   `phx-click` on an element while the first is waiting for the server (lab: three presses,
   one event), and disables every button in a form while its `phx-submit` is in flight
   (lab). So an on-chain button has no `phx-click`, is never inside a `phx-submit` form,
   and never waits for a server round trip before the wallet opens when the step is
   already on the page.
3. **Privy's active wallet sends, when it is one of the account's own** (founder,
   21 Oct 2026, which replaces the 27 Sep "make them switch" decision). The hook reports
   the active wallet; when it is one of the signed-in account's linked wallets, the panel
   shows its figures and the server builds the steps for it. A wallet the account does
   not link is ignored, as if none were open: the figures stay on the account's own
   wallet, no note asks the person to switch, and a press sends nothing and names the
   account's wallets to open. Signed out, the active
   wallet's figures show and the first press opens Privy's sign-in (founder,
   2026-10-19). The account's linked wallets
   come from `AccessContext.linked_wallets/1` (`nil` signed out), never a hard-coded
   list. See [which wallet sends](references/hook-pattern.md#which-wallet-sends).
4. **The server builds every step** (founder decision, 2026-09-27): it encodes the
   calldata and pushes the review to the panel before the button is pressed. The
   browser never encodes a transaction. See
   [hook pattern](references/hook-pattern.md#the-server-builds-the-steps).
5. **Before sending**, switch the wallet to the step's chain (add it when the wallet
   answers 4902), then check the account is the step's signer and make `eth_chainId`
   the last read before `eth_sendTransaction`.
6. **An approval is a step of its own.** The next step's button appears as soon as the
   approval is sent; nothing waits for it to land before the next press can reach the
   wallet. Approve and Buy are the same size, and Approve turns grey with a green border
   once its transaction succeeds, still pressable. See
   [hook pattern](references/hook-pattern.md#approvals).
7. **The hook reports only what the wallet said**: the hash, or why nothing was sent.
   Each report names the review it was sent from, and `handleEvent` payloads carry the
   component's DOM id, since every hook on the page hears every `push_event`.
8. **The server checks the result at the latest block** (founder decision, 2026-09-26):
   read the receipt every quarter second (Sean, 15 Oct), confirm the transaction's sender, target and calldata are
   the step's, and show pending, done or reverted. Stop after a set number of reads and
   offer "Check again". Never use `safe` or `finalized`, never count confirmations, never
   store pending transactions. The chain watcher (`chain-events`) records the outcome for
   good.
9. **Words are for customers**: say what happened and what to do, never an error code.
   See the outcome table in [hook pattern](references/hook-pattern.md#outcomes-and-words).
10. **A step that names several items names only the ones the contract will take.** One
    refused item reverts the whole call (Keyfleet, 13 October 2026: one new Key blocked
    "Mark present" and a ballot for every other Key). When it builds such a step, the
    server reads each item's state at the latest block, leaves out the ones certain to be
    refused, and the review says which were left out and why.

## References

| File | Covers |
| --- | --- |
| [hook-pattern.md](references/hook-pattern.md) | The template's reference files, the review, which wallet sends, a press, the server's check, outcomes and words, checks |
| [journeys.md](references/journeys.md) | Listing a page's wallet journeys: controls, the shared wallet situations, per-control cases, marks; known gaps in the pattern |
| [sites-today.md](references/sites-today.md) | How each site does it now, where it differs from these rules, and which checkout to read |

## Checks

- Before a page with wallet buttons ships, list its journeys as
  [journeys.md](references/journeys.md) describes and mark every row.
- Run the page's wallet situations on a lab chain the way the template's
  `/showcase/onchain` workshop does (see [hook pattern](references/hook-pattern.md#checks)).
- Sites keep their own test policy; the template has no test suite. LiveView tests do not
  run hooks.
- A person checks real Privy and a browser-extension wallet on a lab chain before
  release; say so in the report rather than claiming it.
- Motion on the button comes from the kit (`data-press-label`, see `animejs`).

From regents-ai/ash-template, MIT.

More from regents-ai/ash-template