@loyal-labs/transactions 0.1.0

package/dist/src/idl.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Bundled IDL for the Telegram Transfer program
+ * Program ID: 4ewpzEPF5xrVAHeRkoe7XS1yKFGQBekD7PgFwEz9SaxY
+ */
+/**
+ * Program IDL type definition (camelCase for JS/TS usage)
+ */
+export type TelegramTransfer = {
+    address: "4ewpzEPF5xrVAHeRkoe7XS1yKFGQBekD7PgFwEz9SaxY";
+    metadata: {
+        name: "telegramTransfer";
+        version: "0.1.0";
+        spec: "0.1.0";
+        description: "Created with Anchor";
+    };
+    instructions: [
+        {
+            name: "claimDeposit";
+            discriminator: [201, 106, 1, 224, 122, 144, 210, 155];
+            accounts: [
+                {
+                    name: "recipient";
+                    docs: ["can be a new address"];
+                    writable: true;
+                },
+                {
+                    name: "vault";
+                    writable: true;
+                    pda: {
+                        seeds: [
+                            {
+                                kind: "const";
+                                value: [118, 97, 117, 108, 116];
+                            }
+                        ];
+                    };
+                },
+                {
+                    name: "deposit";
+                    writable: true;
+                    pda: {
+                        seeds: [
+                            {
+                                kind: "const";
+                                value: [100, 101, 112, 111, 115, 105, 116];
+                            },
+                            {
+                                kind: "account";
+                                path: "deposit.user";
+                                account: "deposit";
+                            },
+                            {
+                                kind: "account";
+                                path: "deposit.username";
+                                account: "deposit";
+                            }
+                        ];
+                    };
+                },
+                {
+                    name: "session";
+                },
+                {
+                    name: "systemProgram";
+                    address: "11111111111111111111111111111111";
+                }
+            ];
+            args: [
+                {
+                    name: "amount";
+                    type: "u64";
+                }
+            ];
+        },
+        {
+            name: "depositForUsername";
+            discriminator: [85, 11, 120, 21, 51, 229, 125, 220];
+            accounts: [
+                {
+                    name: "payer";
+                    writable: true;
+                    signer: true;
+                },
+                {
+                    name: "depositor";
+                    writable: true;
+                    signer: true;
+                },
+                {
+                    name: "vault";
+                    writable: true;
+                    pda: {
+                        seeds: [
+                            {
+                                kind: "const";
+                                value: [118, 97, 117, 108, 116];
+                            }
+                        ];
+                    };
+                },
+                {
+                    name: "deposit";
+                    writable: true;
+                    pda: {
+                        seeds: [
+                            {
+                                kind: "const";
+                                value: [100, 101, 112, 111, 115, 105, 116];
+                            },
+                            {
+                                kind: "account";
+                                path: "depositor";
+                            },
+                            {
+                                kind: "arg";
+                                path: "username";
+                            }
+                        ];
+                    };
+                },
+                {
+                    name: "systemProgram";
+                    address: "11111111111111111111111111111111";
+                }
+            ];
+            args: [
+                {
+                    name: "username";
+                    type: "string";
+                },
+                {
+                    name: "amount";
+                    type: "u64";
+                }
+            ];
+        },
+        {
+            name: "refundDeposit";
+            discriminator: [19, 19, 78, 50, 187, 10, 162, 229];
+            accounts: [
+                {
+                    name: "depositor";
+                    writable: true;
+                    signer: true;
+                },
+                {
+                    name: "vault";
+                    writable: true;
+                    pda: {
+                        seeds: [
+                            {
+                                kind: "const";
+                                value: [118, 97, 117, 108, 116];
+                            }
+                        ];
+                    };
+                },
+                {
+                    name: "deposit";
+                    writable: true;
+                    pda: {
+                        seeds: [
+                            {
+                                kind: "const";
+                                value: [100, 101, 112, 111, 115, 105, 116];
+                            },
+                            {
+                                kind: "account";
+                                path: "depositor";
+                            },
+                            {
+                                kind: "account";
+                                path: "deposit.username";
+                                account: "deposit";
+                            }
+                        ];
+                    };
+                }
+            ];
+            args: [
+                {
+                    name: "amount";
+                    type: "u64";
+                }
+            ];
+        }
+    ];
+    accounts: [
+        {
+            name: "deposit";
+            discriminator: [148, 146, 121, 66, 207, 173, 21, 227];
+        },
+        {
+            name: "telegramSession";
+            discriminator: [166, 166, 101, 241, 97, 253, 72, 138];
+        },
+        {
+            name: "vault";
+            discriminator: [211, 8, 232, 43, 2, 152, 117, 119];
+        }
+    ];
+    errors: [
+        {
+            code: 6000;
+            name: "overflow";
+            msg: "overflow";
+        },
+        {
+            code: 6001;
+            name: "insufficientVault";
+            msg: "Insufficient Vault";
+        },
+        {
+            code: 6002;
+            name: "insufficientDeposit";
+            msg: "Insufficient Deposit";
+        },
+        {
+            code: 6003;
+            name: "notVerified";
+            msg: "Not Verified";
+        },
+        {
+            code: 6004;
+            name: "expiredSignature";
+            msg: "Expired Signature";
+        },
+        {
+            code: 6005;
+            name: "replay";
+            msg: "replay";
+        },
+        {
+            code: 6006;
+            name: "invalidEd25519";
+            msg: "Invalid Ed25519";
+        },
+        {
+            code: 6007;
+            name: "invalidUsername";
+            msg: "Invalid Username";
+        },
+        {
+            code: 6008;
+            name: "invalidRecipient";
+            msg: "Invalid Recipient";
+        },
+        {
+            code: 6009;
+            name: "invalidDepositor";
+            msg: "Invalid Depositor";
+        }
+    ];
+    types: [
+        {
+            name: "deposit";
+            docs: ["A deposit account for a user and token mint."];
+            type: {
+                kind: "struct";
+                fields: [
+                    {
+                        name: "user";
+                        type: "pubkey";
+                    },
+                    {
+                        name: "username";
+                        type: "string";
+                    },
+                    {
+                        name: "amount";
+                        type: "u64";
+                    },
+                    {
+                        name: "lastNonce";
+                        type: "u64";
+                    }
+                ];
+            };
+        },
+        {
+            name: "telegramSession";
+            type: {
+                kind: "struct";
+                fields: [
+                    {
+                        name: "userWallet";
+                        type: "pubkey";
+                    },
+                    {
+                        name: "username";
+                        type: "string";
+                    },
+                    {
+                        name: "validationBytes";
+                        type: "bytes";
+                    },
+                    {
+                        name: "verified";
+                        type: "bool";
+                    },
+                    {
+                        name: "authAt";
+                        type: "u64";
+                    },
+                    {
+                        name: "verifiedAt";
+                        type: {
+                            option: "u64";
+                        };
+                    }
+                ];
+            };
+        },
+        {
+            name: "vault";
+            docs: ["A vault storing deposited SOL."];
+            type: {
+                kind: "struct";
+                fields: [
+                    {
+                        name: "bump";
+                        type: "u8";
+                    },
+                    {
+                        name: "totalDeposited";
+                        type: "u64";
+                    }
+                ];
+            };
+        }
+    ];
+};
+/**
+ * Bundled IDL constant for the Telegram Transfer program
+ */
+export declare const IDL: TelegramTransfer;

