@scalecrx/sdk 0.4.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,269 @@
+# Scale SDK
+
+TypeScript SDK for Scale AMM and Scale VMM.
+
+## Install
+
+```bash
+npm install @scalecrx/sdk @coral-xyz/anchor @solana/web3.js
+```
+
+## Constants
+
+```ts
+import { AMM_ADDRESS, VMM_ADDRESS, CLUSTER_RPC_URLS } from "@scalecrx/sdk";
+```
+
+- `AMM_ADDRESS` => `SCALEwAvEK5gtkdHiFzXfPgtk2YwJxPDzaV3aDmR7tA`
+- `VMM_ADDRESS` => `SCALEWoRSpVZpMRqHEcDfNvBh3nUSe34jDr9r689gLa`
+
+## Constructors
+
+### 1) RPC URL overload
+
+```ts
+import { Scale } from "@scalecrx/sdk";
+
+const sdk = new Scale("https://my-rpc.example.com", walletOptional);
+```
+
+### 2) Cluster overload (`"devnet" | "mainnet"`)
+
+```ts
+import { Scale } from "@scalecrx/sdk";
+
+const sdkDevnet = new Scale("devnet", walletOptional); // uses https://api.devnet.solana.com
+const sdkMainnet = new Scale("mainnet", walletOptional); // uses https://api.mainnet-beta.solana.com
+```
+
+If wallet is omitted, read-only and instruction-building flows still work, but direct execution methods throw.
+
+## Execution vs Instruction Builders
+
+Every write flow has two styles:
+
+1. **Execute now** (requires wallet):
+
+```ts
+await sdk.amm.buy(poolAddress, { amount: 1_000, limit: 1 }, opts);
+```
+
+2. **Return instructions only** (no send):
+
+```ts
+const bundle = await sdk.amm.buyInstructions(poolAddress, { amount: 1_000, limit: 1 }, opts);
+// bundle.instructions -> add to Transaction yourself
+```
+
+Same pattern exists for AMM and VMM (`buy/sell/create*`, plus config instruction builders).
+
+## Supported Curves (on-chain)
+
+Pool/pair creation supports exactly two curve configs:
+
+- `constantProduct`: standard x*y=k style curve.
+- `exponential`: steeper curve profile than constant product for the same inputs.
+
+Use one of:
+
+```ts
+{ constantProduct: {} }
+// or
+{ exponential: {} }
+```
+
+## Parameter Reference
+
+### Common numeric types
+
+- Most numeric args are `number | BN`.
+- On-chain values are integer base units (raw token units), not UI decimals.
+
+### Creation params (`CreatePoolParamsInput` / `CreatePairParamsInput`)
+
+- `shift`: virtual token A liquidity shift used by curve math.
+- `initialTokenBReserves`: initial token B reserves deposited for create.
+- `curve`: `{ constantProduct: {} } | { exponential: {} }`.
+- `feeBeneficiaries`: array of `{ wallet: PublicKey, shareBps: number }`.
+
+### Create options (AMM: `CreatePoolOptions`, VMM: `CreatePairOptions`)
+
+- `payer?`: transaction payer (defaults to SDK wallet public key).
+- `owner?` (AMM only): pool owner PDA seed input (defaults to SDK wallet).
+- `tokenWalletB?`: token B source account for create.
+- `tokenWalletAuthority?`: authority for `tokenWalletB` transfers.
+- `signers?`: extra signers appended to returned bundle/send.
+
+### Swap params (`SwapParamsInput`)
+
+- `amount`: input amount in raw units.
+- `limit`: slippage guard / minimum-out style bound enforced by program.
+
+### Swap options (`SwapOptions`)
+
+- `userTokenAccountA?`, `userTokenAccountB?`: user token accounts override.
+- `platformFeeTokenAccount?`: explicit platform fee token A account.
+- `beneficiaryTokenAccounts?`: explicit creator fee accounts (order-sensitive).
+- `wrapSol?`: wrap SOL into WSOL before swap when mint A is native.
+- `unwrapSol?`: unwrap WSOL after swap when mint A is native.
+- `autoCreateAta?`: auto-create missing ATAs (default true).
+
+### VMM swap extension (`VmmSwapOptions`)
+
+In addition to `SwapOptions`, VMM accepts AMM-routing overrides used for graduation-aware paths:
+
+- `ammProgramId?`, `ammPool?`, `ammVaultA?`, `ammVaultB?`
+- `ammConfig?`, `ammTokenProgramA?`, `ammTokenProgramB?`, `ammSystemProgram?`
+
+### Graduation status check
+
+```ts
+const pair = await sdk.vmm.getPairByMints(mintA, mintB);
+const isGraduated = pair.data.graduated;
+```
+
+### SDK constructor options (`ScaleOptions`)
+
+- `ammProgramId?`, `vmmProgramId?`: override default vanity program IDs.
+- `ammIdl?`, `vmmIdl?`: IDL overrides.
+- `programId?`, `idl?`: legacy AMM alias fallback.
+- `providerOptions?`: Anchor provider confirmation/preflight options.
+
+## AMM quick usage
+
+```ts
+const config = await sdk.amm.getPlatformConfig();
+const pool = await sdk.amm.getPoolByMints(owner, mintA, mintB);
+const quote = await sdk.amm.estimateBuy(pool.address, { amount: 10_000, limit: 1 });
+```
+
+```ts
+const createBundle = await sdk.amm.createPoolInstructions(
+  {
+    shift: 1_000_000,
+    initialTokenBReserves: 100_000,
+    curve: { constantProduct: {} },
+    feeBeneficiaries: [],
+  },
+  mintA,
+  mintB,
+  {
+    payer,
+    owner,
+    tokenWalletB,
+    tokenWalletAuthority,
+  }
+);
+
+const swapBundle = await sdk.amm.buyInstructions(
+  poolAddress,
+  { amount: 10_000, limit: 1 },
+  {
+    userTokenAccountA,
+    userTokenAccountB,
+    platformFeeTokenAccount,
+    beneficiaryTokenAccounts,
+    wrapSol: true,
+    unwrapSol: false,
+    autoCreateAta: true,
+  }
+);
+```
+
+## VMM quick usage
+
+```ts
+const config = await sdk.vmm.getPlatformConfig();
+const pair = await sdk.vmm.getPairByMints(mintA, mintB);
+const quote = await sdk.vmm.estimateSell(pair.address, { amount: 10_000, limit: 1 });
+```
+
+```ts
+const createBundle = await sdk.vmm.createPairInstructions(
+  {
+    shift: 1_000_000,
+    initialTokenBReserves: 100_000,
+    curve: { exponential: {} },
+    feeBeneficiaries: [],
+  },
+  mintA,
+  mintB,
+  {
+    payer,
+    tokenWalletB,
+    tokenWalletAuthority,
+  }
+);
+
+const swapBundle = await sdk.vmm.sellInstructions(
+  pairAddress,
+  { amount: 10_000, limit: 1 },
+  {
+    userTokenAccountA,
+    userTokenAccountB,
+    platformFeeTokenAccount,
+    beneficiaryTokenAccounts,
+    autoCreateAta: true,
+  }
+);
+```
+
+## Public API map
+
+### `Scale`
+- `new Scale(connection, wallet, options)`
+- `new Scale(rpcUrl, wallet?, options?)`
+- `new Scale("devnet" | "mainnet", wallet?, options?)`
+- `amm`, `vmm`, `loadAmm`, `loadVmm`
+  - `loadAmm(programId?, idlOverride?)`
+  - `loadVmm(programId?, idlOverride?)`
+
+### `ScaleAmm`
+- Read-only: `getConfigAddress`, `getPoolAddress`, `getVaultAddress`, `getPlatformConfig`, `getPlatformBaseToken`, `getPool*`, `getFee*`, `estimateBuy`, `estimateSell`
+- Execute: `createPool`, `buy`, `sell`
+- Instruction builders: `createPoolInstructions`, `createWithDevBuyInstructions`, `buyInstructions`, `sellInstructions`
+  - `createPool(params, mintA, mintB, options?)`
+  - `createPoolInstructions(params, mintA, mintB, options?)`
+  - `createWithDevBuyInstructions(params, mintA, mintB, buyParams, options?)`
+  - `buy(poolInput, params, options?)`
+  - `sell(poolInput, params, options?)`
+  - `buyInstructions(poolInput, params, options?)`
+  - `sellInstructions(poolInput, params, options?)`
+
+### `ScaleVmm`
+- Read-only: `getConfigAddress`, `getPairAddress`, `getVaultAddress`, `getAmmPoolAddress`, `getAmmVaultAddress`, `getPlatformConfig`, `getPlatformConfigView`, `getPlatformBaseToken`, `getGraduationThreshold`, `getPair*`, `getFee*`, `estimateBuy`, `estimateSell`
+- Execute: `setGraduationThreshold`, `createPair`, `buy`, `sell`
+- Instruction builders: `setGraduationThresholdInstruction`, `createPairInstructions`, `createWithDevBuyInstructions`, `buyInstructions`, `sellInstructions`
+  - `setGraduationThreshold(threshold)`
+  - `setGraduationThresholdInstruction(threshold)`
+  - `createPair(params, mintA, mintB, options?)`
+  - `createPairInstructions(params, mintA, mintB, options?)`
+  - `createWithDevBuyInstructions(params, mintA, mintB, buyParams, options?)`
+  - `buy(pairInput, params, options?)`
+  - `sell(pairInput, params, options?)`
+  - `buyInstructions(pairInput, params, options?)`
+  - `sellInstructions(pairInput, params, options?)`
+
+## Agent Use
+
+Use this prompt in your AI coding agent to integrate an existing project with Scale SDK:
+
+```text
+Integrate Scale SDK into this project end-to-end using the official docs:
+https://github.com/scalecrx/sdk/blob/main/README.md
+
+Requirements:
+1. Install and configure @scalecrx/sdk and required Solana/Anchor dependencies.
+2. Detect this project’s package manager, TypeScript setup, and runtime (Node/server/client), then implement integration in the correct layer.
+3. Add a reusable Scale client module and environment-driven RPC/network configuration.
+4. Implement at least one read flow (platform config + pair/pool fetch/quote) and one transaction instruction-building flow using this SDK.
+5. If wallet execution is not available in this project context, use instruction builders only and wire outputs for external signing.
+6. Keep all amounts in raw base units (not UI decimals) and add safe input validation.
+7. Add/update minimal docs in this repo explaining how to run and use the integration.
+8. Run build/typecheck/tests (if present) and fix any issues caused by the integration.
+
+Output format:
+- Summary of files changed and why
+- Exact commands run
+- Any assumptions or follow-up tasks
+```

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+import { PublicKey } from "@solana/web3.js";
+export declare const AMM_ADDRESS: PublicKey;
+export declare const VMM_ADDRESS: PublicKey;
+export declare const CLUSTER_RPC_URLS: {
+    readonly devnet: "https://api.devnet.solana.com";
+    readonly mainnet: "https://api.mainnet-beta.solana.com";
+};
+export type ScaleCluster = keyof typeof CLUSTER_RPC_URLS;

