@xitadel-fi/sdk 0.2.5 → 0.2.13

package/dist/sdk/src/admin-action.d.ts

@@ -0,0 +1,38 @@
+import { Connection, PublicKey, Transaction, TransactionInstruction } from '@solana/web3.js';
+import { SquadsContext, WalletMode } from './squads-wallet-modes';
+import { SquadsProposalBundle } from './squads-wrap';
+/**
+ * Options driving the submission strategy for an admin instruction.
+ *
+ *   - eoa    → caller assembles + signs a plain tx targeting xitadel.
+ *   - squads → SDK wraps the instruction into a Squads proposal bundle.
+ *              Caller is responsible for getting threshold approvals +
+ *              submitting the bundle's three transactions.
+ */
+export type AdminActionOpts = {
+    mode: 'eoa';
+} | {
+    mode: 'squads';
+    squads: SquadsContext;
+};
+export interface AdminActionPlan {
+    mode: WalletMode;
+    /** Plain unsigned transaction for EOA mode. Undefined for Squads. */
+    eoaTx?: Transaction;
+    /** Squads proposal lifecycle bundle for Squads mode. Undefined for EOA. */
+    squads?: SquadsProposalBundle;
+}
+/**
+ * Produce the transaction(s) needed to perform `innerIx` under the chosen
+ * admin wallet mode. The function is purely transaction-building: callers
+ * are responsible for fetching blockhash, signing, sending, and waiting
+ * for confirmation. Keeps this SDK helper free of wallet-adapter coupling.
+ */
+export declare function planAdminAction(innerIx: TransactionInstruction, opts: AdminActionOpts, connection: Connection): Promise<AdminActionPlan>;
+/**
+ * Resolve the manager pubkey to embed as the signer slot inside the inner
+ * xitadel instruction. EOA mode uses the operator's wallet directly;
+ * Squads mode uses the derived vault PDA — Squads runs `invoke_signed`
+ * for it at execute time so Anchor's Signer<'info> accepts the same value.
+ */
+export declare function resolveManagerSigner(opts: AdminActionOpts, operator: PublicKey): PublicKey;

package/dist/sdk/src/admin-action.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planAdminAction = planAdminAction;
+exports.resolveManagerSigner = resolveManagerSigner;
+const web3_js_1 = require("@solana/web3.js");
+const squads_wallet_modes_1 = require("./squads-wallet-modes");
+const squads_wrap_1 = require("./squads-wrap");
+/**
+ * Produce the transaction(s) needed to perform `innerIx` under the chosen
+ * admin wallet mode. The function is purely transaction-building: callers
+ * are responsible for fetching blockhash, signing, sending, and waiting
+ * for confirmation. Keeps this SDK helper free of wallet-adapter coupling.
+ */
+async function planAdminAction(innerIx, opts, connection) {
+    if (opts.mode === 'eoa') {
+        return {
+            mode: 'eoa',
+            eoaTx: new web3_js_1.Transaction().add(innerIx),
+        };
+    }
+    const bundle = await (0, squads_wrap_1.wrapWithSquads)(innerIx, opts.squads, connection);
+    return {
+        mode: 'squads',
+        squads: bundle,
+    };
+}
+/**
+ * Resolve the manager pubkey to embed as the signer slot inside the inner
+ * xitadel instruction. EOA mode uses the operator's wallet directly;
+ * Squads mode uses the derived vault PDA — Squads runs `invoke_signed`
+ * for it at execute time so Anchor's Signer<'info> accepts the same value.
+ */
+function resolveManagerSigner(opts, operator) {
+    if (opts.mode === 'eoa')
+        return operator;
+    return (0, squads_wallet_modes_1.getSquadsVaultPda)(opts.squads);
+}

package/dist/sdk/src/program.js