package/dist/src/pda.d.ts

@@ -0,0 +1,17 @@
+import { PublicKey } from "@solana/web3.js";
+/**
+ * Derive the deposit PDA for a user and username
+ *
+ * @param depositor - The depositor's public key
+ * @param username - The Telegram username
+ * @param programId - Optional program ID (defaults to PROGRAM_ID)
+ * @returns [PDA address, bump seed]
+ */
+export declare function findDepositPda(depositor: PublicKey, username: string, programId?: PublicKey): [PublicKey, number];
+/**
+ * Derive the vault PDA
+ *
+ * @param programId - Optional program ID (defaults to PROGRAM_ID)
+ * @returns [PDA address, bump seed]
+ */
+export declare function findVaultPda(programId?: PublicKey): [PublicKey, number];

package/dist/src/types.d.ts

@@ -0,0 +1,65 @@
+import type { PublicKey, Transaction, VersionedTransaction, Keypair, Commitment } from "@solana/web3.js";
+import type { AnchorProvider } from "@coral-xyz/anchor";
+/**
+ * Minimal wallet interface matching @solana/wallet-adapter-base
+ * Compatible with browser wallet adapters (Phantom, Solflare, etc.)
+ */
+export interface WalletLike {
+    publicKey: PublicKey;
+    signTransaction<T extends Transaction | VersionedTransaction>(tx: T): Promise<T>;
+    signAllTransactions<T extends Transaction | VersionedTransaction>(txs: T[]): Promise<T[]>;
+}
+/**
+ * Union type supporting multiple wallet types:
+ * - WalletLike: Browser wallet adapters (Phantom, Solflare, etc.)
+ * - Keypair: Server-side scripts and testing
+ * - AnchorProvider: Existing Anchor projects
+ */
+export type WalletSigner = WalletLike | Keypair | AnchorProvider;
+/**
+ * Parameters for depositing SOL for a Telegram username
+ */
+export interface DepositParams {
+    /** Telegram username (without @, 5-32 characters) */
+    username: string;
+    /** Amount in lamports to deposit */
+    amountLamports: number | bigint;
+    /** Transaction commitment level (default: 'confirmed') */
+    commitment?: Commitment;
+}
+/**
+ * Result of a successful deposit transaction
+ */
+export interface DepositResult {
+    /** Transaction signature */
+    signature: string;
+    /** Updated deposit account data */
+    deposit: DepositData;
+}
+/**
+ * Deposit account data structure
+ */
+export interface DepositData {
+    /** Wallet address of the depositor */
+    user: PublicKey;
+    /** Telegram username */
+    username: string;
+    /** Total deposited amount in lamports */
+    amount: number;
+    /** Last nonce used (for replay protection) */
+    lastNonce: number;
+    /** PDA address of the deposit account */
+    address: PublicKey;
+}
+/**
+ * Check if signer is a raw Keypair
+ */
+export declare function isKeypair(signer: WalletSigner): signer is Keypair;
+/**
+ * Check if signer is an AnchorProvider
+ */
+export declare function isAnchorProvider(signer: WalletSigner): signer is AnchorProvider;
+/**
+ * Check if signer is a WalletLike (wallet adapter)
+ */
+export declare function isWalletLike(signer: WalletSigner): signer is WalletLike;

