| name | updating-metadata |
| description | Edit a token's JSON metadata in-place — attribute swap, name correction, description update — and re-pin under dual-pin policy. JSON-only specialization of grafting-traits. |
| user-invocable | true |
| allowed-tools | Read, Write, Edit, Bash |
Updating Metadata
Specialized op called by grafting-traits for changes that touch only the JSON, not the image. Faster path than full graft (no image regeneration), but follows the same dual-pin + mutation-log discipline.
When to use
- Trait attribute correction (typo, wrong value, schema migration)
- Name or description field update (community-input proposal, lore expansion)
external_url or animation_url change
When NOT to use
- The image needs to change too — that's
updating-image or full grafting-traits
- The change requires regenerating the asset —
the-mint
- The metadata schema itself is changing — that's a collection-wide event, escalate to
cultivating-cycle
Workflow
- Read current metadata via
verifying-pin. Refuse if substrate is unhealthy.
- Apply the change-spec to the JSON.
- Re-hash; confirm the change actually mutated the bytes (operator-error guard).
- Dual-pin via
pinning-to-freeside + pinning-to-ipfs.
- Hand to
grafting-traits for the mutation log + protocol handoff.
Output shape
interface MetadataUpdateResult {
tokenId: number
old_hash: string
new_hash: string
diff: Record<string, {from: any, to: any}>
new_freeside_url: string
new_ipfs_cid: string
}
Anti-patterns
- Editing without diffing. Always log the field-level diff. "Metadata updated" with no diff is a black-box change.
- Skipping image-hash check. If the JSON's
image: field references a CID that no longer matches the actual image bytes, the metadata is broken even though it pinned cleanly. Validate.
- Treating updating-metadata as a non-graft. It's still a graft. Mutation log entry is mandatory.
Composes with
- Called by:
grafting-traits
- Calls:
verifying-pin · pinning-to-freeside · pinning-to-ipfs
- Hands to:
grafting-traits for log + protocol handoff
