@vultisig/core-chain 2.37.0 → 2.38.0

package/dist/chains/solana/kamino/tx/sequence.js

@@ -0,0 +1,235 @@
+import { computeBudgetDiscriminators, createIdempotentAtaDiscriminator, hasAnchorDiscriminator, isAttributionMemoData, kaminoDiscriminators, systemTransferDiscriminator, tokenCloseAccountDiscriminator, tokenSyncNativeDiscriminator, } from './instructions.js';
+/**
+ * The instruction shapes each Kamino operation produces, and the walk that
+ * matches a transaction against them.
+ *
+ * Shared by the two places that need it, because they must agree on what a
+ * Kamino transaction is *allowed to contain*: the validator runs it on the
+ * initiating device before signing, followed by account-identity checks that
+ * need the lookup tables resolved; the decoder runs it on ANY device, offline,
+ * before claiming to describe a transaction. Without it the decode would read
+ * one recognised instruction and say nothing about the rest — so a transfer
+ * riding alongside a plausible deposit would be summarised as "Deposit
+ * 1 USDC", which is worse than showing nothing at all.
+ *
+ * A step matches on the program and the instruction discriminator only. Both
+ * are readable without a lookup table (a v0 message's program ids are always
+ * static keys), which is what lets the offline decode use the same template
+ * as the online validator. Everything else about an instruction is checked
+ * after it has been matched, so a wrong ACCOUNT is a refusal rather than a
+ * silent failure to match.
+ */
+export const kaminoInstructionKinds = [
+    'computeUnitLimit',
+    'computeUnitPrice',
+    'createTokenAccount',
+    'wrapSolTransfer',
+    'syncNative',
+    'closeTokenAccount',
+    'kvaultDeposit',
+    'kvaultWithdraw',
+    'farmsInitializeUser',
+    'farmsStake',
+    'farmsUnstake',
+    'farmsWithdrawUnstakedDeposits',
+    'attributionMemo',
+];
+/** Human-readable step names, used in refusal messages. */
+export const kaminoInstructionKindName = {
+    computeUnitLimit: 'compute unit limit',
+    computeUnitPrice: 'compute unit price',
+    createTokenAccount: 'create associated token account',
+    wrapSolTransfer: 'SOL wrap transfer',
+    syncNative: 'wrapped SOL sync',
+    closeTokenAccount: 'close token account',
+    kvaultDeposit: 'vault deposit',
+    kvaultWithdraw: 'vault withdraw',
+    farmsInitializeUser: 'farm user initialization',
+    farmsStake: 'farm stake',
+    farmsUnstake: 'farm unstake',
+    farmsWithdrawUnstakedDeposits: 'farm unstaked share withdrawal',
+    attributionMemo: 'attribution memo',
+};
+/**
+ * The shape `operation` produces against a vault with these properties,
+ * verified by decoding transactions the Kamino API built and simulating them
+ * on mainnet.
+ *
+ * Optional steps are the ones whose absence cannot cost the user anything —
+ * an idempotent account creation that was already done, a farm user that
+ * already exists, a token account that stays open. Everything that decides
+ * where money moves is required, and anything not listed at all is refused.
+ */
+export const expectedKaminoSequence = ({ operation, isWrappedSolVault, hasFarm, hasPriorityFee, hasAttributionMemo, farmUnstake, }) => {
+    const steps = [];
+    const step = (kind, isRequired, isRepeatable, pairedWith) => steps.push({ kind, isRequired, isRepeatable, pairedWith });
+    if (hasPriorityFee) {
+        step('computeUnitLimit', true, false);
+        step('computeUnitPrice', true, false);
+    }
+    if (operation === 'deposit') {
+        step('createTokenAccount', false, true);
+        if (isWrappedSolVault) {
+            step('wrapSolTransfer', true, false);
+            step('syncNative', true, false);
+            step('createTokenAccount', false, true);
+        }
+        step('kvaultDeposit', true, false);
+        if (hasFarm) {
+            // Only the user's farm state may already exist. The stake itself is
+            // what makes the shares the position the app then reads, so a deposit
+            // that omits it is not the deposit that was requested.
+            step('farmsInitializeUser', false, false);
+            step('farmsStake', true, false);
+        }
+    }
+    else {
+        // The share account the released shares land in, created first because
+        // the two farms instructions below need it to exist.
+        step('createTokenAccount', false, true);
+        if (hasFarm && farmUnstake !== 'forbidden') {
+            // BOTH farms instructions, and both BEFORE the vault withdraw — the
+            // shares have to be out of the farm and in the user's own account
+            // before anything can burn them. They appear together or not at all;
+            // `farmUnstake` decides which of the two transaction shapes this is
+            // supposed to be, so a caller that knows gets a REQUIRED pair and a
+            // caller that cannot know gets an optional one — never a silent
+            // "either is fine" for the device that could have checked.
+            const required = farmUnstake === 'required';
+            step('farmsUnstake', required, false, 'farmsWithdrawUnstakedDeposits');
+            step('farmsWithdrawUnstakedDeposits', required, false, 'farmsUnstake');
+            step('createTokenAccount', false, true);
+        }
+        step('kvaultWithdraw', true, false);
+        // Emptied token accounts, closed so their rent comes back. REPEATABLE,
+        // because a full wrapped-SOL withdraw carries two: the payout account and
+        // the now-empty share account. REQUIRED on the wrapped-SOL vault, where
+        // closing the payout account is what unwraps wSOL into the native SOL the
+        // screen says the user receives; optional elsewhere.
+        step('closeTokenAccount', isWrappedSolVault, true);
+    }
+    // Last, because that is where the injector appends it: the memo records who
+    // originated the transaction and takes no part in what it does.
+    if (hasAttributionMemo) {
+        step('attributionMemo', true, false);
+    }
+    return steps;
+};
+/**
+ * The kind of instruction this program and payload are, or `undefined` when
+ * it is none the template knows. Program and discriminator only — see the
+ * module doc for why.
+ */
+export const kaminoInstructionKind = (program, data) => {
+    if (!program)
+        return undefined;
+    switch (program) {
+        case 'computeBudget':
+            if (data[0] === computeBudgetDiscriminators.setUnitLimit)
+                return 'computeUnitLimit';
+            if (data[0] === computeBudgetDiscriminators.setUnitPrice)
+                return 'computeUnitPrice';
+            return undefined;
+        case 'associatedToken':
+            return data[0] === createIdempotentAtaDiscriminator ? 'createTokenAccount' : undefined;
+        case 'system':
+            return data.length >= 4 && systemTransferDiscriminator.every((byte, index) => data[index] === byte)
+                ? 'wrapSolTransfer'
+                : undefined;
+        case 'token':
+        case 'token2022':
+            if (data.length === 1 && data[0] === tokenSyncNativeDiscriminator)
+                return 'syncNative';
+            if (data.length === 1 && data[0] === tokenCloseAccountDiscriminator)
+                return 'closeTokenAccount';
+            return undefined;
+        case 'kvault':
+            if (hasAnchorDiscriminator(data, kaminoDiscriminators.kvaultDeposit))
+                return 'kvaultDeposit';
+            // TWO discriminators, one kind: `withdraw` and `withdraw_from_available`
+            // are the same withdraw — same `u64` share argument, same authority,
+            // same share account burned, same payout account credited — and which
+            // one the builder emits says only whether the vault's liquid buffer
+            // covered the request. That is a fact about the vault's balance sheet,
+            // not about what the user is being asked to approve. They may share the
+            // account map because the IDL declares `withdraw`'s account list as
+            // `withdraw_from_available`'s accounts followed by the reserve group.
+            if (hasAnchorDiscriminator(data, kaminoDiscriminators.kvaultWithdraw) ||
+                hasAnchorDiscriminator(data, kaminoDiscriminators.kvaultWithdrawFromAvailable)) {
+                return 'kvaultWithdraw';
+            }
+            return undefined;
+        case 'memo':
+            // The tag is matched WHOLE, not as a prefix. A memo is free-form bytes,
+            // so the tag followed by anything else is a different memo — and the
+            // one thing this app is willing to sign under the Memo program is its
+            // own attribution tag, exactly.
+            return isAttributionMemoData(data) ? 'attributionMemo' : undefined;
+        case 'farms':
+            if (hasAnchorDiscriminator(data, kaminoDiscriminators.farmsInitializeUser))
+                return 'farmsInitializeUser';
+            if (hasAnchorDiscriminator(data, kaminoDiscriminators.farmsStake))
+                return 'farmsStake';
+            if (hasAnchorDiscriminator(data, kaminoDiscriminators.farmsUnstake))
+                return 'farmsUnstake';
+            if (hasAnchorDiscriminator(data, kaminoDiscriminators.farmsWithdrawUnstakedDeposits)) {
+                return 'farmsWithdrawUnstakedDeposits';
+            }
+            return undefined;
+    }
+};
+/**
+ * Walks `steps` and `kinds` together. A step that does not match is skipped
+ * only when it is optional; an instruction left over at the end has no place
+ * in this operation at all.
+ *
+ * `kinds` holds one entry per instruction, in order, `undefined` for an
+ * instruction whose program is not allow-listed or whose discriminator is not
+ * one the template names.
+ */
+export const matchKaminoSequence = (kinds, steps) => {
+    const matched = [];
+    let cursor = 0;
+    const matches = (kind, position) => position < kinds.length && kinds[position] === kind;
+    for (const step of steps) {
+        if (step.isRepeatable) {
+            // A repeatable step consumes as many as it finds — and if it is also
+            // REQUIRED it has to find at least one. Skipping that check because the
+            // loop already ran is how "one or more" silently becomes "zero or
+            // more": the wrapped-SOL withdraw's close is both, and without this its
+            // requirement would not exist.
+            let consumed = 0;
+            while (matches(step.kind, cursor)) {
+                matched.push(step.kind);
+                cursor += 1;
+                consumed += 1;
+            }
+            if (step.isRequired && consumed === 0) {
+                return { mismatch: { missingInstruction: kaminoInstructionKindName[step.kind] } };
+            }
+            continue;
+        }
+        if (matches(step.kind, cursor)) {
+            matched.push(step.kind);
+            cursor += 1;
+        }
+        else if (step.isRequired) {
+            return { mismatch: { missingInstruction: kaminoInstructionKindName[step.kind] } };
+        }
+    }
+    if (cursor !== kinds.length) {
+        return { mismatch: { unexpectedInstruction: { index: cursor } } };
+    }
+    // Paired steps, last: a half-operation is a refusal even when both of its
+    // halves were individually optional — either the transaction releases
+    // shares from the farm and moves them, or it does neither.
+    for (const step of steps) {
+        if (!step.pairedWith)
+            continue;
+        if (matched.includes(step.kind) !== matched.includes(step.pairedWith)) {
+            return { mismatch: { incompleteInstructionPair: kaminoInstructionKindName[step.kind] } };
+        }
+    }
+    return { matched };
+};
+//# sourceMappingURL=sequence.js.map

