Skip to content

Document transfer hooks - #355

Merged
ryley-o merged 2 commits into
mainfrom
transfer-hooks-docs
Sep 11, 2026
Merged

ryley-o merged 2 commits into
mainfrom
transfer-hooks-docs

Conversation

@ryley-o

@ryley-o ryley-o commented Sep 10, 2026 •

Copy link
Copy Markdown
Contributor

Core v3.3 adds a per-project contract that Engine cores call on every mint and transfer. Nothing described it outside the contract source.

Covers what a hook is, the v3.3 compatibility floor and why existing contracts cannot gain support, configuring and locking, reading the configuration on and off chain, and writing a hook. The security and cost constraints get their own weight: a hook must authenticate the calling core itself, it cannot reenter the core, its gas is paid by whoever moves the token, and locking freezes the hook address rather than the hook's behavior.

Cross-linked from the protocol overview alongside PostParams, the closest existing extension point.

Core v3.3 adds a per-project contract that Engine cores call on every mint and
transfer. Nothing described it outside the contract source.

Covers what a hook is, the v3.3 compatibility floor and why existing contracts
cannot gain support, configuring and locking, reading the configuration on and
off chain, and writing a hook. The security and cost constraints get their own
weight: a hook must authenticate the calling core itself, it cannot reenter the
core, its gas is paid by whoever moves the token, and locking freezes the hook
address rather than the hook's behavior.

Cross-linked from the protocol overview alongside PostParams, the closest
existing extension point.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C6jcGQ48oJZddVVQFpShAz
@ryley-o
ryley-o requested a review from a team as a code owner September 10, 2026 21:48
@github-actions

github-actions Bot commented Sep 10, 2026 •

Copy link
Copy Markdown
PR Preview Action v1.8.1

QR code for preview link

🚀 View preview at
https://ArtBlocks.github.io/artblocks-docs/pr-preview/pr-355/

Built to branch retype at 2026-09-10 22:46 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale comment

Left a non-blocking comment and did not approve: Cursor Security Agent: Security Reviewer was still pending after the wait window, so the required security-review signal did not complete. Reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router and Approver

@cursor
cursor Bot requested review from j3r3mys and jordanlyall September 10, 2026 21:55
Running a hook is not a signal to the rendering pipeline. Syncing a PostParam
write is: it calls triggerTokenProcessing with render and features set, and an
owner change has no equivalent.

That gap lands hardest on the projects most likely to want a hook. An artwork
that reacts to its owner renders correctly in the live generator the moment it
transfers, while the stored thumbnail on artblocks.io and in marketplaces keeps
showing the previous owner's output.

Documents the way out — an Address-authorized PostParam whose authorized
address is the hook contract, written from inside onTokenTransfer — along with
the two things that make it viable or not: the core blocks reentrant mints and
transfers but not calls to other contracts, and it doubles the storage cost
carried by every transfer for the life of the project.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C6jcGQ48oJZddVVQFpShAz

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved. Cursor Security Agent: Security Reviewer passed with no findings comment, and Cursor Bugbot was not running on this PR. No additional reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router and Approver

@ryley-o
ryley-o merged commit bf4dd8a into main Sep 11, 2026
5 checks passed
@ryley-o
ryley-o deleted the transfer-hooks-docs branch September 11, 2026 14:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants