crypto-aio 0.0.3 → 0.1.0

package/dist/adapters/solana/fees.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lamportsCharged = exports.MAX_PRICE_VARIANT = exports.VARIANTS = exports.SPEED_PERCENTILE = void 0;
+exports.computeUnitLimitFor = computeUnitLimitFor;
+exports.fallbackComputeUnitLimit = fallbackComputeUnitLimit;
+exports.variantOffsets = variantOffsets;
+exports.speedPrice = speedPrice;
+exports.aboveMaxPrice = aboveMaxPrice;
+exports.variantCounter = variantCounter;
+exports.priorityFee = priorityFee;
+exports.priceForSpeed = priceForSpeed;
+exports.parseOverride = parseOverride;
+exports.feeDraft = feeDraft;
+exports.detailsOf = detailsOf;
+exports.signedFee = signedFee;
+/**
+ * The Solana fee policy (base fee plus priority), pure and bigint-only. The
+ * priority fee is `ceil(computeUnitPrice × computeUnitLimit / 1_000_000)` lamports, charged
+ * on the requested limit (Solana's fee documentation).
+ */
+const error_1 = require("../../core/errors/error");
+const programs_1 = require("./programs");
+const rpc_1 = require("./rpc");
+/** Library policy: the percentile of recent prioritization fees each speed pays. */
+exports.SPEED_PERCENTILE = Object.freeze({
+    slow: 25,
+    normal: 50,
+    fast: 75,
+});
+/** Library policy: the compute-unit limit is the simulated usage plus 20% and 1,000 units. */
+function computeUnitLimitFor(unitsConsumed) {
+    const limit = unitsConsumed + unitsConsumed / 5n + 1000n;
+    return limit > programs_1.MAX_COMPUTE_UNIT_LIMIT ? programs_1.MAX_COMPUTE_UNIT_LIMIT : limit;
+}
+/** The runtime's own default when a simulation cannot measure the transaction. */
+function fallbackComputeUnitLimit(instructions) {
+    const limit = programs_1.DEFAULT_INSTRUCTION_COMPUTE_UNITS * BigInt(instructions);
+    return limit > programs_1.MAX_COMPUTE_UNIT_LIMIT ? programs_1.MAX_COMPUTE_UNIT_LIMIT : limit;
+}
+/**
+ * Build variants: identical intents built on the same blockhash would
+ * sign byte-identical messages, so a second Operation would silently share the first one's
+ * signature and one payment would be lost. Each estimate therefore adds a variant to the
+ * compute-unit limit (0 to 1,023 units) and, for a speed, to the price (0 to 999
+ * micro-lamports): at most about one lamport of priority fee per 1,000 compute units.
+ */
+exports.VARIANTS = 1_024 * 1_000;
+function variantOffsets(variant) {
+    return {
+        limit: BigInt(variant % 1_024),
+        price: BigInt(Math.floor(variant / 1_024) % 1_000),
+    };
+}
+/** The largest price variant a speed adds, in micro-lamports per compute unit. */
+exports.MAX_PRICE_VARIANT = 999n;
+/**
+ * A speed's signed price within the handle's `maxComputeUnitPrice`: the node's
+ * percentile, at most the bound less the largest variant, plus this build's variant. The
+ * signed price never exceeds the bound, and identical transfers still differ at it.
+ * The bound is at least `MAX_PRICE_VARIANT` (`solanaNetworkConfig`).
+ */
+function speedPrice(percentile, variant, maxComputeUnitPrice) {
+    const ceiling = maxComputeUnitPrice - exports.MAX_PRICE_VARIANT;
+    return (percentile < ceiling ? percentile : ceiling) + variant;
+}
+/**
+ * An explicit price above the handle's bound, refused before anything is signed. The details
+ * carry the price and the bound (decimal strings), so the caller sees what to allow.
+ */
+function aboveMaxPrice(price, maxComputeUnitPrice) {
+    return new error_1.ValidationError('INVALID_INTENT', 'computeUnitPrice is above maxComputeUnitPrice, the Solana handle option that bounds it (micro-lamports per compute unit)', {
+        details: {
+            required: price.toString(),
+            maxComputeUnitPrice: maxComputeUnitPrice.toString(),
+        },
+    });
+}
+/**
+ * The highest recent price a speed pays: the u64 range less the largest price variant
+ * (999), so the varied price still fits its u64 field.
+ */
+const MAX_RECENT_PRICE = 2n ** 64n - 1n - 999n;
+/** A per-driver counter from a random start: distinct in-process, rare across processes. */
+function variantCounter(start) {
+    let next = start % exports.VARIANTS;
+    return () => {
+        const variant = next;
+        next = (next + 1) % exports.VARIANTS;
+        return variant;
+    };
+}
+function priorityFee(computeUnitPrice, computeUnitLimit) {
+    return (computeUnitPrice * computeUnitLimit + 999999n) / 1000000n;
+}
+/**
+ * The nearest-rank percentile of `getRecentPrioritizationFees` answers (micro-lamports per
+ * compute unit); `0n` when the node reports none. A malformed entry, including one outside
+ * the u64 range or without room for the price variant, is a retryable
+ * `PROVIDER_UNAVAILABLE`.
+ */
+function priceForSpeed(recent, speed) {
+    if (!Array.isArray(recent))
+        throw (0, rpc_1.malformed)('getRecentPrioritizationFees');
+    const fees = recent.map((entry) => {
+        const fee = (0, rpc_1.u64)(entry?.prioritizationFee, 'getRecentPrioritizationFees');
+        if (fee > MAX_RECENT_PRICE)
+            throw (0, rpc_1.malformed)('getRecentPrioritizationFees');
+        return fee;
+    });
+    if (fees.length === 0)
+        return 0n;
+    fees.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const rank = Math.ceil((exports.SPEED_PERCENTILE[speed] / 100) * fees.length);
+    return fees[Math.max(0, rank - 1)];
+}
+/** A validated `SolanaFeeOverride`; anything else is `INVALID_INTENT`. */
+function parseOverride(fee) {
+    const invalid = (reason) => new error_1.ValidationError('INVALID_INTENT', `Solana fee override: ${reason}`);
+    const keys = Object.keys(fee);
+    if (keys.some((key) => key !== 'computeUnitPrice' && key !== 'computeUnitLimit')) {
+        throw invalid('only computeUnitPrice and computeUnitLimit are allowed');
+    }
+    const { computeUnitPrice, computeUnitLimit } = fee;
+    if (typeof computeUnitPrice !== 'bigint' ||
+        computeUnitPrice < 0n ||
+        computeUnitPrice >= 2n ** 64n) {
+        throw invalid('computeUnitPrice must be a bigint of micro-lamports in the u64 range');
+    }
+    if (computeUnitLimit !== undefined &&
+        (typeof computeUnitLimit !== 'bigint' ||
+            computeUnitLimit < 1n ||
+            computeUnitLimit > programs_1.MAX_COMPUTE_UNIT_LIMIT)) {
+        throw invalid('computeUnitLimit must be a bigint from 1 to 1,400,000');
+    }
+    return {
+        computeUnitPrice,
+        ...(computeUnitLimit !== undefined ? { computeUnitLimit } : {}),
+    };
+}
+/**
+ * The fee draft: `network` (the signature fee), `priority` and, when the recipient's token
+ * account is created, `rent`. The bound is `exact` unless rent is charged: that deposit is
+ * skipped when someone else creates the account first, so it is an upper bound.
+ */
+function feeDraft(speed, details) {
+    const charges = [
+        { asset: 'native', amount: details.baseFee, label: 'network' },
+        { asset: 'native', amount: details.priorityFee, label: 'priority' },
+    ];
+    if (details.createsRecipientAccount) {
+        charges.push({ asset: 'native', amount: details.rent, label: 'rent' });
+    }
+    return {
+        kind: 'solana',
+        speed,
+        charges,
+        bound: details.createsRecipientAccount ? 'upper' : 'exact',
+        details: { ...details },
+    };
+}
+/** The `SolanaFeeDetails` of a draft this driver made; anything else is `INVALID_INTENT`. */
+function detailsOf(fee) {
+    const d = fee.details;
+    if (fee.kind !== 'solana' ||
+        typeof d.computeUnitLimit !== 'bigint' ||
+        typeof d.computeUnitPrice !== 'bigint' ||
+        typeof d.baseFee !== 'bigint' ||
+        typeof d.priorityFee !== 'bigint' ||
+        typeof d.rent !== 'bigint' ||
+        typeof d.signatures !== 'number' ||
+        typeof d.createsRecipientAccount !== 'boolean') {
+        throw new error_1.ValidationError('INVALID_INTENT', 'not a Solana fee estimate');
+    }
+    return {
+        signatures: d.signatures,
+        baseFee: d.baseFee,
+        computeUnitLimit: d.computeUnitLimit,
+        computeUnitPrice: d.computeUnitPrice,
+        priorityFee: d.priorityFee,
+        rent: d.rent,
+        createsRecipientAccount: d.createsRecipientAccount,
+    };
+}
+/**
+ * The compute budget `build` signs, checked wherever the estimate
+ * came from (the store, `prepareTransfer`, a caller): the price within the handle's bound,
+ * the limit within the protocol's, and the priority fee exactly the one that budget costs.
+ */
+function signedFee(fee, maxComputeUnitPrice) {
+    const details = detailsOf(fee);
+    const { computeUnitPrice: price, computeUnitLimit: limit } = details;
+    if (price > maxComputeUnitPrice)
+        throw aboveMaxPrice(price, maxComputeUnitPrice);
+    if (price < 0n ||
+        limit < 1n ||
+        limit > programs_1.MAX_COMPUTE_UNIT_LIMIT ||
+        details.priorityFee !== priorityFee(price, limit)) {
+        throw new error_1.ValidationError('INVALID_INTENT', 'the fee estimate is not consistent with its own compute budget');
+    }
+    return details;
+}
+/** The lamports every fee charge of `fee` adds up to. */
+const lamportsCharged = (fee) => fee.charges.reduce((sum, charge) => sum + charge.amount, 0n);
+exports.lamportsCharged = lamportsCharged;
+//# sourceMappingURL=fees.js.map

