feat(solana): support token icons and descriptions on wrapped tokens

Token-2022 has no icon or description fields; both are served from the
off-chain JSON document that its `uri` field points at. That field was
initialized to an empty string, so wrapped tokens could never carry either.

Adds `uri` to `PartialTokenMetadata` and passes it through to the metadata
initialize CPI. It is deliberately excluded from the mint's PDA hash: that
hash is recomputed from onchain metadata to authenticate a mint as a wrapped
token, so extending the preimage would move every already-deployed mint to an
address the program no longer derives.

`wrap_token` keeps its exact wire format, taking a `PartialTokenMetadataV1`
argument whose layout is byte-identical to the previous type, and delegates
with an empty uri. `wrap_token_v2` accepts the uri. Both derive the same mint.

`set_wrapped_token_uri` fills in a missing uri. It is permissionless because a
wrapped mint has no owner, and write-once so an existing uri can never be
overwritten. This is what lets tokens wrapped before this change, and those
wrapped through the deprecated instruction, get icons.

Also fixes `create_mock_wrapped_mint`, which left `update_authority` unset and
so did not match a real wrapped mint in the one field metadata writes depend on.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jackchuma

clients/ts/src/bridge/generated/errors/bridge.ts

@@ -84,6 +84,12 @@ export const BRIDGE_ERROR__INVALID_SCALER_EXPONENT = 0x319f; // 12703
 export const BRIDGE_ERROR__MINT_IS_NOT_FROM_TOKEN2022 = 0x31a0; // 12704
 /** MintIsNotWrappedTokenPda: Mint is not a valid wrapped token PDA */
 export const BRIDGE_ERROR__MINT_IS_NOT_WRAPPED_TOKEN_PDA = 0x31a1; // 12705
+/** UriTooLong: Token metadata uri is too long */
+export const BRIDGE_ERROR__URI_TOO_LONG = 0x31a2; // 12706
+/** EmptyUri: Token metadata uri is empty */
+export const BRIDGE_ERROR__EMPTY_URI = 0x31a3; // 12707
+/** UriAlreadySet: Token metadata uri is already set and cannot be changed */
+export const BRIDGE_ERROR__URI_ALREADY_SET = 0x31a4; // 12708
 /** InvalidThreshold: Threshold must be <= number of signers */
 export const BRIDGE_ERROR__INVALID_THRESHOLD = 0x3200; // 12800
 /** TooManySigners: Too many signers (max 32) */
@@ -114,6 +120,7 @@ export type BridgeError =
   | typeof BRIDGE_ERROR__CREATION_WITH_NON_ZERO_TARGET
   | typeof BRIDGE_ERROR__DUPLICATE_SIGNER
   | typeof BRIDGE_ERROR__EMPTY_MMR
+  | typeof BRIDGE_ERROR__EMPTY_URI
   | typeof BRIDGE_ERROR__INCORRECT_BLOCK_NUMBER
   | typeof BRIDGE_ERROR__INCORRECT_BRIDGE_PROGRAM
   | typeof BRIDGE_ERROR__INCORRECT_GAS_FEE_RECEIVER
@@ -150,6 +157,8 @@ export type BridgeError =
   | typeof BRIDGE_ERROR__UNAUTHORIZED_CONFIG_UPDATE
   | typeof BRIDGE_ERROR__UNAUTHORIZED_INITIALIZATION
   | typeof BRIDGE_ERROR__UNUSED_PROOF_ELEMENTS_REMAINING
+  | typeof BRIDGE_ERROR__URI_ALREADY_SET
+  | typeof BRIDGE_ERROR__URI_TOO_LONG
   | typeof BRIDGE_ERROR__ZERO_ADDRESS;
 
 let bridgeErrorMessages: Record<BridgeError, string> | undefined;
@@ -163,6 +172,7 @@ if (process.env.NODE_ENV !== 'production') {
     [BRIDGE_ERROR__CREATION_WITH_NON_ZERO_TARGET]: `Creation with non-zero target`,
     [BRIDGE_ERROR__DUPLICATE_SIGNER]: `Duplicate signer found`,
     [BRIDGE_ERROR__EMPTY_MMR]: `MMR is empty`,
+    [BRIDGE_ERROR__EMPTY_URI]: `Token metadata uri is empty`,
     [BRIDGE_ERROR__INCORRECT_BLOCK_NUMBER]: `Incorrect block number`,
     [BRIDGE_ERROR__INCORRECT_BRIDGE_PROGRAM]: `Incorrect bridge program`,
     [BRIDGE_ERROR__INCORRECT_GAS_FEE_RECEIVER]: `Incorrect gas fee receiver`,
@@ -199,6 +209,8 @@ if (process.env.NODE_ENV !== 'production') {
     [BRIDGE_ERROR__UNAUTHORIZED_CONFIG_UPDATE]: `Unauthorized to update configuration`,
     [BRIDGE_ERROR__UNAUTHORIZED_INITIALIZATION]: `Only the upgrade authority can initialize the bridge`,
     [BRIDGE_ERROR__UNUSED_PROOF_ELEMENTS_REMAINING]: `Unused proof elements remaining`,
+    [BRIDGE_ERROR__URI_ALREADY_SET]: `Token metadata uri is already set and cannot be changed`,
+    [BRIDGE_ERROR__URI_TOO_LONG]: `Token metadata uri is too long`,
     [BRIDGE_ERROR__ZERO_ADDRESS]: `Zero address`,
   };
 }

