Point new mint uris at the gateway skill route; readers extract the sig

New skill/workflow mints write uri = {gateway}/skill/{mint}/{sig} so external
viewers (marketplaces, explorers, wallets) can resolve standard NFT JSON and
a card image over HTTP. The code-in txid stays recoverable on-chain: it is
the uri's last path segment, and every reader now funnels through
inscriptionSigOf() to extract it before readCodeIn — the gateway attempt and
the RPC fallback both receive the bare sig, never the URL. Legacy bare-sig
uris keep working through the same parse (the two existing mainnet mints
migrate separately).

Author: zo-sol

packages/core/src/core/chain.spec.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { Connection, PublicKey, Keypair } from "@solana/web3.js";
-import { init, ensureDbRoot, createTable, writeRow, codeIn, signerAddress, tableExists, readCodeIn, readRows } from "./chain.js";
+import { init, ensureDbRoot, createTable, writeRow, codeIn, signerAddress, tableExists, readCodeIn, readRows, inscriptionSigOf, itemMetadataUri } from "./chain.js";
 import { readCodeIn as sdkReadCodeIn, readTableRows as sdkReadTableRows } from "@iqlabs-official/solana-sdk/reader";
 
 // Mock the solana-sdk modules
@@ -161,4 +161,35 @@ describe("core/chain", () => {
       vi.unstubAllGlobals();
     });
   });
+
+  describe("inscriptionSigOf / itemMetadataUri", () => {
+    const SIG = "4K3z7cWH8QAxd74tK4ErtNv8ZL1k97yrAsm7SQJg4zPRya7DnbsxtmZwEgza4H34Z6QX9ewjqpmospXe3KQahruh";
+    const MINT = "Es18ADJ4ZpKDojLtvNJEBGCaXpqxsmw2kG8ihS6TJC7U";
+
+    it("passes a legacy bare signature through", () => {
+      expect(inscriptionSigOf(SIG)).toBe(SIG);
+    });
+
+    it("extracts the sig from a gateway skill URL (last segment)", () => {
+      expect(inscriptionSigOf(`https://gateway.iqlabs.dev/skill/${MINT}/${SIG}`)).toBe(SIG);
+    });
+
+    it("tolerates .png suffix, trailing slash and query", () => {
+      expect(inscriptionSigOf(`https://gateway.iqlabs.dev/skill/${MINT}/${SIG}.png`)).toBe(SIG);
+      expect(inscriptionSigOf(`https://gateway.iqlabs.dev/skill/${MINT}/${SIG}/`)).toBe(SIG);
+      expect(inscriptionSigOf(`https://gateway.iqlabs.dev/skill/${MINT}/${SIG}?v=1`)).toBe(SIG);
+    });
+
+    it("rejects things that carry no signature", () => {
+      expect(inscriptionSigOf("txid123")).toBeNull(); // too short
+      expect(inscriptionSigOf(`https://gateway.iqlabs.dev/skill/${MINT}`)).toBeNull(); // mint tail, not a sig
+      expect(inscriptionSigOf("")).toBeNull();
+    });
+
+    it("itemMetadataUri builds a URL whose tail round-trips through inscriptionSigOf", () => {
+      const uri = itemMetadataUri(MINT, SIG);
+      expect(uri.endsWith(`/skill/${MINT}/${SIG}`)).toBe(true);
+      expect(inscriptionSigOf(uri)).toBe(SIG);
+    });
+  });
 });

packages/core/src/core/chain.ts

@@ -323,6 +323,31 @@ export async function codeIn(
   );
 }
 