package/dist/adapters/solana/fees.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fees.js","sourceRoot":"","sources":["../../../src/adapters/solana/fees.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The Solana fee policy (base fee plus priority), pure and bigint-only. The\n * priority fee is `ceil(computeUnitPrice × computeUnitLimit / 1_000_000)` lamports, charged\n * on the requested limit (Solana's fee documentation).\n */\nimport { ValidationError } from '../../core/errors/error';\nimport type {\n  FeeChargeDraft,\n  FeeEstimateDraft,\n  FeeOverride,\n  FeeSpeed,\n} from '../../core/model/fee';\nimport { DEFAULT_INSTRUCTION_COMPUTE_UNITS, MAX_COMPUTE_UNIT_LIMIT } from './programs';\nimport { malformed, u64 } from './rpc';\nimport type { SolanaFeeDetails, SolanaFeeOverride } from './types';\n\n/** Library policy: the percentile of recent prioritization fees each speed pays. */\nexport const SPEED_PERCENTILE: Readonly<Record<FeeSpeed, number>> = Object.freeze({\n  slow: 25,\n  normal: 50,\n  fast: 75,\n});\n\n/** Library policy: the compute-unit limit is the simulated usage plus 20% and 1,000 units. */\nexport function computeUnitLimitFor(unitsConsumed: bigint): bigint {\n  const limit = unitsConsumed + unitsConsumed / 5n + 1_000n;\n  return limit > MAX_COMPUTE_UNIT_LIMIT ? MAX_COMPUTE_UNIT_LIMIT : limit;\n}\n\n/** The runtime's own default when a simulation cannot measure the transaction. */\nexport function fallbackComputeUnitLimit(instructions: number): bigint {\n  const limit = DEFAULT_INSTRUCTION_COMPUTE_UNITS * BigInt(instructions);\n  return limit > MAX_COMPUTE_UNIT_LIMIT ? MAX_COMPUTE_UNIT_LIMIT : limit;\n}\n\n/**\n * Build variants: identical intents built on the same blockhash would\n * sign byte-identical messages, so a second Operation would silently share the first one's\n * signature and one payment would be lost. Each estimate therefore adds a variant to the\n * compute-unit limit (0 to 1,023 units) and, for a speed, to the price (0 to 999\n * micro-lamports): at most about one lamport of priority fee per 1,000 compute units.\n */\nexport const VARIANTS = 1_024 * 1_000;\n\nexport function variantOffsets(variant: number): {\n  readonly limit: bigint;\n  readonly price: bigint;\n} {\n  return {\n    limit: BigInt(variant % 1_024),\n    price: BigInt(Math.floor(variant / 1_024) % 1_000),\n  };\n}\n\n/** The largest price variant a speed adds, in micro-lamports per compute unit. */\nexport const MAX_PRICE_VARIANT = 999n;\n\n/**\n * A speed's signed price within the handle's `maxComputeUnitPrice`: the node's\n * percentile, at most the bound less the largest variant, plus this build's variant. The\n * signed price never exceeds the bound, and identical transfers still differ at it.\n * The bound is at least `MAX_PRICE_VARIANT` (`solanaNetworkConfig`).\n */\nexport function speedPrice(\n  percentile: bigint,\n  variant: bigint,\n  maxComputeUnitPrice: bigint,\n): bigint {\n  const ceiling = maxComputeUnitPrice - MAX_PRICE_VARIANT;\n  return (percentile < ceiling ? percentile : ceiling) + variant;\n}\n\n/**\n * An explicit price above the handle's bound, refused before anything is signed. The details\n * carry the price and the bound (decimal strings), so the caller sees what to allow.\n */\nexport function aboveMaxPrice(\n  price: bigint,\n  maxComputeUnitPrice: bigint,\n): ValidationError {\n  return new ValidationError(\n    'INVALID_INTENT',\n    'computeUnitPrice is above maxComputeUnitPrice, the Solana handle option that bounds it (micro-lamports per compute unit)',\n    {\n      details: {\n        required: price.toString(),\n        maxComputeUnitPrice: maxComputeUnitPrice.toString(),\n      },\n    },\n  );\n}\n\n/**\n * The highest recent price a speed pays: the u64 range less the largest price variant\n * (999), so the varied price still fits its u64 field.\n */\nconst MAX_RECENT_PRICE = 2n ** 64n - 1n - 999n;\n\n/** A per-driver counter from a random start: distinct in-process, rare across processes. */\nexport function variantCounter(start: number): () => number {\n  let next = start % VARIANTS;\n  return () => {\n    const variant = next;\n    next = (next + 1) % VARIANTS;\n    return variant;\n  };\n}\n\nexport function priorityFee(computeUnitPrice: bigint, computeUnitLimit: bigint): bigint {\n  return (computeUnitPrice * computeUnitLimit + 999_999n) / 1_000_000n;\n}\n\n/**\n * The nearest-rank percentile of `getRecentPrioritizationFees` answers (micro-lamports per\n * compute unit); `0n` when the node reports none. A malformed entry, including one outside\n * the u64 range or without room for the price variant, is a retryable\n * `PROVIDER_UNAVAILABLE`.\n */\nexport function priceForSpeed(recent: unknown, speed: FeeSpeed): bigint {\n  if (!Array.isArray(recent)) throw malformed('getRecentPrioritizationFees');\n  const fees = recent.map((entry: unknown) => {\n    const fee = u64(\n      (entry as { prioritizationFee?: unknown } | null)?.prioritizationFee,\n      'getRecentPrioritizationFees',\n    );\n    if (fee > MAX_RECENT_PRICE) throw malformed('getRecentPrioritizationFees');\n    return fee;\n  });\n  if (fees.length === 0) return 0n;\n  fees.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));\n  const rank = Math.ceil((SPEED_PERCENTILE[speed] / 100) * fees.length);\n  return fees[Math.max(0, rank - 1)] as bigint;\n}\n\n/** A validated `SolanaFeeOverride`; anything else is `INVALID_INTENT`. */\nexport function parseOverride(fee: FeeOverride): SolanaFeeOverride {\n  const invalid = (reason: string) =>\n    new ValidationError('INVALID_INTENT', `Solana fee override: ${reason}`);\n  const keys = Object.keys(fee);\n  if (keys.some((key) => key !== 'computeUnitPrice' && key !== 'computeUnitLimit')) {\n    throw invalid('only computeUnitPrice and computeUnitLimit are allowed');\n  }\n  const { computeUnitPrice, computeUnitLimit } = fee;\n  if (\n    typeof computeUnitPrice !== 'bigint' ||\n    computeUnitPrice < 0n ||\n    computeUnitPrice >= 2n ** 64n\n  ) {\n    throw invalid('computeUnitPrice must be a bigint of micro-lamports in the u64 range');\n  }\n  if (\n    computeUnitLimit !== undefined &&\n    (typeof computeUnitLimit !== 'bigint' ||\n      computeUnitLimit < 1n ||\n      computeUnitLimit > MAX_COMPUTE_UNIT_LIMIT)\n  ) {\n    throw invalid('computeUnitLimit must be a bigint from 1 to 1,400,000');\n  }\n  return {\n    computeUnitPrice,\n    ...(computeUnitLimit !== undefined ? { computeUnitLimit } : {}),\n  };\n}\n\n/**\n * The fee draft: `network` (the signature fee), `priority` and, when the recipient's token\n * account is created, `rent`. The bound is `exact` unless rent is charged: that deposit is\n * skipped when someone else creates the account first, so it is an upper bound.\n */\nexport function feeDraft(\n  speed: FeeSpeed | 'custom',\n  details: SolanaFeeDetails,\n): FeeEstimateDraft {\n  const charges: FeeChargeDraft[] = [\n    { asset: 'native', amount: details.baseFee, label: 'network' },\n    { asset: 'native', amount: details.priorityFee, label: 'priority' },\n  ];\n  if (details.createsRecipientAccount) {\n    charges.push({ asset: 'native', amount: details.rent, label: 'rent' });\n  }\n  return {\n    kind: 'solana',\n    speed,\n    charges,\n    bound: details.createsRecipientAccount ? 'upper' : 'exact',\n    details: { ...details },\n  };\n}\n\n/** The `SolanaFeeDetails` of a draft this driver made; anything else is `INVALID_INTENT`. */\nexport function detailsOf(fee: FeeEstimateDraft): SolanaFeeDetails {\n  const d = fee.details as Partial<SolanaFeeDetails>;\n  if (\n    fee.kind !== 'solana' ||\n    typeof d.computeUnitLimit !== 'bigint' ||\n    typeof d.computeUnitPrice !== 'bigint' ||\n    typeof d.baseFee !== 'bigint' ||\n    typeof d.priorityFee !== 'bigint' ||\n    typeof d.rent !== 'bigint' ||\n    typeof d.signatures !== 'number' ||\n    typeof d.createsRecipientAccount !== 'boolean'\n  ) {\n    throw new ValidationError('INVALID_INTENT', 'not a Solana fee estimate');\n  }\n  return {\n    signatures: d.signatures,\n    baseFee: d.baseFee,\n    computeUnitLimit: d.computeUnitLimit,\n    computeUnitPrice: d.computeUnitPrice,\n    priorityFee: d.priorityFee,\n    rent: d.rent,\n    createsRecipientAccount: d.createsRecipientAccount,\n  };\n}\n\n/**\n * The compute budget `build` signs, checked wherever the estimate\n * came from (the store, `prepareTransfer`, a caller): the price within the handle's bound,\n * the limit within the protocol's, and the priority fee exactly the one that budget costs.\n */\nexport function signedFee(\n  fee: FeeEstimateDraft,\n  maxComputeUnitPrice: bigint,\n): SolanaFeeDetails {\n  const details = detailsOf(fee);\n  const { computeUnitPrice: price, computeUnitLimit: limit } = details;\n  if (price > maxComputeUnitPrice) throw aboveMaxPrice(price, maxComputeUnitPrice);\n  if (\n    price < 0n ||\n    limit < 1n ||\n    limit > MAX_COMPUTE_UNIT_LIMIT ||\n    details.priorityFee !== priorityFee(price, limit)\n  ) {\n    throw new ValidationError(\n      'INVALID_INTENT',\n      'the fee estimate is not consistent with its own compute budget',\n    );\n  }\n  return details;\n}\n\n/** The lamports every fee charge of `fee` adds up to. */\nexport const lamportsCharged = (fee: FeeEstimateDraft): bigint =>\n  fee.charges.reduce((sum, charge) => sum + charge.amount, 0n);\n"]}