package/dist/src/wallet-adapter.d.ts

@@ -0,0 +1,31 @@
+import { PublicKey, Transaction, VersionedTransaction } from "@solana/web3.js";
+import { type WalletSigner, type WalletLike } from "./types";
+/**
+ * Internal wallet adapter that normalizes different wallet types
+ * to a common interface compatible with AnchorProvider
+ */
+export declare class InternalWalletAdapter implements WalletLike {
+    private readonly signer;
+    readonly publicKey: PublicKey;
+    private constructor();
+    /**
+     * Create an adapter from any supported wallet type
+     */
+    static from(signer: WalletSigner): InternalWalletAdapter;
+    /**
+     * Extract public key from any supported wallet type
+     */
+    static getPublicKey(signer: WalletSigner): PublicKey;
+    /**
+     * Sign a single transaction
+     */
+    signTransaction<T extends Transaction | VersionedTransaction>(tx: T): Promise<T>;
+    /**
+     * Sign multiple transactions
+     */
+    signAllTransactions<T extends Transaction | VersionedTransaction>(txs: T[]): Promise<T[]>;
+    /**
+     * Sign a transaction with a Keypair
+     */
+    private signWithKeypair;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@loyal-labs/transactions",
+  "version": "0.1.0",
+  "description": "SDK for Telegram-based Solana deposits",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build ./index.ts --outdir ./dist --target node --format esm --external @coral-xyz/anchor --external @solana/web3.js --external bn.js",
+    "build:types": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "clean": "rm -rf dist",
+    "test": "bun test"
+  },
+  "keywords": [
+    "solana",
+    "telegram",
+    "anchor",
+    "web3",
+    "crypto",
+    "blockchain",
+    "deposit",
+    "transfer"
+  ],
+  "author": "Loyal",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/loyal/solana-telegram-transactions.git",
+    "directory": "sdk/transactions"
+  },
+  "bugs": {
+    "url": "https://github.com/loyal/solana-telegram-transactions/issues"
+  },
+  "homepage": "https://github.com/loyal/solana-telegram-transactions/tree/main/sdk/transactions#readme",
+  "peerDependencies": {
+    "@coral-xyz/anchor": "^0.32.0",
+    "@solana/web3.js": "^1.95.0"
+  },
+  "devDependencies": {
+    "@coral-xyz/anchor": "^0.32.1",
+    "@solana/web3.js": "^1.95.0",
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}