Handling Metadata Changes

Token metadata on Trench is not fixed at launch. Holders vote on a token’s name, symbol, image, description, and links, and when a proposal passes, the new values are written on-chain. Anything you cached before that point is wrong from that moment on.

This applies to every integration that displays a Trench token, not only the ones that surface governance. If you cache a token’s name or image and never refresh it, your users will keep seeing the old values indefinitely. Nothing in the trading endpoints will tell you, because the mint does not change.

The Rule

Watch for ProposalSettledEvent from the Trench governance program. When one arrives with executed: true, the proposal passed and its action was written on-chain, so refetch that token’s metadata.

Why Settlement Is the Moment

Voting closing does not apply anything. A proposal sits closed but unapplied until someone calls settle, which computes the outcome and, if it passed, writes the change. Settling is permissionless, so it can happen minutes or days after voting ends, and anyone can trigger it, including you. There is therefore no fixed delay between a vote ending and metadata changing, which is why a timer based on votingEndsAtUnix is not a substitute for watching for the event.

The Event

The governance program at Fmy9Mi1RbcHPEht6ydGmrLGFCiU3P9JSUomVDEsYwF2J emits ProposalSettledEvent once per settlement.

Field	Type	Meaning
`governance`	pubkey	The governance account that settled
`proposal`	pubkey	The proposal that settled
`proposer`	pubkey	Wallet that created it
`proposal_index`	u64	Index within the governance
`action`	enum	`UpdateContent`, `ExtendMutability`, or `FinalizeMetadata`
`outcome`	enum	`Passed`, `Failed`, `Expired`, or `Superseded`
`executed`	bool	Whether the action was applied
`content_revision`	u64	The governance’s content revision after settlement
`finalized`	bool	Whether metadata is now permanently locked
`mutable_until`	i64	When metadata locks, after any extension
`mutability_extended`	bool	Whether the window has now been extended
Seven `*_locked` flags	bool	Per-field locks for name, symbol, image, description, website, twitter, and telegram
`yes_votes`, `no_votes`	u64	Final tally
`participating_supply`	u64	Total weight cast
`participating_voters`	u32	Distinct qualifying voters

The field to branch on is executed. Most settlements change nothing, because the proposal failed, expired, or was superseded, and only executed: true means state was written.

The event carries the governance state as it stands after settlement, so content_revision and the lock flags can be applied straight to your cache without a follow-up read. Only the metadata itself has to be fetched.

What Each Action Changes

Action	What `executed: true` means	Refetch metadata
`UpdateContent`	Name, symbol, and the metadata URI were rewritten	Yes
`ExtendMutability`	The mutability window moved	No, but update your cached `mutableUntilUnix`
`FinalizeMetadata`	Metadata is now locked permanently	No, but stop expecting further changes

Refetching on every executed: true regardless of action is simpler and always correct. The distinction only matters if a refetch is expensive for you.

What to Refetch

A content change touches two places, and both have to be re-read.

The metadata account

Name and symbol live on-chain, alongside the URI. The account address is metadata on the governance read response.

The JSON at the URI

Image, description, and links live off-chain in the document the URI points at. A content change pins new JSON, so the URI itself changes.

Key your image cache on the metadata URI rather than on the mint. New content is pinned at a new address, so a cache keyed on the mint will keep serving the old image even after you have refetched everything else correctly.

contentRevision Is Your Cache Key

The governance object exposes contentRevision, which increments on every applied content change. Store it alongside whatever you cached and you can establish staleness by comparison rather than by guesswork.

const { governance } = await trench.get(`/partner/v1/governance/${mint}`);

if (governance.contentRevision !== cached.contentRevision) {
  await refreshTokenMetadata(mint);
}

This matters because subscriptions are lossy. A websocket drops messages across reconnects, deploys, and outages, so a revision comparison is what catches the changes your listener missed.

Watching in Practice

Subscribe to program logs for the governance program and decode every Program data: line you receive. Decoding needs the governance IDL, which Trench provides, so ask your contact for it if you do not have it yet.

import { readFileSync } from "node:fs";
import { BorshEventCoder } from "@coral-xyz/anchor";
import { Connection, PublicKey } from "@solana/web3.js";

const GOVERNANCE_PROGRAM_ID = new PublicKey(
  "Fmy9Mi1RbcHPEht6ydGmrLGFCiU3P9JSUomVDEsYwF2J",
);
const PREFIX = "Program data: ";

const idl = JSON.parse(readFileSync("./trench_governance.json", "utf8"));
const coder = new BorshEventCoder(idl);
const connection = new Connection(process.env.SOLANA_RPC_URL, "confirmed");

connection.onLogs(GOVERNANCE_PROGRAM_ID, ({ err, logs }) => {
  if (err) return;

  for (const log of logs) {
    if (!log.startsWith(PREFIX)) continue;

    const event = coder.decode(log.slice(PREFIX.length));
    if (event?.name !== "ProposalSettledEvent") continue;
    if (!event.data.executed) continue;

    onGovernanceSettled({
      governance: event.data.governance.toBase58(),
      contentRevision: event.data.content_revision.toString(),
      contentChanged: "UpdateContent" in event.data.action,
    });
  }
}, "confirmed");

Two details catch people out. As of @coral-xyz/anchor 0.32, the decoder hands back the IDL’s snake_case field names rather than the camelCase Anchor uses elsewhere, so the field is content_revision and not contentRevision. Enum values also arrive as an object keyed by the variant name, which is why the action is tested with in rather than compared against a string.

The event cannot be read positionally. An UpdateContent action carries variable-length strings, so every field after action, including executed and content_revision, sits at an offset that depends on the proposal’s own contents. Decode it properly rather than slicing bytes at fixed offsets.

Subscribing per Token

If you follow a small, fixed set of tokens, an account subscription skips decoding altogether. The governance account is written on every settlement, so a change notification is your cue to re-read.

const { governance } = await trench.get(`/partner/v1/governance/${mint}`);

connection.onAccountChange(
  new PublicKey(governance.governance),
  () => refreshTokenMetadata(mint),
  "confirmed",
);

This costs one subscription per token, so it does not stretch to an open-ended catalogue, but it is the shortest path to correct behaviour when the set is small. Whichever you choose, reconcile on a schedule as well. Re-reading contentRevision for your tracked tokens on a slow loop costs little and bounds how long a missed update can survive.

When You Can Stop Watching

A token whose governance reports finalized: true has locked its metadata permanently, and no further content change is possible. The same becomes true once mutableUntilUnix has passed, whether or not anyone voted. Both are safe points at which to drop a token from your refresh set.

Get Started

Principles

How-to Guides

Handling Metadata Changes

The Rule

Why Settlement Is the Moment

The Event

What Each Action Changes

What to Refetch

contentRevision Is Your Cache Key

Watching in Practice

Subscribing per Token

When You Can Stop Watching

​The Rule

​Why Settlement Is the Moment

​The Event

​What Each Action Changes

​What to Refetch

​contentRevision Is Your Cache Key

​Watching in Practice

​Subscribing per Token

​When You Can Stop Watching

The Rule

Why Settlement Is the Moment

The Event

What Each Action Changes

What to Refetch

contentRevision Is Your Cache Key

Watching in Practice

Subscribing per Token

When You Can Stop Watching