package/dist/adapters/solana/heights.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Dense block heights over Solana's slots: the core's heights must be dense, so they are
+ * block heights, never slots. Slots can be skipped; block heights count only produced
+ * blocks, so every height up to the head has exactly one block. The index maps a height
+ * to its slot with `getBlocks`, which lists the produced slots of a range: anchored on a
+ * known block at the head, the block `k` places before it in that list is `k` heights
+ * lower.
+ *
+ * A list can have gaps (a ledger jump to a snapshot, a long-term-storage gap, pruning), so
+ * no pair is believed until a read of the list's first block confirms its height. Only
+ * finalized, verified pairs are cached (immutable chain data, the only state a shared
+ * driver may keep), which makes a forward scan cost one `getBlock` per height. A height
+ * the endpoint no longer holds is a retryable error that decides nothing, never `null`
+ * (`null` means "not visible yet"). Every read is a single endpoint's view: verdicts
+ * quorum-read the block at the resolved slot. Any other RPC error decides nothing either:
+ * proofs reach this index, and agave answers `getBlocks` below its local ledger with
+ * `-32602 "BigTable query failed"` when long-term storage fails. Such a page starts again
+ * at the endpoint's first available block (liveness), so a height inside its ledger still
+ * resolves.
+ */
+import type { Transport } from '../../core/transport/types';
+import { type BlockHeader } from './rpc';
+import type { Commitment, SolanaCallTags } from './types';
+export interface HeadBlock {
+    readonly slot: bigint;
+    readonly header: BlockHeader;
+}
+export declare class HeightIndex {
+    #private;
+    constructor(transport: Transport);
+    /** The block at the endpoint's `commitment` head (one `getSlot`, one `getBlock`). */
+    head(commitment: Commitment, tags: SolanaCallTags): Promise<HeadBlock>;
+    /**
+     * The block at `slot`, or `null` while the endpoint has not reached it at `commitment`.
+     * A pruned or missing block is a retryable error (decides nothing); a slot the endpoint
+     * calls skipped means a list named a slot with no block, so the cache is dropped.
+     */
+    header(slot: bigint, commitment: Commitment, tags: SolanaCallTags): Promise<BlockHeader | null>;
+    /**
+     * The slot of the block at `height` on the endpoint's chain at `commitment`, or `null`
+     * while that chain has no block at `height` yet. A `confirmed` lookup at or below the
+     * endpoint's finalized height resolves on the finalized chain, which fills the cache.
+     */
+    slotAt(height: bigint, commitment: Commitment, tags: SolanaCallTags): Promise<bigint | null>;
+    /** Drops every cached pair: a later read contradicted one (cheap to rebuild). */
+    forget(): void;
+}