package/dist/constants.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLUSTER_RPC_URLS = exports.VMM_ADDRESS = exports.AMM_ADDRESS = void 0;
+const web3_js_1 = require("@solana/web3.js");
+exports.AMM_ADDRESS = new web3_js_1.PublicKey("SCALEwAvEK5gtkdHiFzXfPgtk2YwJxPDzaV3aDmR7tA");
+exports.VMM_ADDRESS = new web3_js_1.PublicKey("SCALEWoRSpVZpMRqHEcDfNvBh3nUSe34jDr9r689gLa");
+exports.CLUSTER_RPC_URLS = {
+    devnet: "https://api.devnet.solana.com",
+    mainnet: "https://api.mainnet-beta.solana.com",
+};

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+export declare class ScaleSdkError extends Error {
+    readonly context: string;
+    readonly cause: unknown;
+    readonly logs?: string[];
+    readonly code?: string;
+    readonly number?: number;
+    constructor(message: string, context: string, cause: unknown, details?: {
+        logs?: string[];
+        code?: string;
+        number?: number;
+    });
+}
+export declare const toSdkError: (context: string, err: unknown, idlErrors: Map<number, string>) => ScaleSdkError;

package/dist/errors.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSdkError = exports.ScaleSdkError = void 0;
+const anchor_1 = require("@coral-xyz/anchor");
+class ScaleSdkError extends Error {
+    constructor(message, context, cause, details) {
+        super(message);
+        this.name = "ScaleSdkError";
+        this.context = context;
+        this.cause = cause;
+        this.logs = details?.logs;
+        this.code = details?.code;
+        this.number = details?.number;
+    }
+}
+exports.ScaleSdkError = ScaleSdkError;
+const toSdkError = (context, err, idlErrors) => {
+    if (err instanceof ScaleSdkError) {
+        return err;
+    }
+    const translated = (0, anchor_1.translateError)(err, idlErrors);
+    if (translated instanceof anchor_1.AnchorError) {
+        return new ScaleSdkError(`${context}: ${translated.message}`, context, err, {
+            logs: translated.logs,
+            code: translated.error.errorCode.code,
+            number: translated.error.errorCode.number,
+        });
+    }
+    if (translated instanceof Error) {
+        return new ScaleSdkError(`${context}: ${translated.message}`, context, err);
+    }
+    return new ScaleSdkError(`${context}: Unknown error`, context, err);
+};
+exports.toSdkError = toSdkError;