Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(pumpfun): add MPL-404 planning helpers
ni3ad2c51e4852fc
diff --git a/packages/pumpfun-skills/README.md b/packages/pumpfun-skills/README.mdindex a89573a04..bed9a1da7 100644--- a/packages/pumpfun-skills/README.md+++ b/packages/pumpfun-skills/README.md@@ -4,7 +4,7 @@<h1 align="center">@three-ws/pumpfun-skills</h1>-<p align="center"><strong>pump.fun launch + trade as composable agent tools: create a coin, swap, and read creator fees, with a runtime-supplied mint.</strong></p>+<p align="center"><strong>pump.fun launch, trade, creator fees, and MPL-404 hybrid planning as composable agent tools.</strong></p><p align="center"><a href="https://www.npmjs.com/package/@three-ws/pumpfun-skills"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/pumpfun-skills?logo=npm&color=cb3837"></a>@@ -54,6 +54,8 @@ the user to sign. These skills collapse that into three calls:`collectFees({...})` builds the claim or distribution transaction.- **Mint supplied at runtime.** Pass any pump.fun mint you control. There is nocoin list, no allowlist: generic plumbing, your inputs.+- **MPL-404-ready.** Turn a Pump.fun mint into the fungible backing side of a+ Metaplex Hybrid V1 project, without pretending Pump.fun itself creates NFTs.This is the SDK twin of the `pumpfun_create_coin`, `pumpfun_swap`, and`pumpfun_collect_fees` MCP/skill tools: same endpoints, plain functions.@@ -128,6 +130,33 @@ the functions below; plus the `AGENT_API_BASE`, `COINS_V2_BASE`, and`FEE_DESTINATIONS` constants and the `ThreeWsError` / `PaymentRequiredError`error classes.+### `createMpl404Plan(input) → Mpl404Plan`++Creates a validated plan for the maintained Metaplex Hybrid program (commonly+called MPL-404/SPL-404). A Pump.fun launch supplies the fungible SPL mint; a+Metaplex **Core** collection supplies the NFT side. The helper never sends a+transaction or holds a secret key. It returns the exact V1 setup parameters for+your wallet-controlled `initEscrowV1`, followed by `captureV1` and `releaseV1`.++```js+import { createMpl404Plan } from '@three-ws/pumpfun-skills';++const plan = createMpl404Plan({+ tokenMint: launch.mint, // Pump.fun mint+ collection: coreCollection,+ authority: wallet.publicKey.toBase58(),+ name: '$THREE relics',+ uri: 'https://ipfs.io/ipfs/Qm…/hybrid.json',+ amount: '1000000', // backing token's smallest units per NFT+});+// Use plan.initEscrowV1 with @metaplex-foundation/mpl-hybrid's V1 instruction.+```++Only Core collections are supported by the upstream hybrid program today;+Token Metadata/pNFT and Token-2022-extension assets must be rejected rather+than silently producing an unusable escrow. Protocol fees are governed by the+deployed program, so confirm the current fee in the wallet flow before signing.+### `createCoin(input) → Promise<BuiltTx & { mint: string }>`Build a new-coin transaction with an optional initial buy. The mint keypair isdiff --git a/packages/pumpfun-skills/package.json b/packages/pumpfun-skills/package.jsonindex 00a026d33..9820ba916 100644--- a/packages/pumpfun-skills/package.json+++ b/packages/pumpfun-skills/package.json@@ -1,6 +1,6 @@{"name": "@three-ws/pumpfun-skills",- "version": "0.1.2",+ "version": "0.1.3","description": "pump.fun launch + trade skills as composable agent tools. Create a coin, swap on the bonding curve or AMM, and read creator fees, with a runtime-supplied mint.","type": "module","main": "./src/index.js",diff --git a/packages/pumpfun-skills/src/index.d.ts b/packages/pumpfun-skills/src/index.d.tsindex a45f8be48..9e3ae8e12 100644--- a/packages/pumpfun-skills/src/index.d.ts+++ b/packages/pumpfun-skills/src/index.d.ts@@ -18,6 +18,11 @@ export declare const AGENT_API_BASE: string;export declare const COINS_V2_BASE: string;export declare const NATIVE_MINT: string;export declare const FEE_DESTINATIONS: FeeDestination[];+/** Metaplex's maintained MPL-404 / hybrid swap program. */+export declare const MPL_HYBRID_PROGRAM_ID: string;+export declare const MPL_HYBRID_INSTRUCTION_VERSION: 'V1';+export declare const MPL_HYBRID_ASSET_STANDARD: 'metaplex-core';+export declare const MPL_HYBRID_DOCS_URL: string;export type FeeDestination = 'creator' | 'cashback' | 'sharing_config';export type SharingConfigMode = 'create' | 'update';@@ -160,6 +165,45 @@ export interface PumpfunSkillsClient {coinFees(mint: string, opts?: ReadOptions): Promise<FeeInfo>;}+export interface Mpl404PlanInput {+ /** The Pump.fun (or another SPL Token) mint that backs each hybrid asset. */+ tokenMint: string;+ /** Metaplex Core collection address. Token Metadata/pNFT collections are not supported by MPL-Hybrid. */+ collection: string;+ /** Wallet that administers the V1 escrow. */+ authority: string;+ /** Fee recipient; defaults to authority. */+ feeLocation?: string;+ name: string;+ uri: string;+ /** Smallest fungible units required to release one Core NFT. */+ amount: string | number | bigint;+ min?: string | number | bigint;+ max?: string | number | bigint;+ feeAmount?: string | number | bigint;+ solFeeAmount?: string | number | bigint;+ path?: number;+}++export interface Mpl404Plan {+ standard: 'mpl-404';+ instructionVersion: 'V1';+ programId: string;+ assetStandard: 'metaplex-core';+ backing: { kind: 'spl-fungible-token'; mint: string };+ collection: string;+ authority: string;+ feeLocation: string;+ initEscrowV1: Record<string, string | number>;+ feeNotice: string;+ docsUrl: string;+ requiredTransactions: ['initEscrowV1', 'captureV1', 'releaseV1'];+}++/** Create a validated, user-signed V1 MPL-404 escrow plan for a Pump.fun mint. */+export declare function createMpl404Plan(input: Mpl404PlanInput): Mpl404Plan;+export declare function isMpl404Compatible(input: { tokenMint?: string; assetStandard?: string }): boolean;+export declare function createPumpfunSkills(options?: PumpfunSkillsOptions): PumpfunSkillsClient;export declare function createCoin(input: CreateCoinInput, opts?: RequestOptions): Promise<CreateCoinResult>;export declare function swap(input: SwapInput, opts?: RequestOptions): Promise<BuiltTx>;diff --git a/packages/pumpfun-skills/src/index.js b/packages/pumpfun-skills/src/index.jsindex 92ebc0d21..31c9d6d87 100644--- a/packages/pumpfun-skills/src/index.js+++ b/packages/pumpfun-skills/src/index.js@@ -7,6 +7,15 @@import { createHttp, ThreeWsError } from './http.js';+export {+ MPL_HYBRID_PROGRAM_ID,+ MPL_HYBRID_INSTRUCTION_VERSION,+ MPL_HYBRID_ASSET_STANDARD,+ MPL_HYBRID_DOCS_URL,+ createMpl404Plan,+ isMpl404Compatible,+} from './mpl404.js';+export { ThreeWsError, PaymentRequiredError, DEFAULT_BASE_URL } from './http.js';/** pump.fun's agent transaction API: builds the unsigned/mint-signed tx. */diff --git a/packages/pumpfun-skills/src/mpl404.js b/packages/pumpfun-skills/src/mpl404.jsnew file mode 100644index 000000000..bad7aa718--- /dev/null+++ b/packages/pumpfun-skills/src/mpl404.js@@ -0,0 +1,103 @@+// MPL-404 (often called SPL-404) planning helpers for Pump.fun mints.+//+// Pump.fun creates the fungible side of a hybrid. The maintained hybrid+// program then escrows that SPL mint against Metaplex Core NFTs. It is not a+// different Pump.fun launch mode and must never be represented as one: a+// project needs both a real SPL mint and a Core collection before it can swap.++export const MPL_HYBRID_PROGRAM_ID = 'MPL4o4wMzndgh8T1NVDxELQCj5UQfYTYEkabX3wNKtb';+export const MPL_HYBRID_INSTRUCTION_VERSION = 'V1';+export const MPL_HYBRID_ASSET_STANDARD = 'metaplex-core';+export const MPL_HYBRID_DOCS_URL = 'https://www.metaplex.com/docs/smart-contracts/mpl-hybrid';++const PUBKEY = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;++function inputError(message) {+ const err = new Error(message);+ err.code = 'invalid_hybrid_input';+ return err;+}++function publicKey(value, label) {+ if (typeof value !== 'string' || !PUBKEY.test(value)) {+ throw inputError(`${label} must be a base58 Solana public key`);+ }+ return value;+}++function uint(value, label, { min = 0n, max = (1n << 64n) - 1n } = {}) {+ let parsed;+ try {+ parsed = typeof value === 'bigint' ? value : BigInt(value);+ } catch {+ throw inputError(`${label} must be an unsigned integer`);+ }+ if (parsed < min || parsed > max) throw inputError(`${label} is out of range`);+ return parsed;+}++/**+ * Validate and describe the V1 MPL-Hybrid setup that makes a Pump.fun mint a+ * hybrid backing token. This function deliberately does not broadcast or+ * custody a key: callers use the returned values to build the upstream V1+ * `initEscrowV1` transaction with their own wallet signer.+ *+ * `amount` is the number of smallest fungible units required to release one+ * Core asset. `min` and `max` are passed through to the upstream V1 escrow+ * instruction and are constrained around that amount to avoid an accidental,+ * surprising exchange configuration.+ */+export function createMpl404Plan(input = {}) {+ const tokenMint = publicKey(input.tokenMint, 'tokenMint');+ const collection = publicKey(input.collection, 'collection');+ const authority = publicKey(input.authority, 'authority');+ const feeLocation = publicKey(input.feeLocation || authority, 'feeLocation');+ const amount = uint(input.amount, 'amount', { min: 1n });+ const min = uint(input.min ?? amount, 'min');+ const max = uint(input.max ?? amount, 'max');+ const feeAmount = uint(input.feeAmount ?? 0, 'feeAmount');+ const solFeeAmount = uint(input.solFeeAmount ?? 0, 'solFeeAmount');+ const path = uint(input.path ?? 0, 'path', { max: 65535n });+ const name = String(input.name || '').trim();+ const uri = String(input.uri || '').trim();++ if (!name || name.length > 32) throw inputError('name must be 1-32 characters');+ if (!/^https?:\/\//.test(uri) || uri.length > 200) {+ throw inputError('uri must be an https metadata URL no longer than 200 characters');+ }+ if (min > amount || amount > max) {+ throw inputError('min <= amount <= max is required for a predictable swap ratio');+ }++ return Object.freeze({+ standard: 'mpl-404',+ instructionVersion: MPL_HYBRID_INSTRUCTION_VERSION,+ programId: MPL_HYBRID_PROGRAM_ID,+ assetStandard: MPL_HYBRID_ASSET_STANDARD,+ backing: { kind: 'spl-fungible-token', mint: tokenMint },+ collection,+ authority,+ feeLocation,+ initEscrowV1: {+ name,+ uri,+ max: max.toString(),+ min: min.toString(),+ amount: amount.toString(),+ feeAmount: feeAmount.toString(),+ solFeeAmount: solFeeAmount.toString(),+ path: Number(path),+ },+ // Swap protocol fees are controlled by the deployed program. Do not bake a+ // stale fee number into a product quote; fetch/confirm it at signing time.+ feeNotice: 'MPL-Hybrid protocol fees may apply. Confirm the current fee before signing.',+ docsUrl: MPL_HYBRID_DOCS_URL,+ requiredTransactions: ['initEscrowV1', 'captureV1', 'releaseV1'],+ });+}++/** True only for the supported, production-compatible pairing. */+export function isMpl404Compatible(input = {}) {+ return input.assetStandard === MPL_HYBRID_ASSET_STANDARD &&+ typeof input.tokenMint === 'string' && PUBKEY.test(input.tokenMint);+}diff --git a/packages/pumpfun-skills/test/pumpfun-skills.test.js b/packages/pumpfun-skills/test/pumpfun-skills.test.jsindex b4471f974..83fbd4fd5 100644--- a/packages/pumpfun-skills/test/pumpfun-skills.test.js+++ b/packages/pumpfun-skills/test/pumpfun-skills.test.js@@ -5,6 +5,9 @@ import {NATIVE_MINT,ThreeWsError,PaymentRequiredError,+ createMpl404Plan,+ isMpl404Compatible,+ MPL_HYBRID_PROGRAM_ID,} from '../src/index.js';// $THREE is the only coin. Tests use the real $THREE mint or a clearly-synthetic@@ -13,6 +16,35 @@ const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';const SYNTH_MINT = 'THREEsynthetic1111111111111111111111111111';const WALLET = 'YourWa11et1111111111111111111111111111111111';+test('createMpl404Plan() makes Pump.fun the SPL backing asset, not a fake launch mode', () => {+ const plan = createMpl404Plan({+ tokenMint: THREE_MINT,+ collection: 'Co11ection111111111111111111111111111111111',+ authority: WALLET,+ name: 'THREE relics',+ uri: 'https://example.com/relics.json',+ amount: '1000000',+ });+ assert.equal(plan.programId, MPL_HYBRID_PROGRAM_ID);+ assert.equal(plan.assetStandard, 'metaplex-core');+ assert.equal(plan.backing.mint, THREE_MINT);+ assert.deepEqual(plan.requiredTransactions, ['initEscrowV1', 'captureV1', 'releaseV1']);+ assert.equal(plan.initEscrowV1.amount, '1000000');+ assert.equal(isMpl404Compatible({ tokenMint: THREE_MINT, assetStandard: 'metaplex-core' }), true);+});++test('createMpl404Plan() rejects an unsafe or inverted swap ratio', () => {+ assert.throws(() => createMpl404Plan({+ tokenMint: THREE_MINT, collection: 'bad', authority: WALLET,+ name: 'x', uri: 'https://example.com/x.json', amount: '1',+ }), /collection must be a base58/);+ assert.throws(() => createMpl404Plan({+ tokenMint: THREE_MINT,+ collection: 'Co11ection111111111111111111111111111111111', authority: WALLET,+ name: 'x', uri: 'https://example.com/x.json', min: '2', amount: '1', max: '3',+ }), /min <= amount <= max/);+});+// A scripted fetch double: each call shifts the next queued response and records// the request. No network, no real endpoints, we assert on request shaping and// response parsing, which is all the SDK is responsible for.