@atomiqlabs/chain-starknet 8.4.5 → 8.5.0

package/README.md

@@ -30,6 +30,69 @@ Import backend-only utilities from the dedicated `node` subpath:
 import {StarknetChainEvents, StarknetPersistentSigner} from "@atomiqlabs/chain-starknet/node";
 ```
 
+## Signers
+
+### Browser wallets
+
+For connecting to browser wallets (Braavos, Xverse, Argent/Ready...) from within browser environments,
+use `StarknetSigner` with a get-starknet `WalletAccount` — the extension handles signing.
+
+```ts
+import { connect } from "@starknet-io/get-starknet";
+import { WalletAccount } from "starknet";
+import { StarknetBrowserSigner } from "@atomiqlabs/chain-starknet";
+
+// Connect the starknet wallet
+const swo = await connect();
+
+const provider = new RpcProvider({nodeUrl: starknetRpc});
+const walletAccount = await WalletAccount.connect(provider, swo);
+const wallet = new StarknetBrowserSigner(walletAccount);
+```
+
+### New keypair based wallets
+
+For a programmatic integration driven by a raw private key using a simple single-key controlled OpenZeppelin
+account. Use this only for newly created accounts, if you are bringing in your existing key from an already
+deployed wallet account (Braavos, Xverse and Argent/Ready accounts), use the `DeployedStarkCurveWallet` described
+in [Already deployed wallets](#already-deployed-wallets).
+
+```ts
+import {StarknetSigner, StarknetKeypairWallet} from "@atomiqlabs/chain-starknet";
+import {RpcProvider} from "starknet";
+
+// Generate random private key
+const starknetKey: string = StarknetKeypairWallet.generateRandomPrivateKey();
+
+const provider = new RpcProvider({nodeUrl: starknetRpc});
+const wallet = new StarknetKeypairWallet(provider, starknetKey);
+const starknetSigner = new StarknetSigner(wallet);
+```
+
+The account contract does not need to be deployed up front: the SDK automatically deploys it with the first
+swap transaction (paying the deployment fee from the account's STRK balance).
+
+### Already deployed wallets
+
+For a programmatic integration driven by a raw private key controlling an **already-deployed**
+account (like existing Braavos, Xverse and Argent/Ready accounts), use `DeployedStarkCurveWallet`.
+A Starknet address depends on the account's class hash, so the address is passed explicitly rather
+than derived. Prefer `createAndVerify` over using the constructor, which confirms — via the account's
+own on-chain signature validation — that the key controls the address:
+
+```ts
+import {StarknetSigner, DeployedStarkCurveWallet} from "@atomiqlabs/chain-starknet";
+import {RpcProvider} from "starknet";
+
+const provider = new RpcProvider({nodeUrl: starknetRpc});
+const wallet = await DeployedStarkCurveWallet.createAndVerify(provider, privateKey, address);
+const signer = new StarknetSigner(wallet);
+```
+
+It throws `AccountNotDeployedError` if the account isn't deployed, or `WalletVerificationError`
+if the key doesn't control it (or the account needs a scheme a single Stark-curve key can't
+satisfy, e.g. multisig). The bare constructor performs no such check — call `verifyWallet()` first.
+
 ## Supported Chains
 
 This package exports a single Starknet initializer:

package/package.json

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

package/src/index.ts

@@ -99,6 +99,7 @@ export {StarknetSuccessAction, StarknetSwapData} from "./starknet/swaps/Starknet
 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/src/starknet/wallet/accounts/DeployedStarkCurveWallet.ts

@@ -0,0 +1,125 @@
+import {Account, DeployAccountContractPayload, ec, Provider, TypedData} from "starknet";
+import {toHex} from "../../../utils/Utils";
+
+/**
+ * Thrown when the target account is not deployed on-chain, so its signature rules can't be checked.
+ */
+export class AccountNotDeployedError extends Error {
+    constructor(readonly address: string) {
+        super("Account "+address+" is not deployed on-chain");
+        this.name = "AccountNotDeployedError";
+        Object.setPrototypeOf(this, AccountNotDeployedError.prototype);
+    }
+}
+
+/**
+ * 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 class WalletVerificationError extends Error {
+    constructor(readonly address: string) {
+        super("Account "+address+" did not accept a signature from the provided private key");
+        this.name = "WalletVerificationError";
+        Object.setPrototypeOf(this, WalletVerificationError.prototype);
+    }
+}
+
+/**
+ * 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 class DeployedStarkCurveWallet extends Account {
+
+    public 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) {
+        super({provider, address, signer: privateKey, cairoVersion: "1"});
+        this.publicKey = ec.starkCurve.getStarkKey(toHex(privateKey));
+    }
+
+    /**
+     * Always null — wraps an already-deployed account and never self-deploys.
+     */
+    public getDeploymentData(): DeployAccountContractPayload | null {
+        return null;
+    }
+
+    /**
+     * @throws {@link AccountNotDeployedError} on CONTRACT_NOT_FOUND; other errors (rate limit, network) propagate.
+     */
+    protected async assertDeployed(): Promise<void> {
+        try {
+            await this.getClassHashAt(this.address);
+        } catch (e: any) {
+            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.
+     */
+    protected async getOwnershipMessage(): Promise<TypedData> {
+        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
+     */
+    public async verifyWallet(): Promise<void> {
+        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}).
+     */
+    public static async createAndVerify(provider: Provider, privateKey: string, address: string): Promise<DeployedStarkCurveWallet> {
+        const wallet = new DeployedStarkCurveWallet(provider, privateKey, address);
+        await wallet.verifyWallet();
+        return wallet;
+    }
+
+}

package/src/starknet/wallet/accounts/StarknetKeypairWallet.ts

@@ -5,7 +5,14 @@ import {Buffer} from "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
  */