+// A mint uri carries the inscription signature in one of two shapes: legacy
+// uris are the bare tx signature; current uris are the gateway presentation
+// URL "{gateway}/skill/{mint}/{sig}" (marketplace-readable JSON+image) whose
+// LAST path segment is the signature (the same tail convention iq-wide-web
+// uses for SOL records). Every on-chain read extracts the sig and resolves
+// content through readCodeIn, so the app never depends on the HTTP route.
+const SIG_SHAPE = /^[1-9A-HJ-NP-Za-km-z]{80,90}$/;
+
+export function inscriptionSigOf(uri: string): string | null {
+  if (SIG_SHAPE.test(uri)) return uri;
+  if (/^https?:\/\//.test(uri)) {
+    const tail = uri.split(/[?#]/, 1)[0].replace(/\/+$/, "").split("/").pop() ?? "";
+    const sig = tail.replace(/\.(png|json)$/, "");
+    if (SIG_SHAPE.test(sig)) return sig;
+  }
+  return null;
+}
+
+/** The uri written onto a new item mint: the gateway route that serves
+ *  standard NFT JSON (+ card image) for external viewers. Network-matched via
+ *  gatewayUrl(); both identifiers are known before the mint tx is signed. */
+export function itemMetadataUri(mint: string, sig: string): string {
+  return `${gatewayUrl()}/skill/${mint}/${sig}`;
+}
+
 // Read a code-in inscription by its tx signature. Tries the gateway's cached
 // `/data/{sig}` first (network-matched via getGatewayUrl — the mainnet gateway
 // can't resolve a devnet tx, so the URL must follow the network); on any failure

packages/core/src/nft/readSkillText.spec.ts

@@ -4,10 +4,12 @@ import * as chain from "../core/chain.js";
 import * as splToken from "@solana/spl-token";
 
 // readSkillText joins readSkillMintMetadata (getTokenMetadata) → readCodeIn.
-vi.mock("../core/chain.js", () => ({
-  signerAddress: vi.fn(),
-  readCodeIn: vi.fn(),
-}));
+// Keep the real inscriptionSigOf: the uri→sig extraction IS part of the path
+// under test (legacy bare-sig uris and gateway-URL uris must both resolve).
+vi.mock("../core/chain.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../core/chain.js")>();
+  return { ...actual, signerAddress: vi.fn(), readCodeIn: vi.fn() };
+});
 
 vi.mock("./minter.js", () => ({
   resolveMinter: vi.fn(),
@@ -20,33 +22,63 @@ vi.mock("@solana/spl-token", async (importOriginal) => {
 });
 
 const MINT = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPvZeJ";
+// A realistically-shaped inscription signature (64 raw bytes → 87-88 base58).
+const TXID = "4K3z7cWH8QAxd74tK4ErtNv8ZL1k97yrAsm7SQJg4zPRya7DnbsxtmZwEgza4H34Z6QX9ewjqpmospXe3KQahruh";
+
+const SKILL_JSON = JSON.stringify({
+  name: "my-skill",
+  description: "d",
+  attributes: [{ trait_type: "category", value: "ai" }],
+  skillText: "# SKILL body text",
+});
 
 describe("nft/readSkillText", () => {
   beforeEach(() => vi.clearAllMocks());
 
-  it("resolves mint → uri (txid) → skillText in the code-in JSON", async () => {
+  it("resolves mint → legacy bare-sig uri → skillText in the code-in JSON", async () => {
     vi.mocked(splToken.getTokenMetadata).mockResolvedValue({
       name: "my-skill",
       symbol: "MY",
-      uri: "txid123",
+      uri: TXID,
       additionalMetadata: [],
     } as any);
     // The inscription is the standard NFT JSON; the body is its skillText field.
-    vi.mocked(chain.readCodeIn).mockResolvedValue({
-      data: JSON.stringify({
-        name: "my-skill",
-        description: "d",
-        attributes: [{ trait_type: "category", value: "ai" }],
-        skillText: "# SKILL body text",
-      }),
-      metadata: "",
-    });
+    vi.mocked(chain.readCodeIn).mockResolvedValue({ data: SKILL_JSON, metadata: "" });
 
     const text = await readSkillText({} as any, MINT);
 
     expect(text).toBe("# SKILL body text");
-    // the uri recovered from the mint is what readCodeIn is asked for
-    expect(chain.readCodeIn).toHaveBeenCalledWith("txid123");
+    // the sig recovered from the mint uri is what readCodeIn is asked for
+    expect(chain.readCodeIn).toHaveBeenCalledWith(TXID);
+  });
+
+  it("resolves a gateway-URL uri by extracting the sig from its last segment", async () => {
+    vi.mocked(splToken.getTokenMetadata).mockResolvedValue({
+      name: "my-skill",
+      symbol: "MY",
+      uri: `https://gateway.iqlabs.dev/skill/${MINT}/${TXID}`,
+      additionalMetadata: [],
+    } as any);
+    vi.mocked(chain.readCodeIn).mockResolvedValue({ data: SKILL_JSON, metadata: "" });
+
+    const text = await readSkillText({} as any, MINT);
+
+    expect(text).toBe("# SKILL body text");
+    expect(chain.readCodeIn).toHaveBeenCalledWith(TXID);
+  });
+
+  it("returns null (no on-chain read) when the uri carries no recognisable sig", async () => {
+    vi.mocked(splToken.getTokenMetadata).mockResolvedValue({
+      name: "my-skill",
+      symbol: "MY",
+      uri: "txid123",
+      additionalMetadata: [],
+    } as any);
+
+    const text = await readSkillText({} as any, MINT);
+
+    expect(text).toBeNull();
+    expect(chain.readCodeIn).not.toHaveBeenCalled();
   });
 
   it("returns null when the mint has no metadata", async () => {

packages/core/src/nft/skill.spec.ts

@@ -11,6 +11,7 @@ vi.mock("../core/chain.js", () => ({
   signerAddress: vi.fn().mockImplementation((signer) =>
     Promise.resolve(signer.publicKey?.toBase58() || "11111111111111111111111111111111"),
   ),
+  itemMetadataUri: vi.fn((mint: string, sig: string) => `https://gateway.test/skill/${mint}/${sig}`),
 }));
 
 vi.mock("../core/seed.js", () => ({

packages/core/src/nft/skill.ts

@@ -22,7 +22,7 @@ import {
   DIRECT_METADATA_MAX_BYTES,
 } from "@iqlabs-official/solana-sdk/constants";
 import { getUserInventoryPda, PROGRAM_ID as CODE_IN_PROGRAM_ID } from "@iqlabs-official/solana-sdk/contract";
-import { codeIn, signerAddress, ensureDbRoot, dbRootExists } from "../core/chain.js";
+import { codeIn, signerAddress, ensureDbRoot, dbRootExists, itemMetadataUri } from "../core/chain.js";
 import { getSkillsCollectionMint } from "../core/seed.js";
 import { createSkillMint } from "./token2022.js";
 import { checkFormat, FormatError } from "./checkFormat.js";
@@ -245,7 +245,9 @@ export async function publishSkill(
   await createSkillMint(conn, tx, {
     name: input.name,
     symbol: input.name.substring(0, 8).toUpperCase(),
-    uri: skillTxid, // points at the JSON above (traits live there, not on the mint)
+    // Gateway presentation URL (marketplaces resolve it for JSON+image); its
+    // last segment is the code-in txid, which on-chain readers extract.
+    uri: itemMetadataUri(skillMint.toBase58(), skillTxid),
     collectionMint,
     mintKeypair: skillMintKp,
     minterAuthority: mintAuthority, // gate PDA holds the mint authority

packages/core/src/nft/token2022.ts

@@ -31,7 +31,7 @@ import {
   type TokenMetadata,
 } from "@solana/spl-token-metadata";
 import { type SignerInput, type WalletSigner } from "@iqlabs-official/solana-sdk/utils";
-import { signerAddress, readCodeIn } from "../core/chain.js";
+import { signerAddress, readCodeIn, inscriptionSigOf } from "../core/chain.js";
 import { resolveMinter, tryMinterPubkey } from "./minter.js";
 
 import { TOKEN_2022_PROGRAM_ID } from "@solana/spl-token";
@@ -290,9 +290,11 @@ export async function readSkillMintMetadata(
 
   const base: SkillMintMetadata = { name: md.name, symbol: md.symbol, uri: md.uri };
   if (!md.uri) return base;
+  const sig = inscriptionSigOf(md.uri);
+  if (!sig) return base; // uri carries no inscription signature we recognise
 
   try {
-    const { data } = await readCodeIn(md.uri);
+    const { data } = await readCodeIn(sig);
     if (!data) return base;
     const json = JSON.parse(data) as SkillJson;
     const { category, hashtags } = traitsFromAttributes(json.attributes);

packages/core/src/nft/workflow.spec.ts

@@ -11,6 +11,7 @@ vi.mock("../core/chain.js", () => ({
   signerAddress: vi.fn().mockImplementation((signer) =>
     Promise.resolve(signer.publicKey?.toBase58() || "11111111111111111111111111111111"),
   ),
+  itemMetadataUri: vi.fn((mint: string, sig: string) => `https://gateway.test/skill/${mint}/${sig}`),
 }));
 
 vi.mock("../core/seed.js", () => ({

packages/core/src/nft/workflow.ts

@@ -12,7 +12,7 @@ import {
 } from "@solana/spl-token";
 import type { SignerInput } from "@iqlabs-official/solana-sdk/utils";
 
-import { codeIn, signerAddress, ensureDbRoot } from "../core/chain.js";
+import { codeIn, signerAddress, ensureDbRoot, itemMetadataUri } from "../core/chain.js";
 import { getWorkflowsCollectionMint } from "../core/seed.js";
 import { trackSignatures, estimatePublishSigns, type PublishProgress } from "./skill.js";
 import { createSkillMint } from "./token2022.js";
@@ -105,7 +105,9 @@ export async function publishWorkflow(
   await createSkillMint(conn, tx, {
     name: input.name,
     symbol: input.name.substring(0, 8).toUpperCase(),
-    uri: workflowTxid, // points at the JSON above (traits live there, not on the mint)
+    // Gateway presentation URL (marketplaces resolve it for JSON+image); its
+    // last segment is the code-in txid, which on-chain readers extract.
+    uri: itemMetadataUri(workflowMint.toBase58(), workflowTxid),
     collectionMint,
     mintKeypair: workflowMintKp,
     minterAuthority: mintAuthority, // gate PDA holds the mint authority