@atomiqlabs/chain-starknet 8.5.0 → 8.5.1

package/dist/index.d.ts

@@ -15,5 +15,6 @@ export { StarknetSuccessAction, StarknetSwapData } from "./starknet/swaps/Starkn
 export * from "./starknet/wallet/StarknetSigner";
 export * from "./starknet/wallet/StarknetBrowserSigner";
 export * from "./starknet/wallet/accounts/StarknetKeypairWallet";
+export * from "./starknet/wallet/accounts/DeployedStarkCurveWallet";
 export * from "./starknet/StarknetChainType";
 export * from "./starknet/StarknetInitializer";

package/dist/index.js

@@ -109,5 +109,6 @@ Object.defineProperty(exports, "StarknetSwapData", { enumerable: true, get: func
 __exportStar(require("./starknet/wallet/StarknetSigner"), exports);
 __exportStar(require("./starknet/wallet/StarknetBrowserSigner"), exports);
 __exportStar(require("./starknet/wallet/accounts/StarknetKeypairWallet"), exports);
+__exportStar(require("./starknet/wallet/accounts/DeployedStarkCurveWallet"), exports);
 __exportStar(require("./starknet/StarknetChainType"), exports);
 __exportStar(require("./starknet/StarknetInitializer"), exports);

package/dist/starknet/wallet/accounts/DeployedStarkCurveWallet.d.ts

@@ -0,0 +1,68 @@
+import { Account, DeployAccountContractPayload, Provider, TypedData } from "starknet";
+/**
+ * Thrown when the target account is not deployed on-chain, so its signature rules can't be checked.
+ */
+export declare class AccountNotDeployedError extends Error {
+    readonly address: string;
+    constructor(address: string);
+}
+/**
+ * Thrown when the deployed account rejects a signature from the key (wrong key, or a scheme a single Stark-curve key can't satisfy, e.g. multisig/guardian/secp256r1).
+ */
+export declare class WalletVerificationError extends Error {
+    readonly address: string;
+    constructor(address: string);
+}
+/**
+ * Wallet for an already-deployed Starknet account controlled by a single Stark-curve private key,
+ *  bound to an explicit `address` (Starknet addresses depend on the account class hash, so a key
+ *  maps to a different address per wallet vendor). Never self-deploys.
+ *
+ * Use this when bringing in the key from an already deployed wallet account (Braavos, Xverse or Argent/Ready wallets).
+ *
+ * If you are creating a new wallet consider using {@link StarknetKeypairWallet}.
+ *
+ * @remarks Prefer {@link createAndVerify}, or call {@link verifyWallet} before use after using the constructor,
+ *  these perform an actual check on whether a given key actually controls the wallet account at a given address.
+ *
+ * @category Wallets
+ */
+export declare class DeployedStarkCurveWallet extends Account {
+    readonly publicKey: string;
+    /**
+     * The constructor does not validate anything. Prefer {@link createAndVerify}, or call
+     * {@link verifyWallet} before use — until then the key is not checked to control `address`.
+     *
+     * @param provider Starknet RPC provider
+     * @param privateKey Stark-curve private key of the account, in the 0x... format
+     * @param address Address of the **already deployed account**
+     */
+    constructor(provider: Provider, privateKey: string, address: string);
+    /**
+     * Always null — wraps an already-deployed account and never self-deploys.
+     */
+    getDeploymentData(): DeployAccountContractPayload | null;
+    /**
+     * @throws {@link AccountNotDeployedError} on CONTRACT_NOT_FOUND; other errors (rate limit, network) propagate.
+     */
+    protected assertDeployed(): Promise<void>;
+    /**
+     * A fixed SNIP-12 message — the contents are irrelevant, it only needs to be signed and validated.
+     */
+    protected getOwnershipMessage(): Promise<TypedData>;
+    /**
+     * Verifies the private key controls the bound account by signing a SNIP-12 message and validating it
+     *  against the account's own on-chain `is_valid_signature` — the canonical check, independent of the
+     *  account's class hash or signature scheme.
+     *
+     * @throws {@link AccountNotDeployedError} if the account is not deployed
+     * @throws {@link WalletVerificationError} if the account does not accept the key's signature
+     */
+    verifyWallet(): Promise<void>;
+    /**
+     * Use this to create a new wallet instance, prefer it over just using the constructor!
+     *
+     * Constructs the wallet and verifies wallet account ownership (by running {@link verifyWallet}).
+     */
+    static createAndVerify(provider: Provider, privateKey: string, address: string): Promise<DeployedStarkCurveWallet>;
+}

package/dist/starknet/wallet/accounts/DeployedStarkCurveWallet.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeployedStarkCurveWallet = exports.WalletVerificationError = exports.AccountNotDeployedError = void 0;
+const starknet_1 = require("starknet");
+const Utils_1 = require("../../../utils/Utils");
+/**
+ * Thrown when the target account is not deployed on-chain, so its signature rules can't be checked.
+ */
+class AccountNotDeployedError extends Error {
+    constructor(address) {
+        super("Account " + address + " is not deployed on-chain");
+        this.address = address;
+        this.name = "AccountNotDeployedError";
+        Object.setPrototypeOf(this, AccountNotDeployedError.prototype);
+    }
+}
+exports.AccountNotDeployedError = AccountNotDeployedError;
+/**
+ * Thrown when the deployed account rejects a signature from the key (wrong key, or a scheme a single Stark-curve key can't satisfy, e.g. multisig/guardian/secp256r1).
+ */
+class WalletVerificationError extends Error {
+    constructor(address) {
+        super("Account " + address + " did not accept a signature from the provided private key");
+        this.address = address;
+        this.name = "WalletVerificationError";
+        Object.setPrototypeOf(this, WalletVerificationError.prototype);
+    }
+}
+exports.WalletVerificationError = WalletVerificationError;
+/**
+ * Wallet for an already-deployed Starknet account controlled by a single Stark-curve private key,
+ *  bound to an explicit `address` (Starknet addresses depend on the account class hash, so a key
+ *  maps to a different address per wallet vendor). Never self-deploys.
+ *
+ * Use this when bringing in the key from an already deployed wallet account (Braavos, Xverse or Argent/Ready wallets).
+ *
+ * If you are creating a new wallet consider using {@link StarknetKeypairWallet}.
+ *
+ * @remarks Prefer {@link createAndVerify}, or call {@link verifyWallet} before use after using the constructor,
+ *  these perform an actual check on whether a given key actually controls the wallet account at a given address.
+ *
+ * @category Wallets
+ */
+class DeployedStarkCurveWallet extends starknet_1.Account {
+    /**
+     * The constructor does not validate anything. Prefer {@link createAndVerify}, or call
+     * {@link verifyWallet} before use — until then the key is not checked to control `address`.
+     *
+     * @param provider Starknet RPC provider
+     * @param privateKey Stark-curve private key of the account, in the 0x... format
+     * @param address Address of the **already deployed account**
+     */
+    constructor(provider, privateKey, address) {
+        super({ provider, address, signer: privateKey, cairoVersion: "1" });
+        this.publicKey = starknet_1.ec.starkCurve.getStarkKey((0, Utils_1.toHex)(privateKey));
+    }
+    /**
+     * Always null — wraps an already-deployed account and never self-deploys.
+     */
+    getDeploymentData() {
+        return null;
+    }
+    /**
+     * @throws {@link AccountNotDeployedError} on CONTRACT_NOT_FOUND; other errors (rate limit, network) propagate.
+     */
+    async assertDeployed() {
+        try {
+            await this.getClassHashAt(this.address);
+        }
+        catch (e) {
+            const message = ((e?.message ?? "") + (e?.baseError?.message ?? "")).toLowerCase();
+            if (message.includes("contract not found") || e?.code === 20 || e?.baseError?.code === 20)
+                throw new AccountNotDeployedError(this.address);
+            throw e;
+        }
+    }
+    /**
+     * A fixed SNIP-12 message — the contents are irrelevant, it only needs to be signed and validated.
+     */
+    async getOwnershipMessage() {
+        return {
+            types: {
+                StarknetDomain: [
+                    { name: 'name', type: 'shortstring' },
+                    { name: 'version', type: 'shortstring' },
+                    { name: 'chainId', type: 'shortstring' },
+                    { name: 'revision', type: 'shortstring' },
+                ],
+                Verification: [{ name: 'action', type: 'shortstring' }],
+            },
+            primaryType: 'Verification',
+            domain: { name: 'DeployedStarkCurveWallet', version: '1', chainId: await this.getChainId(), revision: '1' },
+            message: { action: 'Verify wallet ownership' },
+        };
+    }
+    /**
+     * Verifies the private key controls the bound account by signing a SNIP-12 message and validating it
+     *  against the account's own on-chain `is_valid_signature` — the canonical check, independent of the
+     *  account's class hash or signature scheme.
+     *
+     * @throws {@link AccountNotDeployedError} if the account is not deployed
+     * @throws {@link WalletVerificationError} if the account does not accept the key's signature
+     */
+    async verifyWallet() {
+        await this.assertDeployed();
+        const message = await this.getOwnershipMessage();
+        const signature = await this.signMessage(message);
+        const valid = await this.verifyMessageInStarknet(message, signature, this.address);
+        if (!valid)
+            throw new WalletVerificationError(this.address);
+    }
+    /**
+     * Use this to create a new wallet instance, prefer it over just using the constructor!
+     *
+     * Constructs the wallet and verifies wallet account ownership (by running {@link verifyWallet}).
+     */
+    static async createAndVerify(provider, privateKey, address) {
+        const wallet = new DeployedStarkCurveWallet(provider, privateKey, address);
+        await wallet.verifyWallet();
+        return wallet;
+    }
+}
+exports.DeployedStarkCurveWallet = DeployedStarkCurveWallet;

package/dist/starknet/wallet/accounts/StarknetKeypairWallet.d.ts

@@ -1,6 +1,13 @@
 import { Account, DeployAccountContractPayload, Provider } from "starknet";
 /**
- * Keypair-based wallet implementation using OpenZeppelin Account
+ * A simple keypair-based wallet implementation with a single key and not-upgradable, uses OpenZeppelin Account.
+ * Use this only for new keypair-based wallets which don't require additional features such as guardians, multisigs
+ *  or upgradability.
+ *
+ * @remarks Don't use this for already deployed existing wallet account (Braavos, Xverse, Argent/Ready), as it will
+ *  result in a different address even when used with the same key (this is because Starknet has native account
+ *  abstraction capabilities and you need a correct combination of account type + key). For already deployed wallet
+ *  accounts consider using {@link DeployedStarkCurveWallet} instead!
  *
  * @category Wallets
  */

package/dist/starknet/wallet/accounts/StarknetKeypairWallet.js

@@ -6,7 +6,14 @@ const Utils_1 = require("../../../utils/Utils");
 const buffer_1 = require("buffer");
 const OZaccountClassHash = '0x00261c293c8084cd79086214176b33e5911677cec55104fddc8d25b0b736dcad';
 /**
- * Keypair-based wallet implementation using OpenZeppelin Account
+ * A simple keypair-based wallet implementation with a single key and not-upgradable, uses OpenZeppelin Account.
+ * Use this only for new keypair-based wallets which don't require additional features such as guardians, multisigs
+ *  or upgradability.
+ *
+ * @remarks Don't use this for already deployed existing wallet account (Braavos, Xverse, Argent/Ready), as it will
+ *  result in a different address even when used with the same key (this is because Starknet has native account
+ *  abstraction capabilities and you need a correct combination of account type + key). For already deployed wallet
+ *  accounts consider using {@link DeployedStarkCurveWallet} instead!
  *
  * @category Wallets
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atomiqlabs/chain-starknet",
-  "version": "8.5.0",
+  "version": "8.5.1",
   "description": "Starknet specific base implementation",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",