@stellar-agent-kit/plugin-asset 0.1.9 → 0.1.10

package/dist/index.d.ts

@@ -36,6 +36,47 @@ declare const getOrderbook: Action;
 
 declare const friendbotFund: Action;
 
+declare const knownIssuers: Action;
+
+/**
+ * Verified-canonical asset issuers per network. Use this to avoid LLM
+ * hallucination of issuer addresses when the user says "trustline USDC" without
+ * specifying which one.
+ *
+ * Sources (verified 2026-05-08):
+ * - USDC mainnet: Circle's official issuer (https://stellar.expert/explorer/public/asset/USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN)
+ * - USDC testnet: Circle's testnet issuer (https://stellar.expert/explorer/testnet/asset/USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5)
+ * - EURC mainnet: Circle's official EURC issuer
+ * - AQUA mainnet: Aquarius DEX governance token
+ * - yXLM, yUSDC mainnet: Ultracapital yield assets
+ *
+ * NOTE: testnet has MULTIPLE USDC issuers (Circle, Blend, Etherfuse). We
+ * default to Circle's. To use a different one, callers must pass the issuer
+ * explicitly to ASSET_TRUSTLINE_ADD.
+ */
+interface KnownAssetEntry {
+    code: string;
+    issuer: string;
+    /** Stellar Asset Contract address — for Soroswap / Soroban interactions. */
+    sac?: string;
+    description?: string;
+}
+declare const KNOWN_ASSETS_MAINNET: Record<string, KnownAssetEntry>;
+declare const KNOWN_ASSETS_TESTNET: Record<string, KnownAssetEntry>;
+type StellarNetworkTag = "mainnet" | "testnet" | "futurenet";
+declare function networkTag(passphrase: string): StellarNetworkTag;
+/**
+ * Look up a known asset by code on the current network. Returns null if the
+ * code isn't in the registry. Codes are matched case-insensitively but the
+ * registry's canonical casing wins.
+ */
+declare function lookupKnownAsset(passphrase: string, code: string): KnownAssetEntry | null;
+/**
+ * Render a compact summary of known assets for inclusion in the agent's
+ * system prompt. Helps the LLM pick the right issuer without guessing.
+ */
+declare function describeKnownAssets(passphrase: string): string;
+
 declare const StellarAssetPlugin: Plugin;
 
-export { StellarAssetPlugin, balance, cancelOffer, claimableBalanceClaim, claimableBalanceCreate, StellarAssetPlugin as default, friendbotFund, getOrderbook, issue, manageBuyOffer, manageSellOffer, pathPaymentStrictReceive, pathPaymentStrictSend, setOptions, transfer, trustlineAdd, trustlineRemove };
+export { KNOWN_ASSETS_MAINNET, KNOWN_ASSETS_TESTNET, type KnownAssetEntry, StellarAssetPlugin, type StellarNetworkTag, balance, cancelOffer, claimableBalanceClaim, claimableBalanceCreate, StellarAssetPlugin as default, describeKnownAssets, friendbotFund, getOrderbook, issue, knownIssuers, lookupKnownAsset, manageBuyOffer, manageSellOffer, networkTag, pathPaymentStrictReceive, pathPaymentStrictSend, setOptions, transfer, trustlineAdd, trustlineRemove };

package/dist/index.js