package/dist/chains/solana/kamino/tx/sequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.js","sourceRoot":"","sources":["../../../../../../../../packages/core/chain/chains/solana/kamino/tx/sequence.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,gCAAgC,EAChC,sBAAsB,EACtB,qBAAqB,EAErB,oBAAoB,EACpB,2BAA2B,EAC3B,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,gBAAgB,CAAA;AAEvB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,kBAAkB;IAClB,kBAAkB;IAClB,oBAAoB;IACpB,iBAAiB;IACjB,YAAY;IACZ,mBAAmB;IACnB,eAAe;IACf,gBAAgB;IAChB,qBAAqB;IACrB,YAAY;IACZ,cAAc;IACd,+BAA+B;IAC/B,iBAAiB;CACT,CAAA;AAKV,2DAA2D;AAC3D,MAAM,CAAC,MAAM,yBAAyB,GAA0C;IAC9E,gBAAgB,EAAE,oBAAoB;IACtC,gBAAgB,EAAE,oBAAoB;IACtC,kBAAkB,EAAE,iCAAiC;IACrD,eAAe,EAAE,mBAAmB;IACpC,UAAU,EAAE,kBAAkB;IAC9B,iBAAiB,EAAE,qBAAqB;IACxC,aAAa,EAAE,eAAe;IAC9B,cAAc,EAAE,gBAAgB;IAChC,mBAAmB,EAAE,0BAA0B;IAC/C,UAAU,EAAE,YAAY;IACxB,YAAY,EAAE,cAAc;IAC5B,6BAA6B,EAAE,gCAAgC;IAC/D,eAAe,EAAE,kBAAkB;CACpC,CAAA;AAiED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,EACrC,SAAS,EACT,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,kBAAkB,EAClB,WAAW,GACW,EAAwB,EAAE;IAChD,MAAM,KAAK,GAAyB,EAAE,CAAA;IACtC,MAAM,IAAI,GAAG,CACX,IAA2B,EAC3B,UAAmB,EACnB,YAAqB,EACrB,UAAkC,EAClC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,CAAA;IAE/D,IAAI,cAAc,EAAE,CAAC;QACnB,IAAI,CAAC,kBAAkB,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;QACrC,IAAI,CAAC,kBAAkB,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;IACvC,CAAC;IAED,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,oBAAoB,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;QACvC,IAAI,iBAAiB,EAAE,CAAC;YACtB,IAAI,CAAC,iBAAiB,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;YACpC,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;YAC/B,IAAI,CAAC,oBAAoB,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;QACzC,CAAC;QACD,IAAI,CAAC,eAAe,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;QAClC,IAAI,OAAO,EAAE,CAAC;YACZ,oEAAoE;YACpE,sEAAsE;YACtE,uDAAuD;YACvD,IAAI,CAAC,qBAAqB,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;YACzC,IAAI,CAAC,YAAY,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;QACjC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,uEAAuE;QACvE,qDAAqD;QACrD,IAAI,CAAC,oBAAoB,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;QACvC,IAAI,OAAO,IAAI,WAAW,KAAK,WAAW,EAAE,CAAC;YAC3C,oEAAoE;YACpE,kEAAkE;YAClE,qEAAqE;YACrE,oEAAoE;YACpE,oEAAoE;YACpE,gEAAgE;YAChE,2DAA2D;YAC3D,MAAM,QAAQ,GAAG,WAAW,KAAK,UAAU,CAAA;YAC3C,IAAI,CAAC,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAE,+BAA+B,CAAC,CAAA;YACtE,IAAI,CAAC,+BAA+B,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,CAAC,CAAA;YACtE,IAAI,CAAC,oBAAoB,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;QACzC,CAAC;QACD,IAAI,CAAC,gBAAgB,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;QACnC,uEAAuE;QACvE,0EAA0E;QAC1E,wEAAwE;QACxE,0EAA0E;QAC1E,qDAAqD;QACrD,IAAI,CAAC,mBAAmB,EAAE,iBAAiB,EAAE,IAAI,CAAC,CAAA;IACpD,CAAC;IAED,4EAA4E;IAC5E,gEAAgE;IAChE,IAAI,kBAAkB,EAAE,CAAC;QACvB,IAAI,CAAC,iBAAiB,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;IACtC,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,OAAyC,EACzC,IAAgB,EACmB,EAAE;IACrC,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAA;IAC9B,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,eAAe;YAClB,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,2BAA2B,CAAC,YAAY;gBAAE,OAAO,kBAAkB,CAAA;YACnF,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,2BAA2B,CAAC,YAAY;gBAAE,OAAO,kBAAkB,CAAA;YACnF,OAAO,SAAS,CAAA;QAClB,KAAK,iBAAiB;YACpB,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,gCAAgC,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,SAAS,CAAA;QACxF,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,2BAA2B,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;gBACjG,CAAC,CAAC,iBAAiB;gBACnB,CAAC,CAAC,SAAS,CAAA;QACf,KAAK,OAAO,CAAC;QACb,KAAK,WAAW;YACd,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,4BAA4B;gBAAE,OAAO,YAAY,CAAA;YACtF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,8BAA8B;gBAAE,OAAO,mBAAmB,CAAA;YAC/F,OAAO,SAAS,CAAA;QAClB,KAAK,QAAQ;YACX,IAAI,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,CAAC,aAAa,CAAC;gBAAE,OAAO,eAAe,CAAA;YAC5F,yEAAyE;YACzE,qEAAqE;YACrE,sEAAsE;YACtE,oEAAoE;YACpE,uEAAuE;YACvE,wEAAwE;YACxE,oEAAoE;YACpE,sEAAsE;YACtE,IACE,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,CAAC,cAAc,CAAC;gBACjE,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,CAAC,2BAA2B,CAAC,EAC9E,CAAC;gBACD,OAAO,gBAAgB,CAAA;YACzB,CAAC;YACD,OAAO,SAAS,CAAA;QAClB,KAAK,MAAM;YACT,wEAAwE;YACxE,qEAAqE;YACrE,sEAAsE;YACtE,gCAAgC;YAChC,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAA;QACpE,KAAK,OAAO;YACV,IAAI,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,CAAC,mBAAmB,CAAC;gBAAE,OAAO,qBAAqB,CAAA;YACxG,IAAI,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,CAAC,UAAU,CAAC;gBAAE,OAAO,YAAY,CAAA;YACtF,IAAI,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,CAAC,YAAY,CAAC;gBAAE,OAAO,cAAc,CAAA;YAC1F,IAAI,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,CAAC,6BAA6B,CAAC,EAAE,CAAC;gBACrF,OAAO,+BAA+B,CAAA;YACxC,CAAC;YACD,OAAO,SAAS,CAAA;IACpB,CAAC;AACH,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,KAA4C,EAC5C,KAA2B,EACkD,EAAE;IAC/E,MAAM,OAAO,GAA4B,EAAE,CAAA;IAC3C,IAAI,MAAM,GAAG,CAAC,CAAA;IAEd,MAAM,OAAO,GAAG,CAAC,IAA2B,EAAE,QAAgB,EAAW,EAAE,CACzE,QAAQ,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAA;IAErD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,qEAAqE;YACrE,wEAAwE;YACxE,kEAAkE;YAClE,wEAAwE;YACxE,+BAA+B;YAC/B,IAAI,QAAQ,GAAG,CAAC,CAAA;YAChB,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;gBAClC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACvB,MAAM,IAAI,CAAC,CAAA;gBACX,QAAQ,IAAI,CAAC,CAAA;YACf,CAAC;YACD,IAAI,IAAI,CAAC,UAAU,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;gBACtC,OAAO,EAAE,QAAQ,EAAE,EAAE,kBAAkB,EAAE,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAA;YACnF,CAAC;YACD,SAAQ;QACV,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;YAC/B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACvB,MAAM,IAAI,CAAC,CAAA;QACb,CAAC;aAAM,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC3B,OAAO,EAAE,QAAQ,EAAE,EAAE,kBAAkB,EAAE,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAA;QACnF,CAAC;IACH,CAAC;IAED,IAAI,MAAM,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;QAC5B,OAAO,EAAE,QAAQ,EAAE,EAAE,qBAAqB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;IACnE,CAAC;IAED,0EAA0E;IAC1E,sEAAsE;IACtE,2DAA2D;IAC3D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,SAAQ;QAC9B,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACtE,OAAO,EAAE,QAAQ,EAAE,EAAE,yBAAyB,EAAE,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAA;QAC1F,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,CAAA;AACpB,CAAC,CAAA"}

