Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
7 changes: 7 additions & 0 deletions .changeset/skill-objects-that-act.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
"@artblocks/abx-cli": patch
---

Teach the bundled skill that ABX objects can act on other protocols, not only read them: hooks and
custom minters can launch tokens, trade, or call other contracts as side effects of a mint, transfer,
burn, or setting change. Agents now offer acting designs alongside read-driven ones during ideation.
24 changes: 24 additions & 0 deletions .claude/skills/abx/reference/ecosystem.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,30 @@ Use this reference when a creator wants ideas involving existing protocols, comm
For public context, see [Ecosystem integrations](https://docs.abx.io/docs/using-abx/guides/ecosystem-integrations).
These are discovery routes, not tested ABX adapters or a promise of third-party compatibility.

## Contents

- [Objects can act, not only read](#objects-can-act-not-only-read)
- [Load by chain set and intent](#load-by-chain-set-and-intent)
- [Turn an idea into a bounded plan](#turn-an-idea-into-a-bounded-plan)
- [Input provenance and ABX execution](#input-provenance-and-abx-execution)
- [Account and dependency footprint](#account-and-dependency-footprint)
- [Integration boundaries to resolve](#integration-boundaries-to-resolve)

## Objects can act, not only read

Integration runs both ways. Reads (renderers, augment hooks) let an object reflect same-chain state.
Actions let it change the chain: configure hooks, transfer hooks, and custom minters can execute any
contract call as a side effect of a mint, transfer, burn, or governed parameter write. That includes
launching a token through a protocol's on-chain factory, swapping through an official router, minting
from another collection, paying a treasury, staking, voting, or settling a position. Offer acting
designs alongside read-driven ones during ideation; do not reduce an integration to a data input.

Design constraints for actions: hooks exist only on code projects; the hook must hold or be granted
the funds and approvals it spends (it never receives the holder's wallet); authenticate the calling
token; bound spend and slippage; guard reentrancy and repeated triggers; remember that a revert rolls
back the whole mint, transfer, or edit. Test every lifecycle path on a fork. See
[Custom mechanics](https://docs.abx.io/docs/using-abx/guides/custom-mechanics).

## Load by chain set and intent

Read the selected chain's context, then only the topic/provider relevant to the idea. Shared
Expand Down
8 changes: 6 additions & 2 deletions .claude/skills/abx/reference/ecosystem/tokens.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@ fallbacks should keep the NFT usable if reads fail. A gate's fallback must prese
## Companion token creation — Clanker as one starting reference

ABX creates its NFT collections; fungible token launch and management belong to a separate protocol.
The launch can be a one-time operation with that protocol's tools, or an ABX hook can call the
protocol's on-chain factory as a side effect of a mint or setting change, where the protocol allows
contract callers. Verify that before proposing it.
[Clanker's official SDK](https://github.com/clanker-devco/clanker-sdk) and
[official agent skill](https://github.com/clanker-devco/clanker-sdk/blob/main/.cursor/skills/use-clanker-sdk/SKILL.md)
provide one reusable route for creation, liquidity, and post-launch operations. Prefer these over
Expand All @@ -59,5 +62,6 @@ provider: a creator/agent may choose another protocol using the same verificatio
transaction review. No companion-token deployment, approval, or funding is implied by ideation.

For a proposal, record the token's chain and official identity, input field and provenance, ABX seam,
live versus captured behavior, resilience, new accounts/credentials, and runtime dependencies. Keep
token launch and ABX NFT deployment as separately reviewed operations, using each protocol's official tools.
live versus captured behavior, resilience, new accounts/credentials, and runtime dependencies. Review
the token launch terms and the ABX NFT deployment separately, using each protocol's official tools, even
when a hook will perform the launch later.
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

ABX is an open protocol and toolkit for programmable, durable digital objects on the blockchain.
An ABX project can be artwork, a shared resource, a record, or a financial or community mechanism:
anything whose data, state, permissions, and behavior matter as much as how it looks.
anything whose data, state, permissions, and behavior matter as much as how it looks. ABX objects can
also act: a mint, transfer, or setting change can launch a token, trade, or call any other contract.
The X is for anything; see [what you can build](https://docs.abx.io/docs/using-abx/what-you-can-build).

ABX is built for coding agents. Describe what you want to make, and the ABX skill teaches your agent
to plan, deploy, host, and operate it with the `abx` CLI, showing each plan and waiting for your
Expand Down
5 changes: 4 additions & 1 deletion site/app/(home)/page.tsx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import Link from 'next/link';
import {ArrowRight} from '@phosphor-icons/react/ssr';
import {PromptCard} from '@/components/prompt-card';
import {ABX_SUMMARY} from '@/lib/about';
import {ABX_SUMMARY, WHAT_YOU_CAN_BUILD_PATH} from '@/lib/about';
import {QUICKSTART_PROMPT} from '@/lib/quickstart';
import styles from './home.module.css';

Expand All @@ -21,6 +21,9 @@ export default function HomePage() {
<Link href="/docs/using-abx/quickstart" className={styles.primaryAction}>
Quickstart <ArrowRight aria-hidden weight="regular" />
</Link>
<Link href={WHAT_YOU_CAN_BUILD_PATH} className={styles.secondaryAction}>
Use cases
</Link>
<a href="https://github.com/ArtBlocks/abx" className={styles.secondaryAction}>
View source
</a>
Expand Down
3 changes: 2 additions & 1 deletion site/content/docs/using-abx/agent-and-skill.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,8 @@ ABX projects are programmable, durable digital objects built on standard ERC-721
contracts. Artwork, shared resources, records, and financial or community interactions are possible
directions. The agent
starts with the object's purpose, participants, data, and behavior rather than assuming an art drop.
On-chain, off-chain, and hybrid designs have different dependencies and trust assumptions.
On-chain, off-chain, and hybrid designs have different dependencies and trust assumptions. See
[What you can build](/docs/using-abx/what-you-can-build) for starting points and example prompts.

Exploration stays separate from implementation: choose a concept before asking the agent to build
it. A future launch plan or an available wallet does not by itself authorize starting a project.
Expand Down
36 changes: 31 additions & 5 deletions site/content/docs/using-abx/guides/ecosystem-integrations.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,35 @@ title: "Ecosystem integrations"
description: "Choose ecosystem integrations that fit an object's purpose, lifespan, and dependencies."
---

An ABX object can hold data, govern interactions, relate to a community, or respond to a pool's
state. Start with its purpose and behavior; its appearance is one part of the design. On-chain,
An ABX object can hold data, govern interactions, relate to a community, respond to a pool's state,
or trade in that pool itself. Start with its purpose and behavior; its appearance is one part of the
design. On-chain,
off-chain, and hybrid approaches are possible. For long-lived, self-contained output, prefer
same-chain EVM reads and usable fallbacks that survive loss of a website or third-party API.

## Read the chain, or act on it

Integration runs both ways. An ABX object can **read** other contracts: a renderer or augment hook
pulls a pool's price, a treasury's balance, or a community token's supply into what it shows. It can
also **act**: a configure hook, transfer hook, or custom minter runs contract calls as a side effect
of a mint, a transfer, a burn, or a setting change.

| When this happens | The object can | For example |
| --- | --- | --- |
| A token is minted | Run any contract call from the minter or transfer hook | Swap part of the mint price into a community token, or mint a companion piece from another collection |
| A holder changes a setting | Run calls before the new value is saved, or reject it | Launch an ERC-20 through a protocol's factory, stake, or vote from the object's own funds |
| A token changes hands | Run calls in the same transaction, or block the move | Pay a treasury, settle a position, or update a shared resource |
| Anything reads the token | Pull live state from same-chain contracts | Change color with a pool's price or grow with a treasury |

Hooks are contracts you write and attach to a code project (`abx deploy-code`), so whatever a contract
can do onchain, a hook can do. Side effects are
atomic: if one fails, the mint, transfer, or edit reverts with it. A hook never gets the holder's
wallet. Give it its own funds and approvals, authenticate the calling token, bound what it can spend,
and test every path on a fork first. [Custom mechanics](/docs/using-abx/guides/custom-mechanics)
covers the details.

## Use official tools

ABX handles its collection and parameters. Use each provider's official skills, MCP servers, CLIs,
SDKs, APIs, or contract interfaces for that provider's workflow. Separate tools used to research or
create a project from services the finished NFT would need forever. Official tooling can simplify
Expand Down Expand Up @@ -78,9 +102,11 @@ verified. Native and bridged assets differ; liquid tokens and locked voting posi
Balance alone does not prove sustained ownership or governance participation.

A companion token is optional. ABX creates the NFT collection; an external protocol creates and
manages the ERC-20. Clanker is a general starting reference with official launch and management
tools, not a required provider. Agents can use another protocol's official tooling where it fits.
Keep token launch, liquidity configuration, and ABX deployment as separate reviewed operations.
manages the ERC-20. Launch it once with the protocol's own tools, or have a hook call the protocol's
onchain factory as a side effect, so a mint or a setting change launches a token. Clanker is a general
starting reference with official launch and management tools, not a required provider. Agents can use
another protocol's official tooling where it fits. Review the token's launch terms, liquidity, and
fees on their own, separately from the ABX deployment, even when a hook performs the launch later.

## Keep track of setup

Expand Down
1 change: 1 addition & 0 deletions site/content/docs/using-abx/meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
"title": "Use ABX",
"icon": "Terminal",
"pages": [
"what-you-can-build",
"quickstart",
"installation",
"agent-and-skill",
Expand Down
122 changes: 122 additions & 0 deletions site/content/docs/using-abx/what-you-can-build.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
---
title: "What you can build"
description: "Websites, games, clocks, vaults, guestbooks, token launchers, and art. The X in ABX is for anything."
---

**ABX: the X is for anything.**

Generative art got here first. It won't be the last thing. An ABX project is a programmable object that
lives onchain. It can host a website, run a game, keep time, lock up money, remember who showed up, and
fire off transactions of its own.

Every ABX project is a standard ERC-721 or ERC-1155 contract, so wallets, marketplaces, and indexers
already know what to do with it. What it holds, what it does, and who gets to change it is up to you.

## Objects that act

Most NFTs just sit there. An ABX object can do things. Attach a hook to a code project, and every mint,
transfer, burn, or setting change can set off onchain actions in the same transaction:

- Launch a token through a protocol's factory.
- Swap into or out of a pool.
- Mint a piece from another collection.
- Pay a treasury, stake, vote, or settle a position.
- Say no, and block the action, when the rules aren't met.

If a side effect fails, the whole action rolls back. Nothing half-happens. A hook is a contract you
write, so whatever a contract can do onchain, a hook can do.
[Custom mechanics](/docs/using-abx/guides/custom-mechanics) shows how.

## Starting points

| Build | How ABX does it | Read more |
| --- | --- | --- |
| Websites and archives | ABX FS puts whole folders onchain, with version history and locks you control. Publish a site, a dapp, or an archive whose files live onchain. | [ABX utilities](/docs/using-abx/guides/utilities) |
| Apps and games | Store a program onchain. Every token runs it with its own seed and live settings. | [Code projects](/docs/protocol/code-projects) |
| Objects with rules | Give tokens values that holders can change, then decide who changes what: a level that only goes up, or a pass that can't be sold. | [Parameters](/docs/protocol/params) |
| Objects that act | Mints, transfers, and edits trigger contract calls. Launch a token, trade, pay out, or settle. | [Custom mechanics](/docs/using-abx/guides/custom-mechanics) |
| Protocol mashups | Read a pool, a treasury, or a community token, and act on them too. | [Ecosystem integrations](/docs/using-abx/guides/ecosystem-integrations) |
| Records and receipts | Store, compute, or hash-commit fields, then lock them. Every change leaves a public trail anyone can replay. | [Metadata](/docs/protocol/metadata), [Events](/docs/protocol/event-spine) |
| Data, models, and source files | Attach source files, print exports, 3D models, datasets, or audio stems to a token. | [Artifacts](/docs/protocol/data-plane) |
| Art, generative and otherwise | 1/1s, series, editions, and code-based work, onchain or off. | [Choose a project](/docs/using-abx/guides/deploy-a-digital-asset) |

## Live on ABX

Here's some of what people have shipped so far. Plenty of it is generative art. Plenty of it isn't.

**Objects that hold money**

- [Position Cards](https://arbiscan.io/address/0x6dd8e2d3ea605d6cc61f84896f967de476294b2e) (Arbitrum):
a card with its own wallet and its own Aave loan. The art shakes harder as the loan's health factor
falls. Survive a near-liquidation and the card keeps a crack for good.
- [HODL](https://hodl.ryley.studio) (Ethereum): lock ETH or an NFT until a date you pick. The
certificate can't be sold or moved until then, and nobody holds your funds, the creator included.
- [AB5D](https://ab5d.xyz/spot/) (Ethereum): an art exchange desk. Givers traded an AB[500] work for a
Debit and a Spot, or left the Debit for the next giver and held a Perp, an open position that
settled in turn.

**Clocks, puzzles, and live feeds**

- [Marfa Light](https://etherscan.io/address/0x4504570d25b710942bee78b7ff5720950c1fc02d) (Ethereum):
every token is a working clock for Marfa, Texas, with the sun, moon, and stars computed for the
minute you're looking.
- [ABXdoku](https://github.com/ArtBlocks/ABXdoku) (Base): a new Sudoku every day, with no server.
- [Bird Sightings](https://arbiscan.io/address/0x73903c55c814e33762acf53dac72f75a82c83724) (Arbitrum):
birds photographed live and identified by an agent, each logged onchain with its eBird species code
and the agent's confidence.

**People and places**

- [hollerith](https://thebenmeadows.com/marfa) (Ethereum): one IBM 029 punch card for every person
TheBenMeadows met in Marfa, Texas.
- [Sprite Party](https://www.spriteparty.com/) (Base): an event guestbook where every guest shows up as
a pixel sprite.
- [GenArt Foundation donor mural](https://www.genartfoundation.org/donors) (Base): a generative tile for
every $100 given, set into a mural that grows with each gift.
- [Grid No. 1](https://smint.xyz) (Ethereum): Vermeer's *Girl with a Pearl Earring* cut into 400
squares. Picks stay sealed until the board closes, and each square's edition size is the number of
people who picked it.

**Sites and communities**

- [coinspace](https://coinspace.social) (Base): a community where you make a page and own it.
- [cc0py site](https://etherscan.io/address/0x36a34158ad7ead3b8502585136e7add92e4fb8d3) (Ethereum):
cc0py's site for minting, browsing, and trading, published as an ABX project.

**And yes, art**

- [Under the Influence](https://www.gifs.shop) (Ethereum): 10,000 animated GIFs from the squiggle mill,
each drawn from its token's hash by a program stored onchain.
- [Marfa Project](https://marfa-project.grimble.xyz/1984/) (Ethereum): CGA faces, Kid Pix on an
emulated Macintosh, and a 1997 screensaver synced to music.
- [Squeegee](https://etherscan.io/address/0x27b1f8ea02775e29ce6a12a9c91141b3282e55ed) by Bryan
Brinkman (Ethereum).

That's the list so far. The best ABX idea hasn't been thought of yet.

## Prompts to steal

Paste one into your agent and change it until it's yours:

- "Help me put my band's website onchain and sell the album as an edition."
- "Help me make a clock for my hometown that shows the real sky."
- "Help me make a guestbook for my event where every guest gets a token."
- "Help me make a vault that locks ETH until a date, with a certificate that counts down."
- "Help me make a membership pass whose level only goes up and that can't be sold."
- "Help me make a ticket that swaps part of its mint price into our community token."
- "Help me make a pass that launches a token for its holder when they flip a switch."
- "Help me make a daily puzzle that changes at midnight UTC without a server."

Tell the agent what the thing is for, who uses it, what changes over time, and who gets to change it.
Looks come later. With the [ABX skill](/docs/using-abx/agent-and-skill), the agent explores ideas with
you and waits for you to pick one before it builds anything.

## Before you build

- These are patterns, not buttons. Rules and side effects live in a contract you write and test on a
fork or testnet.
- Hooks attach to code projects created with `abx deploy-code`. An image series can't add them later.
- A hook spends its own funds and approvals. It never gets the holder's wallet.
- A token can stand for rights or money, but real-world rights, custody, and enforcement need their own
legal design.
- Putting code onchain doesn't put the services it calls onchain. Plan for each one.
13 changes: 10 additions & 3 deletions site/lib/about.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,13 @@
export const ABX_SUMMARY =
'ABX is an open protocol and toolkit for programmable, durable digital objects on the blockchain. Describe what you want to make, and your coding agent plans, deploys, and operates it with the ABX CLI.';

/** Context for agents reading llms.txt: what ABX projects are built on and where to start. */
export const ABX_LLMS_CONTEXT =
'ABX projects are standard ERC-721 and ERC-1155 contracts on EVM chains. ABX adds onchain and offchain content storage, Solidity-computed or locked metadata, typed parameters and hooks, shared sale contracts, and a replayable event log. Start with the Quickstart and install the ABX skill before planning a deployment.';
export const WHAT_YOU_CAN_BUILD_PATH = '/docs/using-abx/what-you-can-build';

/** Context for agents reading llms.txt: what ABX is for, what it is built on, and where to start. */
export const ABX_LLMS_CONTEXT = [
'ABX: the X is for anything. ABX is not only for generative art. Projects include websites and archives stored onchain with ABX FS, apps and games, clocks, vaults, guestbooks, records, datasets, and art.',
'ABX objects can act, not only display. Hooks on a mint, transfer, burn, or setting change can launch a token, trade in a pool, mint from another collection, pay a treasury, or call any other contract in the same transaction. See [What you can build](https://docs.abx.io' +
WHAT_YOU_CAN_BUILD_PATH +
') for live projects and starting points. The best ABX idea has not been built yet.',
'ABX projects are standard ERC-721 and ERC-1155 contracts on EVM chains. ABX adds onchain and offchain content storage, Solidity-computed or locked metadata, typed parameters and hooks, shared sale contracts, and a replayable event log. Start with the Quickstart and install the ABX skill before planning a deployment.',
].join('\n\n');
Loading