@@ -217,56 +217,158 @@ var pathPaymentStrictReceive = {
 // src/actions/trustline.ts
 import { z as z4 } from "zod";
 import { Operation as Operation5 } from "@stellar/stellar-sdk";
+
+// src/knownAssets.ts
+import { Networks } from "@stellar/stellar-sdk";
+var KNOWN_ASSETS_MAINNET = {
+  XLM: {
+    code: "XLM",
+    issuer: "native",
+    sac: "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
+    description: "Native Stellar lumens. No trustline needed."
+  },
+  USDC: {
+    code: "USDC",
+    issuer: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
+    sac: "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",
+    description: "Circle's official mainnet USDC."
+  },
+  EURC: {
+    code: "EURC",
+    issuer: "GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2",
+    sac: "CDTKPWPLOURQA2SGTKTUQOWRCBZEORB4BWBOMJ3D3ZTQQSGE5F6JBQLV",
+    description: "Circle's official mainnet EURC."
+  },
+  AQUA: {
+    code: "AQUA",
+    issuer: "GBNZILSTVQZ4R7IKQDGHYGY2QXL5QOFJYQMXPKWRRM5PAV7Y4M67AQUA",
+    sac: "CAUIKL3IYGMERDRUN6YSCLWVAKIFG5Q4YJHUKM4S4NJZQIA3BAS6OJPK",
+    description: "Aquarius DEX governance token."
+  },
+  YXLM: {
+    code: "yXLM",
+    issuer: "GARDNV3Q7YGT4AKSDF25LT32YSCCW4EV22Y2TV3I2PU2MMXJTEDL5T55",
+    description: "Ultracapital yield XLM."
+  },
+  YUSDC: {
+    code: "yUSDC",
+    issuer: "GDGTVWSM4MGS4T7Z6W4RPWOCHE2I6RDFCIFZGS3DOA63LWQTRNZNTTFF",
+    sac: "CDOFW7HNKLUZRLFZST4EW7V3AV4JI5IHMT6BPXXSY2IEFZ4NE5TWU2P4",
+    description: "Ultracapital yield USDC."
+  }
+};
+var KNOWN_ASSETS_TESTNET = {
+  XLM: {
+    code: "XLM",
+    issuer: "native",
+    description: "Native Stellar lumens (testnet). No trustline needed."
+  },
+  USDC: {
+    code: "USDC",
+    issuer: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
+    description: "Circle's testnet USDC. NOTE: testnet has multiple USDC issuers (Circle / Blend / Etherfuse) that don't share liquidity \u2014 pass an explicit issuer to use a different one."
+  }
+};
+function networkTag(passphrase) {
+  if (passphrase === Networks.PUBLIC) return "mainnet";
+  if (passphrase === Networks.FUTURENET) return "futurenet";
+  return "testnet";
+}
+function lookupKnownAsset(passphrase, code) {
+  const network = networkTag(passphrase);
+  const reg = network === "mainnet" ? KNOWN_ASSETS_MAINNET : KNOWN_ASSETS_TESTNET;
+  const upper = code.toUpperCase();
+  return reg[code] ?? reg[upper] ?? null;
+}
+function describeKnownAssets(passphrase) {
+  const network = networkTag(passphrase);
+  const reg = network === "mainnet" ? KNOWN_ASSETS_MAINNET : KNOWN_ASSETS_TESTNET;
+  const lines = [`Known canonical assets on ${network}:`];
+  for (const entry of Object.values(reg)) {
+    if (entry.issuer === "native") {
+      lines.push(`  - ${entry.code} (native, no trustline needed)`);
+    } else {
+      lines.push(
+        `  - ${entry.code}: issuer=${entry.issuer}${entry.sac ? `, SAC=${entry.sac}` : ""}`
+      );
+    }
+  }
+  if (network === "testnet") {
+    lines.push(
+      "  Note: testnet has multiple USDC issuers (Circle / Blend / Etherfuse) that DON'T share liquidity."
+    );
+  }
+  return lines.join("\n");
+}
+
+// src/actions/trustline.ts
 var trustlineAdd = {
   name: "ASSET_TRUSTLINE_ADD",
   similes: ["change trust", "add trustline", "trust asset"],
-  description: "Establish or update a trustline from the agent's wallet for a non-native Stellar asset.",
+  description: "Establish or update a trustline from the agent's wallet for a non-native Stellar asset. If `issuer` is omitted, the kit auto-resolves it from a verified canonical-asset registry (USDC, EURC, AQUA, etc. \u2014 see ASSET_KNOWN_ISSUERS). On testnet there are multiple USDC issuers (Circle / Blend / Etherfuse); the auto-resolver picks Circle's. To use a different one, pass `issuer` explicitly.",
   examples: [
     [
       {
-        input: { assetCode: "USDC", issuer: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN" },
-        output: { hash: "...", ledger: 1 },
-        explanation: "Trustline USDC at default limit"
+        input: { assetCode: "USDC" },
+        output: { hash: "...", ledger: 1, resolvedIssuer: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN" },
+        explanation: "Trustline mainnet Circle USDC (issuer auto-resolved)"
       }
     ]
   ],
   schema: z4.object({
     assetCode: z4.string(),
-    issuer: z4.string(),
+    issuer: z4.string().optional().describe(
+      "Issuer G-address. If omitted, auto-resolved from the canonical-asset registry for the active network."
+    ),
     limit: z4.string().optional().describe("Trust limit (omit for max). String decimal, e.g. 1000000")
   }),
   handler: async (agent, input) => {
-    const asset = makeAsset({ code: input.assetCode, issuer: input.issuer });
+    const issuer = await resolveIssuer(agent, input.assetCode, input.issuer);
+    const asset = makeAsset({ code: input.assetCode, issuer });
     const { hash, ledger } = await buildSubmitClassic(
       agent,
       (b) => b.addOperation(Operation5.changeTrust({ asset, ...input.limit ? { limit: input.limit } : {} }))
     );
-    return { hash, ledger };
+    return { hash, ledger, resolvedIssuer: issuer };
   }
 };
 var trustlineRemove = {
   name: "ASSET_TRUSTLINE_REMOVE",
   similes: ["remove trustline", "untrust asset"],
-  description: "Remove a trustline by setting its limit to 0. The agent's balance for that asset must already be 0.",
+  description: "Remove a trustline by setting its limit to 0. The agent's balance for that asset must already be 0. Issuer is auto-resolved if omitted (see ASSET_TRUSTLINE_ADD).",
   examples: [
     [
       {
-        input: { assetCode: "USDC", issuer: "GA..." },
+        input: { assetCode: "USDC" },
         output: { hash: "...", ledger: 1 },
-        explanation: "Remove a USDC trustline"
+        explanation: "Remove a USDC trustline (issuer auto-resolved)"
       }
     ]
   ],
-  schema: z4.object({ assetCode: z4.string(), issuer: z4.string() }),
+  schema: z4.object({
+    assetCode: z4.string(),
+    issuer: z4.string().optional()
+  }),
   handler: async (agent, input) => {
-    const asset = makeAsset({ code: input.assetCode, issuer: input.issuer });
+    const issuer = await resolveIssuer(agent, input.assetCode, input.issuer);
+    const asset = makeAsset({ code: input.assetCode, issuer });
     const { hash, ledger } = await buildSubmitClassic(
       agent,
       (b) => b.addOperation(Operation5.changeTrust({ asset, limit: "0" }))
     );
-    return { hash, ledger };
+    return { hash, ledger, resolvedIssuer: issuer };
   }
 };
+async function resolveIssuer(agent, assetCode, explicit) {
+  if (explicit) return explicit;
+  const known = lookupKnownAsset(agent.config.networkPassphrase, assetCode);
+  if (known && known.issuer && known.issuer !== "native") return known.issuer;
+  const err = new Error(
+    `Asset ${assetCode} is not in the canonical-asset registry for this network. Pass \`issuer\` explicitly, or use ASSET_KNOWN_ISSUERS to see what's available.`
+  );
+  err.code = "ISSUER_REQUIRED";
+  throw err;
+}
 
 // src/actions/balance.ts
 import { z as z5 } from "zod";
@@ -652,7 +754,7 @@ var getOrderbook = {
 
 // src/actions/friendbot.ts
 import { z as z11 } from "zod";
-import { Networks } from "@stellar/stellar-sdk";
+import { Networks as Networks2 } from "@stellar/stellar-sdk";
 var friendbotFund = {
   name: "ACCOUNT_FRIENDBOT_FUND",
   similes: ["friendbot", "fund testnet account", "airdrop testnet xlm"],
@@ -671,7 +773,7 @@ var friendbotFund = {
   }),
   handler: async (agent, input) => {
     const account = input.account ?? agent.wallet.publicKey;
-    if (agent.config.networkPassphrase === Networks.PUBLIC) {
+    if (agent.config.networkPassphrase === Networks2.PUBLIC) {
       console.warn(
         "[ACCOUNT_FRIENDBOT_FUND] Agent is configured for the public network; Friendbot only funds testnet accounts."
       );
@@ -695,6 +797,55 @@ var friendbotFund = {
   }
 };
 
+// src/actions/knownIssuers.ts
+import { z as z12 } from "zod";
+var knownIssuers = {
+  name: "ASSET_KNOWN_ISSUERS",
+  similes: [
+    "list known issuers",
+    "canonical asset issuers",
+    "which usdc",
+    "verified usdc issuer",
+    "what issuer to use"
+  ],
+  description: "Return the kit's verified canonical-asset registry for the active network. Use this when the user mentions a well-known asset by code (USDC, EURC, AQUA, etc.) and you need the correct issuer G-address to avoid hallucinating one. If `assetCode` is provided, returns just that entry (or null). Otherwise returns the full registry for the network.",
+  examples: [
+    [
+      {
+        input: { assetCode: "USDC" },
+        output: {
+          network: "testnet",
+          asset: {
+            code: "USDC",
+            issuer: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
+            description: "Circle's testnet USDC. NOTE: testnet has multiple USDC issuers..."
+          }
+        },
+        explanation: "Look up Circle USDC on testnet before adding a trustline."
+      }
+    ],
+    [
+      {
+        input: {},
+        output: { network: "mainnet", assets: [{ code: "XLM", issuer: "native" }] },
+        explanation: "List the full registry for the active network."
+      }
+    ]
+  ],
+  schema: z12.object({
+    assetCode: z12.string().optional().describe("Optional: lookup a single asset by code (case-insensitive).")
+  }),
+  handler: async (agent, input) => {
+    const network = networkTag(agent.config.networkPassphrase);
+    if (input.assetCode) {
+      const asset = lookupKnownAsset(agent.config.networkPassphrase, input.assetCode);
+      return { network, asset };
+    }
+    const reg = network === "mainnet" ? KNOWN_ASSETS_MAINNET : KNOWN_ASSETS_TESTNET;
+    return { network, assets: Object.values(reg) };
+  }
+};
+
 // src/index.ts
 var StellarAssetPlugin = {
   name: "stellar-asset",
@@ -714,24 +865,31 @@ var StellarAssetPlugin = {
     manageBuyOffer,
     cancelOffer,
     getOrderbook,
-    friendbotFund
+    friendbotFund,
+    knownIssuers
   ],
   initialize() {
   }
 };
 var index_default = StellarAssetPlugin;
 export {
+  KNOWN_ASSETS_MAINNET,
+  KNOWN_ASSETS_TESTNET,
   StellarAssetPlugin,
   balance,
   cancelOffer,
   claimableBalanceClaim,
   claimableBalanceCreate,
   index_default as default,
+  describeKnownAssets,
   friendbotFund,
   getOrderbook,
   issue,
+  knownIssuers,
+  lookupKnownAsset,
   manageBuyOffer,
   manageSellOffer,
+  networkTag,
   pathPaymentStrictReceive,
   pathPaymentStrictSend,
   setOptions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stellar-agent-kit/plugin-asset",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Classic Stellar asset operations (transfer, path payment, trustline, issuance, claimable balances) as agent actions.",
   "license": "Apache-2.0",
   "type": "module",
@@ -22,13 +22,13 @@
     "zod": "^3.23.8"
   },
   "peerDependencies": {
-    "@stellar-agent-kit/core": "0.1.9"
+    "@stellar-agent-kit/core": "0.1.10"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8",
-    "@stellar-agent-kit/core": "0.1.9"
+    "@stellar-agent-kit/core": "0.1.10"
   },
   "publishConfig": {
     "access": "public"