clients/ts/src/bridge/generated/instructions/index.ts

@@ -39,5 +39,7 @@ export * from './setOracleSigners';
 export * from './setPartnerOracleConfig';
 export * from './setPauseStatus';
 export * from './setWindowDuration';
+export * from './setWrappedTokenUri';
 export * from './transferGuardian';
 export * from './wrapToken';
+export * from './wrapTokenV2';

clients/ts/src/bridge/generated/instructions/setWrappedTokenUri.ts

@@ -0,0 +1,280 @@
+/**
+ * This code was AUTOGENERATED using the Codama library.
+ * Please DO NOT EDIT THIS FILE, instead use visitors
+ * to add features, then rerun Codama to update it.
+ *
+ * @see https://github.com/codama-idl/codama
+ */
+
+import {
+  addDecoderSizePrefix,
+  addEncoderSizePrefix,
+  combineCodec,
+  fixDecoderSize,
+  fixEncoderSize,
+  getBytesDecoder,
+  getBytesEncoder,
+  getStructDecoder,
+  getStructEncoder,
+  getU32Decoder,
+  getU32Encoder,
+  getUtf8Decoder,
+  getUtf8Encoder,
+  transformEncoder,
+  type AccountMeta,
+  type AccountSignerMeta,
+  type Address,
+  type Codec,
+  type Decoder,
+  type Encoder,
+  type Instruction,
+  type InstructionWithAccounts,
+  type InstructionWithData,
+  type ReadonlyAccount,
+  type ReadonlyUint8Array,
+  type TransactionSigner,
+  type WritableAccount,
+  type WritableSignerAccount,
+} from '@solana/kit';
+import { BRIDGE_PROGRAM_ADDRESS } from '../programs';
+import { getAccountMetaFactory, type ResolvedAccount } from '../shared';
+
+export const SET_WRAPPED_TOKEN_URI_DISCRIMINATOR = new Uint8Array([
+  248, 70, 157, 26, 216, 32, 48, 11,
+]);
+
+export function getSetWrappedTokenUriDiscriminatorBytes() {
+  return fixEncoderSize(getBytesEncoder(), 8).encode(
+    SET_WRAPPED_TOKEN_URI_DISCRIMINATOR
+  );
+}
+
+export type SetWrappedTokenUriInstruction<
+  TProgram extends string = typeof BRIDGE_PROGRAM_ADDRESS,
+  TAccountPayer extends string | AccountMeta<string> = string,
+  TAccountMint extends string | AccountMeta<string> = string,
+  TAccountBridge extends string | AccountMeta<string> = string,
+  TAccountTokenProgram extends
+    | string
+    | AccountMeta<string> = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
+  TAccountSystemProgram extends
+    | string
+    | AccountMeta<string> = '11111111111111111111111111111111',
+  TRemainingAccounts extends readonly AccountMeta<string>[] = [],
+> = Instruction<TProgram> &
+  InstructionWithData<ReadonlyUint8Array> &
+  InstructionWithAccounts<
+    [
+      TAccountPayer extends string
+        ? WritableSignerAccount<TAccountPayer> &
+            AccountSignerMeta<TAccountPayer>
+        : TAccountPayer,
+      TAccountMint extends string
+        ? WritableAccount<TAccountMint>
+        : TAccountMint,
+      TAccountBridge extends string
+        ? ReadonlyAccount<TAccountBridge>
+        : TAccountBridge,
+      TAccountTokenProgram extends string
+        ? ReadonlyAccount<TAccountTokenProgram>
+        : TAccountTokenProgram,
+      TAccountSystemProgram extends string
+        ? ReadonlyAccount<TAccountSystemProgram>
+        : TAccountSystemProgram,
+      ...TRemainingAccounts,
+    ]
+  >;
+
+export type SetWrappedTokenUriInstructionData = {
+  discriminator: ReadonlyUint8Array;
+  uri: string;
+};
+
+export type SetWrappedTokenUriInstructionDataArgs = { uri: string };
+
+export function getSetWrappedTokenUriInstructionDataEncoder(): Encoder<SetWrappedTokenUriInstructionDataArgs> {
+  return transformEncoder(
+    getStructEncoder([
+      ['discriminator', fixEncoderSize(getBytesEncoder(), 8)],
+      ['uri', addEncoderSizePrefix(getUtf8Encoder(), getU32Encoder())],
+    ]),
+    (value) => ({
+      ...value,
+      discriminator: SET_WRAPPED_TOKEN_URI_DISCRIMINATOR,
+    })
+  );
+}
+
+export function getSetWrappedTokenUriInstructionDataDecoder(): Decoder<SetWrappedTokenUriInstructionData> {
+  return getStructDecoder([
+    ['discriminator', fixDecoderSize(getBytesDecoder(), 8)],
+    ['uri', addDecoderSizePrefix(getUtf8Decoder(), getU32Decoder())],
+  ]);
+}
+
+export function getSetWrappedTokenUriInstructionDataCodec(): Codec<
+  SetWrappedTokenUriInstructionDataArgs,
+  SetWrappedTokenUriInstructionData
+> {
+  return combineCodec(
+    getSetWrappedTokenUriInstructionDataEncoder(),
+    getSetWrappedTokenUriInstructionDataDecoder()
+  );
+}
+
+export type SetWrappedTokenUriInput<
+  TAccountPayer extends string = string,
+  TAccountMint extends string = string,
+  TAccountBridge extends string = string,
+  TAccountTokenProgram extends string = string,
+  TAccountSystemProgram extends string = string,
+> = {
+  /** The account that pays for the mint account's rent increase. */
+  payer: TransactionSigner<TAccountPayer>;
+  /**
+   * The wrapped token mint whose uri is being filled in. Validated to be a wrapped token PDA of
+   * this program by recomputing its metadata hash, which is what makes the mint's own signature
+   * available for the metadata update below.
+   */
+  mint: Address<TAccountMint>;
+  /** The main bridge state account, read to honor the pause switch. */
+  bridge: Address<TAccountBridge>;
+  /** SPL Token-2022 program that owns the mint's metadata extension. */
+  tokenProgram?: Address<TAccountTokenProgram>;
+  /** System program used to top up the mint's rent before its metadata grows. */
+  systemProgram?: Address<TAccountSystemProgram>;
+  uri: SetWrappedTokenUriInstructionDataArgs['uri'];
+};
+
+export function getSetWrappedTokenUriInstruction<
+  TAccountPayer extends string,
+  TAccountMint extends string,
+  TAccountBridge extends string,
+  TAccountTokenProgram extends string,
+  TAccountSystemProgram extends string,
+  TProgramAddress extends Address = typeof BRIDGE_PROGRAM_ADDRESS,
+>(
+  input: SetWrappedTokenUriInput<
+    TAccountPayer,
+    TAccountMint,
+    TAccountBridge,
+    TAccountTokenProgram,
+    TAccountSystemProgram
+  >,
+  config?: { programAddress?: TProgramAddress }
+): SetWrappedTokenUriInstruction<
+  TProgramAddress,
+  TAccountPayer,
+  TAccountMint,
+  TAccountBridge,
+  TAccountTokenProgram,
+  TAccountSystemProgram
+> {
+  // Program address.
+  const programAddress = config?.programAddress ?? BRIDGE_PROGRAM_ADDRESS;
+
+  // Original accounts.
+  const originalAccounts = {
+    payer: { value: input.payer ?? null, isWritable: true },
+    mint: { value: input.mint ?? null, isWritable: true },
+    bridge: { value: input.bridge ?? null, isWritable: false },
+    tokenProgram: { value: input.tokenProgram ?? null, isWritable: false },
+    systemProgram: { value: input.systemProgram ?? null, isWritable: false },
+  };
+  const accounts = originalAccounts as Record<
+    keyof typeof originalAccounts,
+    ResolvedAccount
+  >;
+
+  // Original args.
+  const args = { ...input };
+
+  // Resolve default values.
+  if (!accounts.tokenProgram.value) {
+    accounts.tokenProgram.value =
+      'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' as Address<'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'>;
+  }
+  if (!accounts.systemProgram.value) {
+    accounts.systemProgram.value =
+      '11111111111111111111111111111111' as Address<'11111111111111111111111111111111'>;
+  }
+
+  const getAccountMeta = getAccountMetaFactory(programAddress, 'programId');
+  return Object.freeze({
+    accounts: [
+      getAccountMeta(accounts.payer),
+      getAccountMeta(accounts.mint),
+      getAccountMeta(accounts.bridge),
+      getAccountMeta(accounts.tokenProgram),
+      getAccountMeta(accounts.systemProgram),
+    ],
+    data: getSetWrappedTokenUriInstructionDataEncoder().encode(
+      args as SetWrappedTokenUriInstructionDataArgs
+    ),
+    programAddress,
+  } as SetWrappedTokenUriInstruction<
+    TProgramAddress,
+    TAccountPayer,
+    TAccountMint,
+    TAccountBridge,
+    TAccountTokenProgram,
+    TAccountSystemProgram
+  >);
+}
+
+export type ParsedSetWrappedTokenUriInstruction<
+  TProgram extends string = typeof BRIDGE_PROGRAM_ADDRESS,
+  TAccountMetas extends readonly AccountMeta[] = readonly AccountMeta[],
+> = {
+  programAddress: Address<TProgram>;
+  accounts: {
+    /** The account that pays for the mint account's rent increase. */
+    payer: TAccountMetas[0];
+    /**
+     * The wrapped token mint whose uri is being filled in. Validated to be a wrapped token PDA of
+     * this program by recomputing its metadata hash, which is what makes the mint's own signature
+     * available for the metadata update below.
+     */
+    mint: TAccountMetas[1];
+    /** The main bridge state account, read to honor the pause switch. */
+    bridge: TAccountMetas[2];
+    /** SPL Token-2022 program that owns the mint's metadata extension. */
+    tokenProgram: TAccountMetas[3];
+    /** System program used to top up the mint's rent before its metadata grows. */
+    systemProgram: TAccountMetas[4];
+  };
+  data: SetWrappedTokenUriInstructionData;
+};
+
+export function parseSetWrappedTokenUriInstruction<
+  TProgram extends string,
+  TAccountMetas extends readonly AccountMeta[],
+>(
+  instruction: Instruction<TProgram> &
+    InstructionWithAccounts<TAccountMetas> &
+    InstructionWithData<ReadonlyUint8Array>
+): ParsedSetWrappedTokenUriInstruction<TProgram, TAccountMetas> {
+  if (instruction.accounts.length < 5) {
+    // TODO: Coded error.
+    throw new Error('Not enough accounts');
+  }
+  let accountIndex = 0;
+  const getNextAccount = () => {
+    const accountMeta = (instruction.accounts as TAccountMetas)[accountIndex]!;
+    accountIndex += 1;
+    return accountMeta;
+  };
+  return {
+    programAddress: instruction.programAddress,
+    accounts: {
+      payer: getNextAccount(),
+      mint: getNextAccount(),
+      bridge: getNextAccount(),
+      tokenProgram: getNextAccount(),
+      systemProgram: getNextAccount(),
+    },
+    data: getSetWrappedTokenUriInstructionDataDecoder().decode(
+      instruction.data
+    ),
+  };
+}