@@ -22,17 +22,17 @@ exports.SEEDS = {
 };
 class XitadelProgram {
     constructor(provider, address) {
-        if (process.env.NODE_ENV === 'development') {
-            const workspace = require('@coral-xyz/anchor').workspace;
-            this.program = workspace.Xitadel;
-        }
-        else {
-            const idl = Object.assign(xitadel_json_1.default, {});
-            if (address) {
-                idl.address = address;
-            }
-            this.program = new anchor_1.Program(idl, provider);
+        // Always construct from bundled IDL + optional address override.
+        // The previous `NODE_ENV === 'development'` branch unconditionally
+        // pulled `anchor.workspace.Xitadel`, which silently ignored the
+        // caller-supplied `address` (e.g. NEXT_PUBLIC_PROGRAM_ID in `pnpm dev`).
+        // Workspace lookup is only meaningful inside `anchor test`, and tests
+        // can construct `Program` directly without this wrapper.
+        const idl = Object.assign(xitadel_json_1.default, {});
+        if (address) {
+            idl.address = address;
         }
+        this.program = new anchor_1.Program(idl, provider);
     }
     getProgramId() {
         return this.program.programId;

package/dist/sdk/src/squads-proposal-client.d.ts

@@ -0,0 +1,21 @@
+import { Connection, PublicKey, Transaction } from '@solana/web3.js';
+export type ProposalStatusKind = 'Draft' | 'Active' | 'Approved' | 'Executing' | 'Executed' | 'Rejected' | 'Cancelled' | 'Unknown';
+export interface ProposalState {
+    multisig: PublicKey;
+    proposalPda: PublicKey;
+    transactionIndex: bigint;
+    status: ProposalStatusKind;
+    approvedBy: PublicKey[];
+    rejectedBy: PublicKey[];
+    cancelledBy: PublicKey[];
+    /** Snapshot of multisig threshold at fetch time (caller may cache separately). */
+    threshold: number;
+    /** True once approvedBy.length >= threshold AND not yet executed. */
+    isExecutable: boolean;
+}
+/** Read on-chain Proposal + Multisig accounts; derive a flat status snapshot. */
+export declare function fetchProposalState(multisigPda: PublicKey, transactionIndex: bigint, connection: Connection): Promise<ProposalState>;
+/** Build a fresh approve tx for the given proposal — caller signs + sends. */
+export declare function buildApproveTx(multisigPda: PublicKey, transactionIndex: bigint, member: PublicKey): Transaction;
+/** Build an execute tx for an approved proposal — caller signs + sends. */
+export declare function buildExecuteTx(multisigPda: PublicKey, transactionIndex: bigint, member: PublicKey, connection: Connection): Promise<Transaction>;

package/dist/sdk/src/squads-proposal-client.js

@@ -0,0 +1,115 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchProposalState = fetchProposalState;
+exports.buildApproveTx = buildApproveTx;
+exports.buildExecuteTx = buildExecuteTx;
+const web3_js_1 = require("@solana/web3.js");
+const multisig = __importStar(require("@sqds/multisig"));
+/** Read on-chain Proposal + Multisig accounts; derive a flat status snapshot. */
+async function fetchProposalState(multisigPda, transactionIndex, connection) {
+    const [proposalPda] = multisig.getProposalPda({
+        multisigPda,
+        transactionIndex,
+    });
+    const [proposal, multisigAccount] = await Promise.all([
+        multisig.accounts.Proposal.fromAccountAddress(connection, proposalPda),
+        multisig.accounts.Multisig.fromAccountAddress(connection, multisigPda),
+    ]);
+    const status = decodeStatus(proposal.status);
+    const approvedBy = proposal.approved;
+    const isExecutable = status === 'Approved' ||
+        (status === 'Active' && approvedBy.length >= multisigAccount.threshold);
+    return {
+        multisig: multisigPda,
+        proposalPda,
+        transactionIndex,
+        status,
+        approvedBy,
+        rejectedBy: proposal.rejected,
+        cancelledBy: proposal.cancelled,
+        threshold: multisigAccount.threshold,
+        isExecutable,
+    };
+}
+function decodeStatus(raw) {
+    if (!raw || typeof raw !== 'object')
+        return 'Unknown';
+    const key = Object.keys(raw)[0];
+    switch (key) {
+        case 'draft':
+        case 'Draft':
+            return 'Draft';
+        case 'active':
+        case 'Active':
+            return 'Active';
+        case 'approved':
+        case 'Approved':
+            return 'Approved';
+        case 'executing':
+        case 'Executing':
+            return 'Executing';
+        case 'executed':
+        case 'Executed':
+            return 'Executed';
+        case 'rejected':
+        case 'Rejected':
+            return 'Rejected';
+        case 'cancelled':
+        case 'Cancelled':
+            return 'Cancelled';
+        default:
+            return 'Unknown';
+    }
+}
+/** Build a fresh approve tx for the given proposal — caller signs + sends. */
+function buildApproveTx(multisigPda, transactionIndex, member) {
+    const ix = multisig.instructions.proposalApprove({
+        multisigPda,
+        transactionIndex,
+        member,
+    });
+    return new web3_js_1.Transaction().add(ix);
+}
+/** Build an execute tx for an approved proposal — caller signs + sends. */
+async function buildExecuteTx(multisigPda, transactionIndex, member, connection) {
+    const result = await multisig.instructions.vaultTransactionExecute({
+        connection,
+        multisigPda,
+        transactionIndex,
+        member,
+    });
+    return new web3_js_1.Transaction().add(result.instruction);
+}

package/dist/sdk/src/squads-wallet-modes.d.ts

@@ -0,0 +1,46 @@
+import { PublicKey } from '@solana/web3.js';
+/**
+ * Admin wallet mode resolved at SDK/frontend layer.
+ *
+ * The xitadel program treats `Config.manager` as a single Pubkey and is
+ * mode-agnostic on-chain. This type lets callers select the correct
+ * transaction shape:
+ *   - 'eoa'    → submit instruction directly with manager as signer
+ *   - 'squads' → wrap instruction as a Squads VaultTransaction proposal
+ */
+export type WalletMode = 'eoa' | 'squads';
+/**
+ * Squads V4 program ID — unified across devnet + mainnet.
+ * Re-exported from @sqds/multisig for caller convenience.
+ */
+export declare const SQUADS_PROGRAM_ID: PublicKey;
+/**
+ * The minimum information needed to identify a Squads vault PDA acting as
+ * xitadel admin. Both fields must be provided up-front by the operator
+ * (typically via app ENV) — vault PDAs are System-owned, so the SDK cannot
+ * infer them from on-chain state alone.
+ */
+export interface SquadsBinding {
+    multisig: PublicKey;
+    vaultIndex: number;
+}
+/**
+ * Per-tx context bundling a binding with the wallet currently in use
+ * (a member of the multisig submitting / approving proposals).
+ */
+export interface SquadsContext extends SquadsBinding {
+    proposer: PublicKey;
+}
+/**
+ * Derive the Squads vault PDA for a given binding. Thin wrapper around
+ * @sqds/multisig getVaultPda — aliased to avoid clashing with the existing
+ * SDK `getVaultPda` (Meteora pool vault).
+ */
+export declare function getSquadsVaultPda(binding: SquadsBinding): PublicKey;
+/**
+ * Confirm a given manager pubkey is actually the vault PDA of the
+ * supplied binding. Hard guard against silently routing admin actions
+ * through the wrong path — callers MUST check this before treating
+ * `Config.manager` as a Squads-managed authority.
+ */
+export declare function verifySquadsBinding(manager: PublicKey, binding: SquadsBinding): boolean;

package/dist/sdk/src/squads-wallet-modes.js

@@ -0,0 +1,67 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQUADS_PROGRAM_ID = void 0;
+exports.getSquadsVaultPda = getSquadsVaultPda;
+exports.verifySquadsBinding = verifySquadsBinding;
+const multisig = __importStar(require("@sqds/multisig"));
+/**
+ * Squads V4 program ID — unified across devnet + mainnet.
+ * Re-exported from @sqds/multisig for caller convenience.
+ */
+exports.SQUADS_PROGRAM_ID = multisig.PROGRAM_ID;
+/**
+ * Derive the Squads vault PDA for a given binding. Thin wrapper around
+ * @sqds/multisig getVaultPda — aliased to avoid clashing with the existing
+ * SDK `getVaultPda` (Meteora pool vault).
+ */
+function getSquadsVaultPda(binding) {
+    const [pda] = multisig.getVaultPda({
+        multisigPda: binding.multisig,
+        index: binding.vaultIndex,
+    });
+    return pda;
+}
+/**
+ * Confirm a given manager pubkey is actually the vault PDA of the
+ * supplied binding. Hard guard against silently routing admin actions
+ * through the wrong path — callers MUST check this before treating
+ * `Config.manager` as a Squads-managed authority.
+ */
+function verifySquadsBinding(manager, binding) {
+    if (binding.vaultIndex < 0 || binding.vaultIndex > 255)
+        return false;
+    return getSquadsVaultPda(binding).equals(manager);
+}

package/dist/sdk/src/squads-wrap.d.ts

@@ -0,0 +1,40 @@
+import { Connection, PublicKey, Transaction, TransactionInstruction } from '@solana/web3.js';
+import { SquadsBinding, SquadsContext } from './squads-wallet-modes';
+/**
+ * Bundle of the three Solana transactions required to push a single inner
+ * instruction through a Squads vault transaction lifecycle.
+ *
+ *   1. createTx  — vaultTransactionCreate + proposalCreate (proposer signs)
+ *   2. approveTx — proposalApprove from the proposer (counts toward threshold)
+ *   3. executeTx — vaultTransactionExecute, callable once threshold met
+ *
+ * Callers submit createTx + approveTx immediately; remaining members
+ * approve separately; finally any member submits executeTx.
+ */
+export interface SquadsProposalBundle {
+    multisig: PublicKey;
+    vaultPda: PublicKey;
+    transactionIndex: bigint;
+    proposalPda: PublicKey;
+    transactionPda: PublicKey;
+    createTx: Transaction;
+    approveTx: Transaction;
+    executeTx: Transaction;
+}
+/**
+ * Wrap a single xitadel instruction as a Squads VaultTransaction proposal.
+ *
+ * The inner instruction MUST list the vault PDA (derived from the binding)
+ * as the signer for any account that would normally be signed by
+ * `Config.manager`. Anchor's `Signer<'info>` constraint accepts the PDA
+ * identically once Squads runs `invoke_signed` at execute time.
+ *
+ * Throws if the binding does not match the on-chain vault PDA — defensive
+ * guard against silently routing admin actions through the wrong path.
+ */
+export declare function wrapWithSquads(innerIx: TransactionInstruction, ctx: SquadsContext, connection: Connection): Promise<SquadsProposalBundle>;
+/** Refetch the threshold + member count to render Squads(N/M) badges. */
+export declare function fetchSquadsThreshold(binding: SquadsBinding, connection: Connection): Promise<{
+    threshold: number;
+    memberCount: number;
+}>;

package/dist/sdk/src/squads-wrap.js

@@ -0,0 +1,122 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapWithSquads = wrapWithSquads;
+exports.fetchSquadsThreshold = fetchSquadsThreshold;
+const web3_js_1 = require("@solana/web3.js");
+const multisig = __importStar(require("@sqds/multisig"));
+const squads_wallet_modes_1 = require("./squads-wallet-modes");
+/**
+ * Wrap a single xitadel instruction as a Squads VaultTransaction proposal.
+ *
+ * The inner instruction MUST list the vault PDA (derived from the binding)
+ * as the signer for any account that would normally be signed by
+ * `Config.manager`. Anchor's `Signer<'info>` constraint accepts the PDA
+ * identically once Squads runs `invoke_signed` at execute time.
+ *
+ * Throws if the binding does not match the on-chain vault PDA — defensive
+ * guard against silently routing admin actions through the wrong path.
+ */
+async function wrapWithSquads(innerIx, ctx, connection) {
+    const vaultPda = (0, squads_wallet_modes_1.getSquadsVaultPda)(ctx);
+    if (!(0, squads_wallet_modes_1.verifySquadsBinding)(vaultPda, ctx)) {
+        throw new Error('Squads binding mismatch: derived vault PDA does not match the supplied multisig + vaultIndex');
+    }
+    // Read current transactionIndex; next proposal sits at + 1.
+    const multisigAccount = await multisig.accounts.Multisig.fromAccountAddress(connection, ctx.multisig);
+    const currentIndex = BigInt(multisigAccount.transactionIndex.toString());
+    const transactionIndex = currentIndex + 1n;
+    // Wrap inner ix into a v0 TransactionMessage with vault PDA as payer.
+    // recentBlockhash here is a placeholder consumed by Squads serializer;
+    // the on-chain execute step does not enforce it.
+    const transactionMessage = new web3_js_1.TransactionMessage({
+        payerKey: vaultPda,
+        recentBlockhash: web3_js_1.PublicKey.default.toBase58(),
+        instructions: [innerIx],
+    });
+    const createIx = multisig.instructions.vaultTransactionCreate({
+        multisigPda: ctx.multisig,
+        transactionIndex,
+        creator: ctx.proposer,
+        vaultIndex: ctx.vaultIndex,
+        ephemeralSigners: 0,
+        transactionMessage,
+    });
+    const proposalIx = multisig.instructions.proposalCreate({
+        multisigPda: ctx.multisig,
+        creator: ctx.proposer,
+        transactionIndex,
+    });
+    const approveIx = multisig.instructions.proposalApprove({
+        multisigPda: ctx.multisig,
+        transactionIndex,
+        member: ctx.proposer,
+    });
+    const executeResult = await multisig.instructions.vaultTransactionExecute({
+        connection,
+        multisigPda: ctx.multisig,
+        transactionIndex,
+        member: ctx.proposer,
+    });
+    const [transactionPda] = multisig.getTransactionPda({
+        multisigPda: ctx.multisig,
+        index: transactionIndex,
+    });
+    const [proposalPda] = multisig.getProposalPda({
+        multisigPda: ctx.multisig,
+        transactionIndex,
+    });
+    const createTx = new web3_js_1.Transaction().add(createIx, proposalIx);
+    const approveTx = new web3_js_1.Transaction().add(approveIx);
+    const executeTx = new web3_js_1.Transaction().add(executeResult.instruction);
+    return {
+        multisig: ctx.multisig,
+        vaultPda,
+        transactionIndex,
+        proposalPda,
+        transactionPda,
+        createTx,
+        approveTx,
+        executeTx,
+    };
+}
+/** Refetch the threshold + member count to render Squads(N/M) badges. */
+async function fetchSquadsThreshold(binding, connection) {
+    const account = await multisig.accounts.Multisig.fromAccountAddress(connection, binding.multisig);
+    return {
+        threshold: account.threshold,
+        memberCount: account.members.length,
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "private": false,
   "name": "@xitadel-fi/sdk",
-  "version": "0.2.5",
+  "version": "0.2.13",
   "description": "SDK for interacting with the Xitadel program",
   "main": "dist/sdk/src/index.js",
   "types": "dist/sdk/src/index.d.ts",
@@ -13,8 +13,8 @@
     "url": "git+https://github.com/xitadel-fi/xitadel-svm.git"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
+    "registry": "https://npm.pkg.github.com/",
+    "access": "restricted"
   },
   "scripts": {
     "build": "tsc",