@forgekit-labs/token 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeKit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @forgekit-labs/token
+
+Mint Solana tokens with authority revocations and burn in one atomic transaction.
+
+## Install
+
+```bash
+npm install @forgekit-labs/token
+```
+
+## Usage
+
+```js
+import { mint } from '@forgekit-labs/token';
+
+const { signature, mintAddress, supply, burned, revoked } = await mint('my-token')
+  .supply(1_000_000_000)
+  .decimals(6)
+  .metadata({ name: 'MY TOKEN', symbol: 'MTK', uri: metadataUri })
+  .burn(2)
+  .revoke('freeze')
+  .revoke('mint')
+  .wallet(keypair.secretKey)
+  .rpc('https://api.mainnet-beta.solana.com')
+  .send();
+```
+
+Everything happens in a single VersionedTransaction (V0): account creation, mint, ATA setup, full-supply mint, burn, and authority revocations. Either it all lands or none of it does.
+
+Authority revocation order is fixed: freeze is always revoked before mint. Reversing the order can leave a token in an inconsistent state.
+
+## Error Handling
+
+```js
+import { mint, ForgeTxError, ForgeRpcError } from '@forgekit-labs/token';
+
+try {
+  await mint('my-token').supply(1_000_000_000).wallet(secretKey).send();
+} catch (err) {
+  if (err instanceof ForgeTxError) {
+    // transaction failed on-chain
+    console.error(err.message, err.cause);
+  }
+  if (err.retry) {
+    // RPC or network issue, safe to retry
+  }
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@forgekit-labs/token",
+  "version": "0.1.0",
+  "description": "Mint Solana tokens with authority revocations and burn in one atomic transaction.",
+  "author": "Res <support@crxcible.io> (https://github.com/solDEv0)",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solDEv0/forgekit.git",
+    "directory": "packages/token"
+  },
+  "homepage": "https://github.com/solDEv0/forgekit/tree/main/packages/token#readme",
+  "bugs": "https://github.com/solDEv0/forgekit/issues",
+  "keywords": [
+    "solana",
+    "token",
+    "mint",
+    "spl",
+    "launchpad"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@forgekit-labs/errors": "^0.1.0",
+    "@solana/web3.js": "^1.98.0",
+    "@solana/spl-token": "^0.4.9"
+  }
+}

package/src/index.js

@@ -0,0 +1,7 @@
+export { mint } from './mint.js';
+export {
+  ForgeError,
+  ForgeValidationError,
+  ForgeTxError,
+  ForgeRpcError,
+} from '@forgekit-labs/errors';

package/src/mint.js

@@ -0,0 +1,259 @@
+import {
+  Connection,
+  Keypair,
+  SystemProgram,
+  TransactionMessage,
+  VersionedTransaction,
+  sendAndConfirmRawTransaction,
+} from '@solana/web3.js';
+import {
+  createInitializeMintInstruction,
+  createAssociatedTokenAccountInstruction,
+  createMintToInstruction,
+  createSetAuthorityInstruction,
+  AuthorityType,
+  getAssociatedTokenAddressSync,
+  getMinimumBalanceForRentExemptMint,
+  MINT_SIZE,
+  TOKEN_PROGRAM_ID,
+} from '@solana/spl-token';
+import { ForgeValidationError, ForgeTxError, ForgeRpcError } from '@forgekit-labs/errors';
+
+const VALID_AUTHORITIES = new Set(['freeze', 'mint']);
+
+class MintBuilder {
+  #name;
+  #supply      = null;
+  #decimals    = 6;
+  #meta        = null;
+  #burnBps     = 0;
+  #revocations = new Set();
+  #secretKey   = null;
+  #rpcUrl      = 'https://api.mainnet-beta.solana.com';
+
+  constructor(name) {
+    if (typeof name !== 'string' || !name.trim()) {
+      throw new ForgeValidationError(
+        'mint() requires a name string.',
+        'Pass a unique identifier, e.g. mint("my-token").',
+      );
+    }
+    this.#name = name;
+  }
+
+  supply(amount) {
+    if (typeof amount !== 'number' || amount <= 0 || !Number.isFinite(amount)) {
+      throw new ForgeValidationError(
+        'supply() requires a positive number.',
+        'e.g. .supply(1_000_000_000)',
+      );
+    }
+    this.#supply = amount;
+    return this;
+  }
+
+  decimals(d) {
+    if (typeof d !== 'number' || d < 0 || d > 9 || !Number.isInteger(d)) {
+      throw new ForgeValidationError(
+        'decimals() requires an integer between 0 and 9.',
+      );
+    }
+    this.#decimals = d;
+    return this;
+  }
+
+  metadata({ name, symbol, uri } = {}) {
+    if (!name)   throw new ForgeValidationError('metadata() requires a name field.');
+    if (!symbol) throw new ForgeValidationError('metadata() requires a symbol field.');
+    if (!uri)    throw new ForgeValidationError('metadata() requires a uri field.');
+    this.#meta = { name, symbol, uri };
+    return this;
+  }
+
+  // Percentage of total supply to burn immediately after mint (0 to 50).
+  // Fractional percentages are supported (e.g. burn(2.5) = 250 bps).
+  burn(pct) {
+    if (typeof pct !== 'number' || pct < 0 || pct > 50) {
+      throw new ForgeValidationError(
+        'burn() requires a percentage between 0 and 50.',
+        'e.g. .burn(2) burns 2% of supply on mint.',
+      );
+    }
+    this.#burnBps = Math.round(pct * 100);
+    return this;
+  }
+
+  // Call once per authority: .revoke('freeze').revoke('mint')
+  revoke(authority) {
+    if (!VALID_AUTHORITIES.has(authority)) {
+      throw new ForgeValidationError(
+        `revoke() received unknown authority "${authority}".`,
+        'Valid authorities are "freeze" and "mint".',
+      );
+    }
+    this.#revocations.add(authority);
+    return this;
+  }
+
+  wallet(secretKey) {
+    if (!(secretKey instanceof Uint8Array)) {
+      throw new ForgeValidationError(
+        'wallet() expects a Uint8Array (your keypair.secretKey).',
+        'e.g. .wallet(keypair.secretKey)',
+      );
+    }
+    this.#secretKey = secretKey;
+    return this;
+  }
+
+  rpc(url) {
+    if (typeof url !== 'string' || (!url.startsWith('http://') && !url.startsWith('https://'))) {
+      throw new ForgeValidationError(
+        'rpc() requires a valid HTTP or HTTPS URL.',
+        'e.g. .rpc("https://api.mainnet-beta.solana.com")',
+      );
+    }
+    this.#rpcUrl = url;
+    return this;
+  }
+
+  async send() {
+    if (this.#supply === null) {
+      throw new ForgeValidationError(
+        'No supply defined.',
+        'Call .supply(1_000_000_000) before .send().',
+      );
+    }
+    if (!this.#secretKey) {
+      throw new ForgeValidationError(
+        'No wallet provided.',
+        'Call .wallet(keypair.secretKey) before .send().',
+      );
+    }
+
+    const payer       = Keypair.fromSecretKey(Buffer.from(this.#secretKey));
+    const mintKeypair = Keypair.generate();
+    const connection  = new Connection(this.#rpcUrl, 'confirmed');
+
+    let blockhash, lamports;
+    try {
+      [{ blockhash }, lamports] = await Promise.all([
+        connection.getLatestBlockhash('confirmed'),
+        getMinimumBalanceForRentExemptMint(connection),
+      ]);
+    } catch (err) {
+      throw new ForgeRpcError(
+        `Failed to fetch blockhash or rent: ${err?.message ?? String(err)}`,
+        err,
+      );
+    }
+
+    const rawSupply  = BigInt(this.#supply) * BigInt(10 ** this.#decimals);
+    const burnAmount = this.#burnBps > 0
+      ? (rawSupply * BigInt(this.#burnBps)) / 10_000n
+      : 0n;
+    const ata = getAssociatedTokenAddressSync(
+      mintKeypair.publicKey,
+      payer.publicKey,
+    );
+
+    const instructions = [
+      // 1. Create mint account
+      SystemProgram.createAccount({
+        fromPubkey:           payer.publicKey,
+        newAccountPubkey:     mintKeypair.publicKey,
+        space:                MINT_SIZE,
+        lamports,
+        programId:            TOKEN_PROGRAM_ID,
+      }),
+      // 2. Initialise mint
+      createInitializeMintInstruction(
+        mintKeypair.publicKey,
+        this.#decimals,
+        payer.publicKey,
+        payer.publicKey,
+      ),
+      // 3. Create payer's associated token account
+      createAssociatedTokenAccountInstruction(
+        payer.publicKey,
+        ata,
+        payer.publicKey,
+        mintKeypair.publicKey,
+      ),
+      // 4. Mint full supply to payer ATA
+      createMintToInstruction(
+        mintKeypair.publicKey,
+        ata,
+        payer.publicKey,
+        rawSupply,
+      ),
+    ];
+
+    // 5. Burn immediately if configured
+    if (burnAmount > 0n) {
+      const { createBurnInstruction } = await import('@solana/spl-token');
+      instructions.push(
+        createBurnInstruction(ata, mintKeypair.publicKey, payer.publicKey, burnAmount),
+      );
+    }
+
+    // 6. Revoke authorities (order: freeze first, then mint)
+    if (this.#revocations.has('freeze')) {
+      instructions.push(
+        createSetAuthorityInstruction(
+          mintKeypair.publicKey,
+          payer.publicKey,
+          AuthorityType.FreezeAccount,
+          null,
+        ),
+      );
+    }
+    if (this.#revocations.has('mint')) {
+      instructions.push(
+        createSetAuthorityInstruction(
+          mintKeypair.publicKey,
+          payer.publicKey,
+          AuthorityType.MintTokens,
+          null,
+        ),
+      );
+    }
+
+    const message = new TransactionMessage({
+      payerKey:           payer.publicKey,
+      recentBlockhash:    blockhash,
+      instructions,
+    }).compileToV0Message();
+
+    const tx = new VersionedTransaction(message);
+    tx.sign([payer, mintKeypair]);
+
+    let signature;
+    try {
+      signature = await sendAndConfirmRawTransaction(
+        connection,
+        Buffer.from(tx.serialize()),
+        { commitment: 'confirmed' },
+      );
+    } catch (err) {
+      throw new ForgeTxError(
+        `Transaction failed: ${err?.message ?? String(err)}`,
+        err,
+      );
+    }
+
+    // Return raw amounts as strings. BigInt does not serialise to JSON, and
+    // Number loses precision above 2^53 (a 1B supply at 9 decimals overflows).
+    return {
+      signature,
+      mintAddress: mintKeypair.publicKey.toBase58(),
+      supply:      rawSupply.toString(),
+      burned:      burnAmount.toString(),
+      revoked:     [...this.#revocations],
+    };
+  }
+}
+
+export function mint(name) {
+  return new MintBuilder(name);
+}