package/dist/chains/solana/kamino/tx/validate.d.ts

@@ -0,0 +1,138 @@
+import { VersionedTransaction } from '@solana/web3.js';
+import { KaminoShareAmount, KaminoTokenAmount } from '../amount.js';
+import { KaminoVaultInfo } from '../models.js';
+/**
+ * A withdraw request, split the way the transaction that answers it is built.
+ *
+ * One type rather than a share amount plus a loose second parameter, because
+ * the split is not optional information: the withdraw endpoint builds a plain
+ * transaction when the request fits inside the shares already in the user's
+ * own account, and one with `farms::unstake` and
+ * `farms::withdraw_unstaked_deposits` in front when it does not. Which of
+ * those two it will be is decided entirely by `shares` against
+ * `unstakedShares`, so a caller that could not state the split could not say
+ * which transaction it was expecting, and would have to accept either.
+ */
+export type KaminoWithdrawRequest = {
+    /** Shares the vault withdraw burns — the `u64` in the instruction. */
+    shares: KaminoShareAmount;
+    /**
+     * Shares already sitting in the user's share account when the position was
+     * read — the part a withdraw spends without touching the farm.
+     */
+    unstakedShares: KaminoShareAmount;
+};
+/**
+ * Shares the farm has to release before the withdraw can burn its amount:
+ * the shortfall, and nothing more. Measured against captured builds: a
+ * request covered by the unstaked balance is built with no farms
+ * instructions at all, and anything above it unstakes exactly the
+ * difference.
+ */
+export declare const kaminoUnstakeShares: ({ shares, unstakedShares }: KaminoWithdrawRequest) => KaminoShareAmount;
+/** The operation a built transaction is supposed to perform. */
+export type KaminoOperationIntent = {
+    deposit: KaminoTokenAmount;
+} | {
+    withdraw: KaminoWithdrawRequest;
+};
+/**
+ * The priority fee the app injected: a compute unit limit and a price per
+ * unit. The fee the network charges is `limit × price`, paid in SOL by the
+ * fee payer, so both halves are a spend and both are checked against the
+ * values the app chose rather than accepted from the transaction.
+ */
+export type KaminoPriorityFee = {
+    unitLimit: number;
+    unitPriceMicroLamports: bigint;
+};
+/** The request a built transaction is supposed to be the answer to. */
+export type KaminoTransactionIntent = {
+    operation: KaminoOperationIntent;
+    vault: KaminoVaultInfo;
+    /**
+     * The user's Solana address: fee payer, sole signer, and the account every
+     * destination must belong to.
+     */
+    owner: string;
+    /**
+     * The priority fee the app injected, or `undefined` before injection — in
+     * which case any ComputeBudget instruction at all is a refusal, because
+     * Kamino's builder emits none and a fee we did not choose is SOL leaving
+     * the wallet.
+     */
+    priorityFee?: KaminoPriorityFee;
+    /**
+     * Whether the app has appended its attribution memo. `false` before
+     * injection, where a memo can only have come from the response — and the
+     * Memo program logs whatever it is handed, so a memo we did not write is
+     * text this app would be signing on somebody else's behalf.
+     */
+    carriesAttributionMemo: boolean;
+};
+/** The category a validation refusal falls into, for branching and tests. */
+export type KaminoValidationFinding = 'vaultNotAllowed' | 'vaultDescriptorMismatch' | 'transactionShape' | 'unexpectedLookupTable' | 'accountResolution' | 'programNotAllowed' | 'unexpectedInstruction' | 'missingInstruction' | 'instructionNotForOperation' | 'malformedInstruction' | 'accountMismatch' | 'accountNotOwnedByUser' | 'amountMismatch' | 'amountOutOfRange' | 'unexpectedPriorityFee' | 'unexpectedMemo' | 'unattributableWritableAccount' | 'unreferencedWritableAccount' | 'derivationFailed';
+/**
+ * A refusal from the fail-closed validator. Everything it finds is a refusal
+ * — nothing downgrades to a warning — and `finding` names the category so
+ * callers and tests branch on data rather than message text.
+ */
+export declare class KaminoValidationError extends Error {
+    readonly finding: KaminoValidationFinding;
+    constructor(finding: KaminoValidationFinding, detail: string);
+}
+/**
+ * The user's associated token accounts for one mint, one per token program.
+ * Both token programs are tried because a mint belongs to exactly one and
+ * which one is not knowable from the address alone.
+ */
+export declare const kaminoUserTokenAccounts: ({ owner, mint }: {
+    owner: string;
+    mint: string;
+}) => Set<string>;
+/**
+ * Fail-closed validation of a Kamino-built Solana transaction.
+ *
+ * Kamino builds the transaction and the app signs the bytes verbatim, so
+ * between an API response and a signature over it there is only this. It runs
+ * before simulation and before keysign, and every finding is a refusal.
+ *
+ * What it establishes, in layers: the shape (one unsigned signature, paid by
+ * the user, every lookup table the vault's own); the programs (every
+ * `programIdIndex` resolves to an allow-listed program — the outer bound on
+ * what the signature can authorise); the sequence (the instruction list
+ * matches the shape this operation produces, so a new instruction fails
+ * closed); the identity of every account that decides where money goes,
+ * compared against values the app already had — registry and local
+ * derivations, never the response, because checking a transaction the API
+ * built against metadata the same API supplied would be circular; the amounts
+ * (the kvault `u64` equals what the user was shown, the priority fee equals
+ * what the app injected); and the writable accounts (no unexplained writes).
+ *
+ * What it does not establish is what the `kvault` and `farms` programs do
+ * with the accounts they are handed. That is the protocol, and choosing to
+ * trust it is what the registry allow-list expresses.
+ *
+ * Pure — lookup tables arrive resolved, so tests can drive it against pinned
+ * contents. `validateKaminoTransactionOnline` is the fetching entry point.
+ */
+export declare const validateKaminoTransaction: ({ transaction, intent, lookupTables, }: {
+    transaction: VersionedTransaction;
+    intent: KaminoTransactionIntent;
+    /** Table address to that table's full address list. */
+    lookupTables: Record<string, string[]>;
+}) => void;
+/**
+ * Resolves the transaction's address lookup tables from the RPC, then runs
+ * the pure validator against them.
+ *
+ * Rejects with `KaminoValidationError` for a refusal of the transaction, and
+ * with `KaminoWireError` when the lookup tables could not be resolved at all
+ * (missing table, stalled node past the read deadline, transport failure) —
+ * callers must not assume every rejection carries a `finding`.
+ */
+export declare const validateKaminoTransactionOnline: ({ transaction, intent, }: {
+    transaction: VersionedTransaction;
+    intent: KaminoTransactionIntent;
+}) => Promise<void>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/chains/solana/kamino/tx/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/chain/chains/solana/kamino/tx/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAEjE,OAAO,EAAE,iBAAiB,EAAqB,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAGnF,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAiC3C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,sEAAsE;IACtE,MAAM,EAAE,iBAAiB,CAAA;IACzB;;;OAGG;IACH,cAAc,EAAE,iBAAiB,CAAA;CAClC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,4BAA4B,qBAAqB,KAAG,iBAGvF,CAAA;AAED,gEAAgE;AAChE,MAAM,MAAM,qBAAqB,GAAG;IAAE,OAAO,EAAE,iBAAiB,CAAA;CAAE,GAAG;IAAE,QAAQ,EAAE,qBAAqB,CAAA;CAAE,CAAA;AAExG;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,sBAAsB,EAAE,MAAM,CAAA;CAC/B,CAAA;AAED,uEAAuE;AACvE,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,EAAE,qBAAqB,CAAA;IAChC,KAAK,EAAE,eAAe,CAAA;IACtB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B;;;;;OAKG;IACH,sBAAsB,EAAE,OAAO,CAAA;CAChC,CAAA;AAED,6EAA6E;AAC7E,MAAM,MAAM,uBAAuB,GAC/B,iBAAiB,GACjB,yBAAyB,GACzB,kBAAkB,GAClB,uBAAuB,GACvB,mBAAmB,GACnB,mBAAmB,GACnB,uBAAuB,GACvB,oBAAoB,GACpB,4BAA4B,GAC5B,sBAAsB,GACtB,iBAAiB,GACjB,uBAAuB,GACvB,gBAAgB,GAChB,kBAAkB,GAClB,uBAAuB,GACvB,gBAAgB,GAChB,+BAA+B,GAC/B,6BAA6B,GAC7B,kBAAkB,CAAA;AAEtB;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAA;gBAE7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,EAAE,MAAM;CAK7D;AAMD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAAI,iBAAiB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KAAG,GAAG,CAAC,MAAM,CAYpG,CAAA;AA0aD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,yBAAyB,GAAI,wCAIvC;IACD,WAAW,EAAE,oBAAoB,CAAA;IACjC,MAAM,EAAE,uBAAuB,CAAA;IAC/B,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;CACvC,KAAG,IAkHH,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,GAAU,0BAGnD;IACD,WAAW,EAAE,oBAAoB,CAAA;IACjC,MAAM,EAAE,uBAAuB,CAAA;CAChC,KAAG,OAAO,CAAC,IAAI,CAGf,CAAA"}