clients/ts/src/bridge/generated/instructions/wrapToken.ts

@@ -101,19 +101,9 @@ export type WrapTokenInstructionData = {
   name: string;
   /** The symbol/ticker of the token (e.g., "WBTC") */
   symbol: string;
-  /**
-   * The 20-byte address of the corresponding token contract on Base (EVM address bytes).
-   * This allows the bridge to identify which Base token this Solana token represents.
-   */
+  /** The 20-byte address of the corresponding token contract on Base (EVM address bytes). */
   remoteToken: ReadonlyUint8Array;
-  /**
-   * The scaling exponent used to convert between token amounts on different chains.
-   * This handles cases where tokens have differing decimal precision on Base vs Solana.
-   * For example, when Base token has 18 decimals and the Solana wrapped mint has 9,
-   * this value conveys the decimal relationship so bridging logic can scale amounts.
-   * The exact conversion is performed by the EVM-side contract; Solana propagates this
-   * value but does not apply arithmetic with it.
-   */
+  /** The scaling exponent used to convert between token amounts on different chains. */
   scalerExponent: number;
 };
 
@@ -124,19 +114,9 @@ export type WrapTokenInstructionDataArgs = {
   name: string;
   /** The symbol/ticker of the token (e.g., "WBTC") */
   symbol: string;
-  /**
-   * The 20-byte address of the corresponding token contract on Base (EVM address bytes).
-   * This allows the bridge to identify which Base token this Solana token represents.
-   */
+  /** The 20-byte address of the corresponding token contract on Base (EVM address bytes). */
   remoteToken: ReadonlyUint8Array;
-  /**
-   * The scaling exponent used to convert between token amounts on different chains.
-   * This handles cases where tokens have differing decimal precision on Base vs Solana.
-   * For example, when Base token has 18 decimals and the Solana wrapped mint has 9,
-   * this value conveys the decimal relationship so bridging logic can scale amounts.
-   * The exact conversion is performed by the EVM-side contract; Solana propagates this
-   * value but does not apply arithmetic with it.
-   */
+  /** The scaling exponent used to convert between token amounts on different chains. */
   scalerExponent: number;
 };