package/dist/adapters/solana/heights.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeightIndex = void 0;
+const rpc_1 = require("./rpc");
+/** `getBlocks` accepts at most this many slots per call (agave). */
+const MAX_RANGE = 500000n;
+/** At most this many `getBlocks` pages below the head (about 8 M slots). */
+const MAX_PAGES = 16;
+/** Verified finalized height → slot pairs kept per driver. */
+const CACHE_SIZE = 8_192;
+class HeightIndex {
+    #transport;
+    #final = new Map();
+    constructor(transport) {
+        this.#transport = transport;
+    }
+    /** The block at the endpoint's `commitment` head (one `getSlot`, one `getBlock`). */
+    async head(commitment, tags) {
+        const slot = (0, rpc_1.u64)(await (0, rpc_1.call)(this.#transport, 'getSlot', [{ commitment }], tags), 'getSlot');
+        const header = await this.header(slot, commitment, tags);
+        if (!header)
+            throw (0, rpc_1.notYet)(`the ${commitment} head block`);
+        return { slot, header };
+    }
+    /**
+     * The block at `slot`, or `null` while the endpoint has not reached it at `commitment`.
+     * A pruned or missing block is a retryable error (decides nothing); a slot the endpoint
+     * calls skipped means a list named a slot with no block, so the cache is dropped.
+     */
+    async header(slot, commitment, tags) {
+        let result;
+        try {
+            result = await (0, rpc_1.call)(this.#transport, 'getBlock', [Number(slot), (0, rpc_1.headerOptions)(commitment)], tags);
+        }
+        catch (error) {
+            if ((0, rpc_1.isNotYet)(error))
+                return null;
+            if ((0, rpc_1.isGone)(error))
+                throw (0, rpc_1.gone)(`the block at slot ${slot}`);
+            if ((0, rpc_1.isSkipped)(error)) {
+                this.forget();
+                throw (0, rpc_1.inconsistent)(`slot ${slot} holds no block`);
+            }
+            throw (0, rpc_1.undecided)(error, `the block at slot ${slot}`);
+        }
+        return result === null ? null : (0, rpc_1.blockHeader)(result);
+    }
+    /**
+     * The slot of the block at `height` on the endpoint's chain at `commitment`, or `null`
+     * while that chain has no block at `height` yet. A `confirmed` lookup at or below the
+     * endpoint's finalized height resolves on the finalized chain, which fills the cache.
+     */
+    async slotAt(height, commitment, tags) {
+        if (height < 0n)
+            return null;
+        const cached = this.#final.get(height);
+        if (cached !== undefined)
+            return cached;
+        const final = await this.head('finalized', tags);
+        if (height <= final.header.blockHeight) {
+            return this.#resolve(height, final, 'finalized', tags);
+        }
+        if (commitment === 'finalized')
+            return null;
+        const top = await this.head('confirmed', tags);
+        if (height > top.header.blockHeight)
+            return null;
+        return this.#resolve(height, top, 'confirmed', tags);
+    }
+    /** Counts back from `top` through verified `getBlocks` pages to the block at `height`. */
+    async #resolve(height, top, commitment, tags) {
+        let anchorSlot = top.slot;
+        let anchorHeight = top.header.blockHeight;
+        if (height === anchorHeight)
+            return anchorSlot;
+        let span = anchorHeight - height + (anchorHeight - height) / 4n + 64n;
+        for (let page = 0; page < MAX_PAGES; page++) {
+            if (span > MAX_RANGE)
+                span = MAX_RANGE;
+            const want = anchorSlot > span ? anchorSlot - span : 0n;
+            const { from, slots } = await this.#page(want, anchorSlot, commitment, tags);
+            const last = slots.length - 1;
+            // agave lists nothing when the range ends above what the endpoint holds at
+            // `commitment` (a backend whose root trails the anchor): that list ends nowhere.
+            if (last < 0 || slots[last] !== anchorSlot) {
+                throw (0, rpc_1.inconsistent)(`getBlocks does not end at slot ${anchorSlot}`);
+            }
+            // A list that adds nothing below its anchor: the endpoint holds nothing older.
+            if (last === 0)
+                throw (0, rpc_1.gone)(`the block at height ${height}`);
+            // The list's first block must sit exactly `last` heights below the anchor, or
+            // the list has a gap; nothing from it is believed or cached.
+            const firstHeight = anchorHeight - BigInt(last);
+            const first = await this.header(slots[0], commitment, tags);
+            if (!first)
+                throw (0, rpc_1.notYet)(`the block at slot ${slots[0]}`);
+            if (first.blockHeight !== firstHeight) {
+                throw (0, rpc_1.inconsistent)(`the blocks listed below slot ${anchorSlot} have a gap`);
+            }
+            slots.forEach((slot, i) => {
+                const at = firstHeight + BigInt(i);
+                // Keep the pairs a forward scan from `height` needs next.
+                if (at >= height && at < height + BigInt(CACHE_SIZE)) {
+                    this.#remember(commitment, at, slot);
+                }
+            });
+            if (height >= firstHeight)
+                return slots[Number(height - firstHeight)];
+            // The list started at slot 0, or at the endpoint's first available block.
+            if (from === 0n || from > want)
+                throw (0, rpc_1.gone)(`the block at height ${height}`);
+            anchorHeight = firstHeight;
+            anchorSlot = slots[0];
+            span *= 2n;
+        }
+        throw (0, rpc_1.gone)(`the block at height ${height} (too far below the head)`);
+    }
+    /**
+     * One verified-shape page of produced slots from `from` to `to`, and where it starts.
+     * When the endpoint cannot list from `from` (a definitive RPC error with a JSON-RPC
+     * code: agave answers `-32602 "BigTable query failed"` below its local ledger when
+     * long-term storage fails), the page starts once more at the endpoint's first available
+     * block, when that lies inside the range (liveness only). Every other error, and a
+     * second failure, decides nothing.
+     */
+    async #page(from, to, commitment, tags) {
+        try {
+            return { from, slots: await this.#blocks(from, to, commitment, tags) };
+        }
+        catch (error) {
+            // Only an endpoint's own definitive answer: an ambiguous error, or one without a
+            // JSON-RPC code, says nothing about what this endpoint can list.
+            const first = (0, rpc_1.rpcCode)(error) === undefined ? null : await this.#firstAvailable(tags);
+            if (first === null || first <= from || first > to) {
+                throw (0, rpc_1.undecided)(error, `the blocks from slot ${from}`);
+            }
+            try {
+                return { from: first, slots: await this.#blocks(first, to, commitment, tags) };
+            }
+            catch (retry) {
+                throw (0, rpc_1.undecided)(retry, `the blocks from slot ${first}`);
+            }
+        }
+    }
+    /** The endpoint's first available block: a hint only, `null` when it cannot say. */
+    async #firstAvailable(tags) {
+        try {
+            return (0, rpc_1.u64)(await (0, rpc_1.call)(this.#transport, 'getFirstAvailableBlock', [], tags), 'getFirstAvailableBlock');
+        }
+        catch (error) {
+            if (tags.signal?.aborted)
+                throw error;
+            return null;
+        }
+    }
+    /** `getBlocks` from `from` to `to`: strictly increasing slots inside the range. */
+    async #blocks(from, to, commitment, tags) {
+        const result = await (0, rpc_1.call)(this.#transport, 'getBlocks', [Number(from), Number(to), { commitment }], tags);
+        if (!Array.isArray(result))
+            throw (0, rpc_1.malformed)('getBlocks');
+        const slots = result.map((slot) => (0, rpc_1.u64)(slot, 'getBlocks slot'));
+        for (let i = 0; i < slots.length; i++) {
+            const slot = slots[i];
+            if (slot < from || slot > to || (i > 0 && slot <= slots[i - 1])) {
+                throw (0, rpc_1.malformed)('getBlocks');
+            }
+        }
+        return slots;
+    }
+    /** Drops every cached pair: a later read contradicted one (cheap to rebuild). */
+    forget() {
+        this.#final.clear();
+    }
+    #remember(commitment, height, slot) {
+        if (commitment !== 'finalized' || this.#final.has(height))
+            return;
+        this.#final.set(height, slot);
+        if (this.#final.size > CACHE_SIZE) {
+            const oldest = this.#final.keys().next().value;
+            this.#final.delete(oldest);
+        }
+    }
+}
+exports.HeightIndex = HeightIndex;
+//# sourceMappingURL=heights.js.map

package/dist/adapters/solana/heights.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heights.js","sourceRoot":"","sources":["../../../src/adapters/solana/heights.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Dense block heights over Solana's slots: the core's heights must be dense, so they are\n * block heights, never slots. Slots can be skipped; block heights count only produced\n * blocks, so every height up to the head has exactly one block. The index maps a height\n * to its slot with `getBlocks`, which lists the produced slots of a range: anchored on a\n * known block at the head, the block `k` places before it in that list is `k` heights\n * lower.\n *\n * A list can have gaps (a ledger jump to a snapshot, a long-term-storage gap, pruning), so\n * no pair is believed until a read of the list's first block confirms its height. Only\n * finalized, verified pairs are cached (immutable chain data, the only state a shared\n * driver may keep), which makes a forward scan cost one `getBlock` per height. A height\n * the endpoint no longer holds is a retryable error that decides nothing, never `null`\n * (`null` means \"not visible yet\"). Every read is a single endpoint's view: verdicts\n * quorum-read the block at the resolved slot. Any other RPC error decides nothing either:\n * proofs reach this index, and agave answers `getBlocks` below its local ledger with\n * `-32602 \"BigTable query failed\"` when long-term storage fails. Such a page starts again\n * at the endpoint's first available block (liveness), so a height inside its ledger still\n * resolves.\n */\nimport type { Transport } from '../../core/transport/types';\nimport {\n  blockHeader,\n  call,\n  gone,\n  headerOptions,\n  inconsistent,\n  isGone,\n  isNotYet,\n  isSkipped,\n  malformed,\n  notYet,\n  rpcCode,\n  u64,\n  undecided,\n  type BlockHeader,\n} from './rpc';\nimport type { Commitment, SolanaCallTags } from './types';\n\n/** `getBlocks` accepts at most this many slots per call (agave). */\nconst MAX_RANGE = 500_000n;\n/** At most this many `getBlocks` pages below the head (about 8 M slots). */\nconst MAX_PAGES = 16;\n/** Verified finalized height → slot pairs kept per driver. */\nconst CACHE_SIZE = 8_192;\n\nexport interface HeadBlock {\n  readonly slot: bigint;\n  readonly header: BlockHeader;\n}\n\nexport class HeightIndex {\n  readonly #transport: Transport;\n  readonly #final = new Map<bigint, bigint>();\n\n  constructor(transport: Transport) {\n    this.#transport = transport;\n  }\n\n  /** The block at the endpoint's `commitment` head (one `getSlot`, one `getBlock`). */\n  async head(commitment: Commitment, tags: SolanaCallTags): Promise<HeadBlock> {\n    const slot = u64(\n      await call(this.#transport, 'getSlot', [{ commitment }], tags),\n      'getSlot',\n    );\n    const header = await this.header(slot, commitment, tags);\n    if (!header) throw notYet(`the ${commitment} head block`);\n    return { slot, header };\n  }\n\n  /**\n   * The block at `slot`, or `null` while the endpoint has not reached it at `commitment`.\n   * A pruned or missing block is a retryable error (decides nothing); a slot the endpoint\n   * calls skipped means a list named a slot with no block, so the cache is dropped.\n   */\n  async header(\n    slot: bigint,\n    commitment: Commitment,\n    tags: SolanaCallTags,\n  ): Promise<BlockHeader | null> {\n    let result: unknown;\n    try {\n      result = await call(\n        this.#transport,\n        'getBlock',\n        [Number(slot), headerOptions(commitment)],\n        tags,\n      );\n    } catch (error) {\n      if (isNotYet(error)) return null;\n      if (isGone(error)) throw gone(`the block at slot ${slot}`);\n      if (isSkipped(error)) {\n        this.forget();\n        throw inconsistent(`slot ${slot} holds no block`);\n      }\n      throw undecided(error, `the block at slot ${slot}`);\n    }\n    return result === null ? null : blockHeader(result);\n  }\n\n  /**\n   * The slot of the block at `height` on the endpoint's chain at `commitment`, or `null`\n   * while that chain has no block at `height` yet. A `confirmed` lookup at or below the\n   * endpoint's finalized height resolves on the finalized chain, which fills the cache.\n   */\n  async slotAt(\n    height: bigint,\n    commitment: Commitment,\n    tags: SolanaCallTags,\n  ): Promise<bigint | null> {\n    if (height < 0n) return null;\n    const cached = this.#final.get(height);\n    if (cached !== undefined) return cached;\n    const final = await this.head('finalized', tags);\n    if (height <= final.header.blockHeight) {\n      return this.#resolve(height, final, 'finalized', tags);\n    }\n    if (commitment === 'finalized') return null;\n    const top = await this.head('confirmed', tags);\n    if (height > top.header.blockHeight) return null;\n    return this.#resolve(height, top, 'confirmed', tags);\n  }\n\n  /** Counts back from `top` through verified `getBlocks` pages to the block at `height`. */\n  async #resolve(\n    height: bigint,\n    top: HeadBlock,\n    commitment: Commitment,\n    tags: SolanaCallTags,\n  ): Promise<bigint> {\n    let anchorSlot = top.slot;\n    let anchorHeight = top.header.blockHeight;\n    if (height === anchorHeight) return anchorSlot;\n    let span = anchorHeight - height + (anchorHeight - height) / 4n + 64n;\n    for (let page = 0; page < MAX_PAGES; page++) {\n      if (span > MAX_RANGE) span = MAX_RANGE;\n      const want = anchorSlot > span ? anchorSlot - span : 0n;\n      const { from, slots } = await this.#page(want, anchorSlot, commitment, tags);\n      const last = slots.length - 1;\n      // agave lists nothing when the range ends above what the endpoint holds at\n      // `commitment` (a backend whose root trails the anchor): that list ends nowhere.\n      if (last < 0 || slots[last] !== anchorSlot) {\n        throw inconsistent(`getBlocks does not end at slot ${anchorSlot}`);\n      }\n      // A list that adds nothing below its anchor: the endpoint holds nothing older.\n      if (last === 0) throw gone(`the block at height ${height}`);\n      // The list's first block must sit exactly `last` heights below the anchor, or\n      // the list has a gap; nothing from it is believed or cached.\n      const firstHeight = anchorHeight - BigInt(last);\n      const first = await this.header(slots[0] as bigint, commitment, tags);\n      if (!first) throw notYet(`the block at slot ${slots[0]}`);\n      if (first.blockHeight !== firstHeight) {\n        throw inconsistent(`the blocks listed below slot ${anchorSlot} have a gap`);\n      }\n      slots.forEach((slot, i) => {\n        const at = firstHeight + BigInt(i);\n        // Keep the pairs a forward scan from `height` needs next.\n        if (at >= height && at < height + BigInt(CACHE_SIZE)) {\n          this.#remember(commitment, at, slot);\n        }\n      });\n      if (height >= firstHeight) return slots[Number(height - firstHeight)] as bigint;\n      // The list started at slot 0, or at the endpoint's first available block.\n      if (from === 0n || from > want) throw gone(`the block at height ${height}`);\n      anchorHeight = firstHeight;\n      anchorSlot = slots[0] as bigint;\n      span *= 2n;\n    }\n    throw gone(`the block at height ${height} (too far below the head)`);\n  }\n\n  /**\n   * One verified-shape page of produced slots from `from` to `to`, and where it starts.\n   * When the endpoint cannot list from `from` (a definitive RPC error with a JSON-RPC\n   * code: agave answers `-32602 \"BigTable query failed\"` below its local ledger when\n   * long-term storage fails), the page starts once more at the endpoint's first available\n   * block, when that lies inside the range (liveness only). Every other error, and a\n   * second failure, decides nothing.\n   */\n  async #page(\n    from: bigint,\n    to: bigint,\n    commitment: Commitment,\n    tags: SolanaCallTags,\n  ): Promise<{ readonly from: bigint; readonly slots: bigint[] }> {\n    try {\n      return { from, slots: await this.#blocks(from, to, commitment, tags) };\n    } catch (error) {\n      // Only an endpoint's own definitive answer: an ambiguous error, or one without a\n      // JSON-RPC code, says nothing about what this endpoint can list.\n      const first =\n        rpcCode(error) === undefined ? null : await this.#firstAvailable(tags);\n      if (first === null || first <= from || first > to) {\n        throw undecided(error, `the blocks from slot ${from}`);\n      }\n      try {\n        return { from: first, slots: await this.#blocks(first, to, commitment, tags) };\n      } catch (retry) {\n        throw undecided(retry, `the blocks from slot ${first}`);\n      }\n    }\n  }\n\n  /** The endpoint's first available block: a hint only, `null` when it cannot say. */\n  async #firstAvailable(tags: SolanaCallTags): Promise<bigint | null> {\n    try {\n      return u64(\n        await call(this.#transport, 'getFirstAvailableBlock', [], tags),\n        'getFirstAvailableBlock',\n      );\n    } catch (error) {\n      if (tags.signal?.aborted) throw error;\n      return null;\n    }\n  }\n\n  /** `getBlocks` from `from` to `to`: strictly increasing slots inside the range. */\n  async #blocks(\n    from: bigint,\n    to: bigint,\n    commitment: Commitment,\n    tags: SolanaCallTags,\n  ): Promise<bigint[]> {\n    const result = await call(\n      this.#transport,\n      'getBlocks',\n      [Number(from), Number(to), { commitment }],\n      tags,\n    );\n    if (!Array.isArray(result)) throw malformed('getBlocks');\n    const slots = result.map((slot) => u64(slot, 'getBlocks slot'));\n    for (let i = 0; i < slots.length; i++) {\n      const slot = slots[i] as bigint;\n      if (slot < from || slot > to || (i > 0 && slot <= (slots[i - 1] as bigint))) {\n        throw malformed('getBlocks');\n      }\n    }\n    return slots;\n  }\n\n  /** Drops every cached pair: a later read contradicted one (cheap to rebuild). */\n  forget(): void {\n    this.#final.clear();\n  }\n\n  #remember(commitment: Commitment, height: bigint, slot: bigint): void {\n    if (commitment !== 'finalized' || this.#final.has(height)) return;\n    this.#final.set(height, slot);\n    if (this.#final.size > CACHE_SIZE) {\n      const oldest = this.#final.keys().next().value as bigint;\n      this.#final.delete(oldest);\n    }\n  }\n}\n"]}

package/dist/adapters/solana/history.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Address history from `getSignaturesForAddress`, newest first. The cursor is the
+ * last signature of a page. A token account's history holds the SPL transfers into it; an
+ * owner's history holds only the transactions that name the owner itself.
+ */
+import type { AddressHistorySource } from '../../core/driver/types';
+import { type SolanaContext } from './reader';
+/** `getSignaturesForAddress` returns at most this many signatures per call (agave). */
+export declare const MAX_HISTORY_PAGE = 1000;
+export declare function createSolanaHistory(ctx: SolanaContext): AddressHistorySource;

package/dist/adapters/solana/history.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_HISTORY_PAGE = void 0;
+exports.createSolanaHistory = createSolanaHistory;
+const error_1 = require("../../core/errors/error");
+const decode_1 = require("./decode");
+const keys_1 = require("./keys");
+const reader_1 = require("./reader");
+const rpc_1 = require("./rpc");
+/** `getSignaturesForAddress` returns at most this many signatures per call (agave). */
+exports.MAX_HISTORY_PAGE = 1_000;
+function createSolanaHistory(ctx) {
+    return {
+        async list(address, { cursor, limit }) {
+            if (cursor !== undefined && !(0, keys_1.isSignature)(cursor)) {
+                throw new error_1.ValidationError('INVALID_INTENT', 'not a Solana history cursor');
+            }
+            const size = Math.min(limit, exports.MAX_HISTORY_PAGE);
+            let result;
+            try {
+                result = await (0, rpc_1.call)(ctx.transport, 'getSignaturesForAddress', [
+                    address,
+                    {
+                        limit: size,
+                        commitment: 'confirmed',
+                        ...(cursor !== undefined ? { before: cursor } : {}),
+                    },
+                ], rpc_1.READ);
+            }
+            catch (error) {
+                // A backend that does not hold the cursor's transaction (another backend behind a
+                // load balancer, or a pruned one) answers -32020. That decides nothing: another
+                // backend may hold it.
+                if ((0, rpc_1.rpcCode)(error) === rpc_1.RPC_CODES.FILTER_TRANSACTION_NOT_FOUND) {
+                    // The node's error stays reachable: its cause and where it happened.
+                    throw new error_1.ProviderError('PROVIDER_UNAVAILABLE', 'the endpoint does not know the history cursor', { cause: error, context: error.context });
+                }
+                throw error;
+            }
+            if (!Array.isArray(result))
+                throw (0, rpc_1.malformed)('getSignaturesForAddress');
+            const signatures = result.map((entry) => {
+                const signature = entry?.signature;
+                if (!(0, keys_1.isSignature)(signature))
+                    throw (0, rpc_1.malformed)('getSignaturesForAddress');
+                return signature;
+            });
+            const items = [];
+            for (const signature of signatures) {
+                const found = await (0, reader_1.readTransaction)(ctx, signature, rpc_1.READ);
+                if (!found)
+                    throw (0, rpc_1.inconsistent)('a listed transaction is missing');
+                items.push((0, decode_1.decodeTransaction)(found.parsed, {
+                    height: found.header.blockHeight,
+                    hash: found.header.blockhash,
+                    ...(found.parsed.blockTime !== undefined
+                        ? { blockTime: found.parsed.blockTime }
+                        : {}),
+                }));
+            }
+            // Paged on the raw page: only a page shorter than asked ends the history, and one
+            // longer than asked never does.
+            const last = signatures[signatures.length - 1];
+            return {
+                items,
+                ...(signatures.length >= size && last !== undefined ? { next: last } : {}),
+            };
+        },
+    };
+}
+//# sourceMappingURL=history.js.map

package/dist/adapters/solana/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../../src/adapters/solana/history.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Address history from `getSignaturesForAddress`, newest first. The cursor is the\n * last signature of a page. A token account's history holds the SPL transfers into it; an\n * owner's history holds only the transactions that name the owner itself.\n */\nimport type { AddressHistorySource, DriverTransaction } from '../../core/driver/types';\nimport {\n  ProviderError,\n  ValidationError,\n  type CryptoAioError,\n} from '../../core/errors/error';\nimport { decodeTransaction } from './decode';\nimport { isSignature } from './keys';\nimport { readTransaction, type SolanaContext } from './reader';\nimport { READ, RPC_CODES, call, inconsistent, malformed, rpcCode } from './rpc';\n\n/** `getSignaturesForAddress` returns at most this many signatures per call (agave). */\nexport const MAX_HISTORY_PAGE = 1_000;\n\nexport function createSolanaHistory(ctx: SolanaContext): AddressHistorySource {\n  return {\n    async list(address, { cursor, limit }) {\n      if (cursor !== undefined && !isSignature(cursor)) {\n        throw new ValidationError('INVALID_INTENT', 'not a Solana history cursor');\n      }\n      const size = Math.min(limit, MAX_HISTORY_PAGE);\n      let result: unknown;\n      try {\n        result = await call(\n          ctx.transport,\n          'getSignaturesForAddress',\n          [\n            address,\n            {\n              limit: size,\n              commitment: 'confirmed',\n              ...(cursor !== undefined ? { before: cursor } : {}),\n            },\n          ],\n          READ,\n        );\n      } catch (error) {\n        // A backend that does not hold the cursor's transaction (another backend behind a\n        // load balancer, or a pruned one) answers -32020. That decides nothing: another\n        // backend may hold it.\n        if (rpcCode(error) === RPC_CODES.FILTER_TRANSACTION_NOT_FOUND) {\n          // The node's error stays reachable: its cause and where it happened.\n          throw new ProviderError(\n            'PROVIDER_UNAVAILABLE',\n            'the endpoint does not know the history cursor',\n            { cause: error, context: (error as CryptoAioError).context },\n          );\n        }\n        throw error;\n      }\n      if (!Array.isArray(result)) throw malformed('getSignaturesForAddress');\n      const signatures = result.map((entry: unknown) => {\n        const signature = (entry as { signature?: unknown } | null)?.signature;\n        if (!isSignature(signature)) throw malformed('getSignaturesForAddress');\n        return signature;\n      });\n      const items: DriverTransaction[] = [];\n      for (const signature of signatures) {\n        const found = await readTransaction(ctx, signature, READ);\n        if (!found) throw inconsistent('a listed transaction is missing');\n        items.push(\n          decodeTransaction(found.parsed, {\n            height: found.header.blockHeight,\n            hash: found.header.blockhash,\n            ...(found.parsed.blockTime !== undefined\n              ? { blockTime: found.parsed.blockTime }\n              : {}),\n          }),\n        );\n      }\n      // Paged on the raw page: only a page shorter than asked ends the history, and one\n      // longer than asked never does.\n      const last = signatures[signatures.length - 1];\n      return {\n        items,\n        ...(signatures.length >= size && last !== undefined ? { next: last } : {}),\n      };\n    },\n  };\n}\n"]}

package/dist/adapters/solana/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `crypto-aio/solana`: the SDK-free Solana types, and the `crypto-aio/native` client type:
+ * importing this entry types `native(bc, '@solana/web3.js')` as a `Connection` wired to the
+ * handle's transport (HTTP JSON-RPC only; subscriptions have no transport bridge).
+ *
+ * @module crypto-aio/solana
+ */
+import type { Connection } from '@solana/web3.js';
+declare module '../../index' {
+    interface NativeClientMap {
+        '@solana/web3.js': Connection;
+    }
+}
+export { SOLANA_PEER_DEPENDENCIES } from './plugin';
+export { DEFAULT_MAX_COMPUTE_UNIT_PRICE, SOLANA_CAPABILITIES } from './network';
+export type { SolanaExpiryOrdering, SolanaExt, SolanaFeeDetails, SolanaFeeOverride, SolanaTokenAccount, } from './types';

package/dist/adapters/solana/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOLANA_CAPABILITIES = exports.DEFAULT_MAX_COMPUTE_UNIT_PRICE = exports.SOLANA_PEER_DEPENDENCIES = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "SOLANA_PEER_DEPENDENCIES", { enumerable: true, get: function () { return plugin_1.SOLANA_PEER_DEPENDENCIES; } });
+var network_1 = require("./network");
+Object.defineProperty(exports, "DEFAULT_MAX_COMPUTE_UNIT_PRICE", { enumerable: true, get: function () { return network_1.DEFAULT_MAX_COMPUTE_UNIT_PRICE; } });
+Object.defineProperty(exports, "SOLANA_CAPABILITIES", { enumerable: true, get: function () { return network_1.SOLANA_CAPABILITIES; } });
+//# sourceMappingURL=index.js.map

package/dist/adapters/solana/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/solana/index.ts"],"names":[],"mappings":";;;AAiBA,mCAAoD;AAA3C,kHAAA,wBAAwB,OAAA;AACjC,qCAAgF;AAAvE,yHAAA,8BAA8B,OAAA;AAAE,8GAAA,mBAAmB,OAAA","sourcesContent":["/**\n * `crypto-aio/solana`: the SDK-free Solana types, and the `crypto-aio/native` client type:\n * importing this entry types `native(bc, '@solana/web3.js')` as a `Connection` wired to the\n * handle's transport (HTTP JSON-RPC only; subscriptions have no transport bridge).\n *\n * @module crypto-aio/solana\n */\nimport type { Connection } from '@solana/web3.js';\n\n// Augments the package entry's map. SDK types appear only here, so the main entry's\n// typings name no SDK.\ndeclare module '../../index' {\n  interface NativeClientMap {\n    '@solana/web3.js': Connection;\n  }\n}\n\nexport { SOLANA_PEER_DEPENDENCIES } from './plugin';\nexport { DEFAULT_MAX_COMPUTE_UNIT_PRICE, SOLANA_CAPABILITIES } from './network';\nexport type {\n  SolanaExpiryOrdering,\n  SolanaExt,\n  SolanaFeeDetails,\n  SolanaFeeOverride,\n  SolanaTokenAccount,\n} from './types';\n"]}