@0xsequence/wallet-core 0.0.0-20250520201059

package/dist/wallet.js

@@ -0,0 +1,306 @@
+import { Config, Constants, Context, Erc6492, Payload, Address as SequenceAddress, Signature as SequenceSignature, } from '@0xsequence/wallet-primitives';
+import { AbiFunction, Address, Bytes, Hex, TypedData } from 'ox';
+import * as Envelope from './envelope.js';
+import * as State from './state/index.js';
+export const DefaultWalletOptions = {
+    context: Context.Dev1,
+    stateProvider: new State.Local.Provider(),
+    guest: Constants.DefaultGuest,
+};
+export class Wallet {
+    address;
+    context;
+    guest;
+    stateProvider;
+    constructor(address, options) {
+        this.address = address;
+        const combinedOptions = { ...DefaultWalletOptions, ...options };
+        this.context = combinedOptions.context;
+        this.guest = combinedOptions.guest;
+        this.stateProvider = combinedOptions.stateProvider;
+    }
+    static async fromConfiguration(configuration, options) {
+        const merged = { ...DefaultWalletOptions, ...options };
+        //FIXME Validate configuration (weights not too large, total weights above threshold, etc)
+        await merged.stateProvider.saveWallet(configuration, merged.context);
+        return new Wallet(SequenceAddress.from(configuration, merged.context), merged);
+    }
+    async isDeployed(provider) {
+        return (await provider.request({ method: 'eth_getCode', params: [this.address, 'pending'] })) !== '0x';
+    }
+    async buildDeployTransaction() {
+        const deployInformation = await this.stateProvider.getDeploy(this.address);
+        if (!deployInformation) {
+            throw new Error(`cannot find deploy information for ${this.address}`);
+        }
+        return Erc6492.deploy(deployInformation.imageHash, deployInformation.context);
+    }
+    async prepareUpdate(configuration) {
+        const imageHash = Config.hashConfiguration(configuration);
+        const blankEvelope = (await Promise.all([
+            this.prepareBlankEnvelope(0n),
+            // TODO: Add save configuration
+            this.stateProvider.saveWallet(configuration, this.context),
+        ]))[0];
+        return {
+            ...blankEvelope,
+            payload: Payload.fromConfigUpdate(Bytes.toHex(imageHash)),
+        };
+    }
+    async submitUpdate(envelope, options) {
+        const [status, newConfig] = await Promise.all([
+            this.getStatus(),
+            this.stateProvider.getConfiguration(envelope.payload.imageHash),
+        ]);
+        if (!newConfig) {
+            throw new Error(`cannot find configuration details for ${envelope.payload.imageHash}`);
+        }
+        // Verify the new configuration is valid
+        const updatedEnvelope = { ...envelope, configuration: status.configuration };
+        const { weight, threshold } = Envelope.weightOf(updatedEnvelope);
+        if (weight < threshold) {
+            throw new Error('insufficient weight in envelope');
+        }
+        const signature = Envelope.encodeSignature(updatedEnvelope);
+        await this.stateProvider.saveUpdate(this.address, newConfig, signature);
+        if (options?.validateSave) {
+            const status = await this.getStatus();
+            if (Hex.from(Config.hashConfiguration(status.configuration)) !== envelope.payload.imageHash) {
+                throw new Error('configuration not saved');
+            }
+        }
+    }
+    async getStatus(provider) {
+        let isDeployed = false;
+        let implementation;
+        let stage;
+        let chainId;
+        let imageHash;
+        let updates = [];
+        let onChainImageHash;
+        if (provider) {
+            // Get chain ID, deployment status, and implementation
+            const requests = await Promise.all([
+                provider.request({ method: 'eth_chainId' }),
+                this.isDeployed(provider),
+                provider
+                    .request({
+                    method: 'eth_call',
+                    params: [{ to: this.address, data: AbiFunction.encodeData(Constants.GET_IMPLEMENTATION) }],
+                })
+                    .then((res) => {
+                    const address = `0x${res.slice(-40)}`;
+                    Address.assert(address, { strict: false });
+                    return address;
+                })
+                    .catch(() => undefined),
+            ]);
+            chainId = BigInt(requests[0]);
+            isDeployed = requests[1];
+            implementation = requests[2];
+            // Determine stage based on implementation address
+            if (implementation) {
+                if (Address.isEqual(implementation, this.context.stage1)) {
+                    stage = 'stage1';
+                }
+                else if (Address.isEqual(implementation, this.context.stage2)) {
+                    stage = 'stage2';
+                }
+            }
+            // Get image hash and updates
+            if (isDeployed && stage === 'stage2') {
+                // For deployed stage2 wallets, get the image hash from the contract
+                onChainImageHash = await provider.request({
+                    method: 'eth_call',
+                    params: [{ to: this.address, data: AbiFunction.encodeData(Constants.IMAGE_HASH) }],
+                });
+            }
+            else {
+                // For non-deployed or stage1 wallets, get the deploy hash
+                const deployInformation = await this.stateProvider.getDeploy(this.address);
+                if (!deployInformation) {
+                    throw new Error(`cannot find deploy information for ${this.address}`);
+                }
+                onChainImageHash = deployInformation.imageHash;
+            }
+            // Get configuration updates
+            updates = await this.stateProvider.getConfigurationUpdates(this.address, onChainImageHash);
+            imageHash = updates[updates.length - 1]?.imageHash ?? onChainImageHash;
+        }
+        else {
+            // Without a provider, we can only get information from the state provider
+            const deployInformation = await this.stateProvider.getDeploy(this.address);
+            if (!deployInformation) {
+                throw new Error(`cannot find deploy information for ${this.address}`);
+            }
+            updates = await this.stateProvider.getConfigurationUpdates(this.address, deployInformation.imageHash);
+            imageHash = updates[updates.length - 1]?.imageHash ?? deployInformation.imageHash;
+        }
+        // Get the current configuration
+        const configuration = await this.stateProvider.getConfiguration(imageHash);
+        if (!configuration) {
+            throw new Error(`cannot find configuration details for ${this.address}`);
+        }
+        if (provider) {
+            return {
+                address: this.address,
+                isDeployed,
+                implementation,
+                stage,
+                configuration,
+                imageHash,
+                pendingUpdates: [...updates].reverse(),
+                chainId,
+                onChainImageHash: onChainImageHash,
+            };
+        }
+        else {
+            return {
+                address: this.address,
+                isDeployed,
+                implementation,
+                stage,
+                configuration,
+                imageHash,
+                pendingUpdates: [...updates].reverse(),
+                chainId,
+            };
+        }
+    }
+    async getNonce(provider, space) {
+        const result = await provider.request({
+            method: 'eth_call',
+            params: [{ to: this.address, data: AbiFunction.encodeData(Constants.READ_NONCE, [space]) }],
+        });
+        if (result === '0x' || result.length === 0) {
+            return 0n;
+        }
+        return BigInt(result);
+    }
+    async prepareTransaction(provider, calls, options) {
+        const space = options?.space ?? 0n;
+        const [chainId, nonce] = await Promise.all([
+            provider.request({ method: 'eth_chainId' }),
+            this.getNonce(provider, space),
+        ]);
+        // If the latest configuration does not match the onchain configuration
+        // then we bundle the update into the transaction envelope
+        if (!options?.noConfigUpdate) {
+            const status = await this.getStatus(provider);
+            if (status.imageHash !== status.onChainImageHash) {
+                calls.push({
+                    to: this.address,
+                    value: 0n,
+                    data: AbiFunction.encodeData(Constants.UPDATE_IMAGE_HASH, [status.imageHash]),
+                    gasLimit: 0n,
+                    delegateCall: false,
+                    onlyFallback: false,
+                    behaviorOnError: 'revert',
+                });
+            }
+        }
+        return {
+            payload: {
+                type: 'call',
+                space,
+                nonce,
+                calls,
+            },
+            ...(await this.prepareBlankEnvelope(BigInt(chainId))),
+        };
+    }
+    async buildTransaction(provider, envelope) {
+        const status = await this.getStatus(provider);
+        const updatedEnvelope = { ...envelope, configuration: status.configuration };
+        const { weight, threshold } = Envelope.weightOf(updatedEnvelope);
+        if (weight < threshold) {
+            throw new Error('insufficient weight in envelope');
+        }
+        const signature = Envelope.encodeSignature(updatedEnvelope);
+        if (status.isDeployed) {
+            return {
+                to: this.address,
+                data: AbiFunction.encodeData(Constants.EXECUTE, [
+                    Bytes.toHex(Payload.encode(envelope.payload)),
+                    Bytes.toHex(SequenceSignature.encodeSignature({
+                        ...signature,
+                        suffix: status.pendingUpdates.map(({ signature }) => signature),
+                    })),
+                ]),
+            };
+        }
+        else {
+            const deploy = await this.buildDeployTransaction();
+            return {
+                to: this.guest,
+                data: Bytes.toHex(Payload.encode({
+                    type: 'call',
+                    space: 0n,
+                    nonce: 0n,
+                    calls: [
+                        {
+                            to: deploy.to,
+                            value: 0n,
+                            data: deploy.data,
+                            gasLimit: 0n,
+                            delegateCall: false,
+                            onlyFallback: false,
+                            behaviorOnError: 'revert',
+                        },
+                        {
+                            to: this.address,
+                            value: 0n,
+                            data: AbiFunction.encodeData(Constants.EXECUTE, [
+                                Bytes.toHex(Payload.encode(envelope.payload)),
+                                Bytes.toHex(SequenceSignature.encodeSignature({
+                                    ...signature,
+                                    suffix: status.pendingUpdates.map(({ signature }) => signature),
+                                })),
+                            ]),
+                            gasLimit: 0n,
+                            delegateCall: false,
+                            onlyFallback: false,
+                            behaviorOnError: 'revert',
+                        },
+                    ],
+                })),
+            };
+        }
+    }
+    async prepareMessageSignature(message, chainId) {
+        let encodedMessage;
+        if (typeof message !== 'string') {
+            encodedMessage = TypedData.encode(message);
+        }
+        else {
+            let hexMessage = Hex.validate(message) ? message : Hex.fromString(message);
+            const messageSize = Hex.size(hexMessage);
+            encodedMessage = Hex.concat(Hex.fromString(`${`\x19Ethereum Signed Message:\n${messageSize}`}`), hexMessage);
+        }
+        return {
+            ...(await this.prepareBlankEnvelope(chainId)),
+            payload: Payload.fromMessage(encodedMessage),
+        };
+    }
+    async buildMessageSignature(envelope, provider) {
+        const status = await this.getStatus(provider);
+        const signature = Envelope.encodeSignature(envelope);
+        if (!status.isDeployed) {
+            const deployTransaction = await this.buildDeployTransaction();
+            signature.erc6492 = { to: deployTransaction.to, data: Bytes.fromHex(deployTransaction.data) };
+        }
+        const encoded = SequenceSignature.encodeSignature({
+            ...signature,
+            suffix: status.pendingUpdates.map(({ signature }) => signature),
+        });
+        return encoded;
+    }
+    async prepareBlankEnvelope(chainId) {
+        const status = await this.getStatus();
+        return {
+            wallet: this.address,
+            chainId: chainId,
+            configuration: status.configuration,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@0xsequence/wallet-core",
+  "version": "0.0.0-20250520201059",
+  "license": "Apache-2.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "private": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.9",
+    "dotenv": "^16.4.7",
+    "fake-indexeddb": "^6.0.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.1.2",
+    "@repo/typescript-config": "^0.0.0-20250520201059"
+  },
+  "dependencies": {
+    "ox": "^0.7.0",
+    "@0xsequence/wallet-primitives": "^0.0.0-20250520201059"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run"
+  }
+}

package/src/envelope.ts

@@ -0,0 +1,148 @@
+import { Config, Payload, Signature } from '@0xsequence/wallet-primitives'
+import { Address, Hex } from 'ox'
+
+export type Envelope<T extends Payload.Payload> = {
+  readonly wallet: Address.Address
+  readonly chainId: bigint
+  readonly configuration: Config.Config
+  readonly payload: T
+}
+
+export type Signature = {
+  address: Address.Address
+  signature: Signature.SignatureOfSignerLeaf
+}
+
+// Address not included as it is included in the signature
+export type SapientSignature = {
+  imageHash: Hex.Hex
+  signature: Signature.SignatureOfSapientSignerLeaf
+}
+
+export function isSignature(sig: any): sig is Signature {
+  return typeof sig === 'object' && 'address' in sig && 'signature' in sig && !('imageHash' in sig)
+}
+
+export function isSapientSignature(sig: any): sig is SapientSignature {
+  return typeof sig === 'object' && 'signature' in sig && 'imageHash' in sig
+}
+
+export type Signed<T extends Payload.Payload> = Envelope<T> & {
+  signatures: (Signature | SapientSignature)[]
+}
+
+export function signatureForLeaf(envelope: Signed<Payload.Payload>, leaf: Config.Leaf) {
+  if (Config.isSignerLeaf(leaf)) {
+    return envelope.signatures.find((sig) => isSignature(sig) && Address.isEqual(sig.address, leaf.address))
+  }
+
+  if (Config.isSapientSignerLeaf(leaf)) {
+    return envelope.signatures.find(
+      (sig) =>
+        isSapientSignature(sig) &&
+        sig.imageHash === leaf.imageHash &&
+        Address.isEqual(sig.signature.address, leaf.address),
+    )
+  }
+
+  return undefined
+}
+
+export function weightOf(envelope: Signed<Payload.Payload>): { weight: bigint; threshold: bigint } {
+  const { maxWeight } = Config.getWeight(envelope.configuration, (s) => !!signatureForLeaf(envelope, s))
+  return {
+    weight: maxWeight,
+    threshold: envelope.configuration.threshold,
+  }
+}
+
+export function reachedThreshold(envelope: Signed<Payload.Payload>): boolean {
+  const { weight, threshold } = weightOf(envelope)
+  return weight >= threshold
+}
+
+export function encodeSignature(envelope: Signed<Payload.Payload>): Signature.RawSignature {
+  const topology = Signature.fillLeaves(
+    envelope.configuration.topology,
+    (s) => signatureForLeaf(envelope, s)?.signature,
+  )
+  return {
+    noChainId: envelope.chainId === 0n,
+    configuration: { ...envelope.configuration, topology },
+  }
+}
+
+export function toSigned<T extends Payload.Payload>(
+  envelope: Envelope<T>,
+  signatures: (Signature | SapientSignature)[] = [],
+): Signed<T> {
+  return {
+    ...envelope,
+    signatures,
+  }
+}
+
+export function addSignature(
+  envelope: Signed<Payload.Payload>,
+  signature: Signature | SapientSignature,
+  args?: { replace?: boolean },
+) {
+  if (isSapientSignature(signature)) {
+    // Find if the signature already exists in envelope
+    const prev = envelope.signatures.find(
+      (sig) =>
+        isSapientSignature(sig) &&
+        Address.isEqual(sig.signature.address, signature.signature.address) &&
+        sig.imageHash === signature.imageHash,
+    ) as SapientSignature | undefined
+
+    if (prev) {
+      // If the signatures are identical, then we can do nothing
+      if (prev.signature.data === signature.signature.data) {
+        return
+      }
+
+      // If not and we are replacing, then remove the previous signature
+      if (args?.replace) {
+        envelope.signatures = envelope.signatures.filter((sig) => sig !== prev)
+      } else {
+        throw new Error('Signature already defined for signer')
+      }
+    }
+
+    envelope.signatures.push(signature)
+  } else if (isSignature(signature)) {
+    // Find if the signature already exists in envelope
+    const prev = envelope.signatures.find(
+      (sig) => isSignature(sig) && Address.isEqual(sig.address, signature.address),
+    ) as Signature | undefined
+
+    if (prev) {
+      // If the signatures are identical, then we can do nothing
+      if (prev.signature.type === 'erc1271' && signature.signature.type === 'erc1271') {
+        if (prev.signature.data === signature.signature.data) {
+          return
+        }
+      } else if (prev.signature.type !== 'erc1271' && signature.signature.type !== 'erc1271') {
+        if (prev.signature.r === signature.signature.r && prev.signature.s === signature.signature.s) {
+          return
+        }
+      }
+
+      // If not and we are replacing, then remove the previous signature
+      if (args?.replace) {
+        envelope.signatures = envelope.signatures.filter((sig) => sig !== prev)
+      } else {
+        throw new Error('Signature already defined for signer')
+      }
+    }
+
+    envelope.signatures.push(signature)
+  } else {
+    throw new Error('Unsupported signature type')
+  }
+}
+
+export function isSigned(envelope: Envelope<Payload.Payload>): envelope is Signed<Payload.Payload> {
+  return typeof envelope === 'object' && 'signatures' in envelope
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './wallet.js'
+
+export * as Signers from './signers/index.js'
+export * as State from './state/index.js'
+export * as Relayer from './relayer/index.js'
+export * as Envelope from './envelope.js'

package/src/relayer/index.ts

@@ -0,0 +1,3 @@
+export * from './relayer.js'
+export * as Local from './local.js'
+export * as Pk from './pk-relayer.js'

package/src/relayer/local.ts

@@ -0,0 +1,125 @@
+import { Constants, Payload } from '@0xsequence/wallet-primitives'
+import { AbiFunction, Address, Bytes, Hex, TransactionReceipt } from 'ox'
+import { FeeOption, FeeQuote, OperationStatus, Relayer } from './relayer.js'
+
+type GenericProviderTransactionReceipt = 'success' | 'failed' | 'unknown'
+
+export interface GenericProvider {
+  sendTransaction(args: { to: string; data: string }, chainId: bigint): Promise<string>
+  getTransactionReceipt(txHash: string, chainId: bigint): Promise<GenericProviderTransactionReceipt>
+}
+
+export class LocalRelayer implements Relayer {
+  public readonly id = 'local'
+
+  constructor(public readonly provider: GenericProvider) {}
+
+  static createFromWindow(window: Window): LocalRelayer | undefined {
+    const eth = (window as any).ethereum
+    if (!eth) {
+      console.warn('Window.ethereum not found, skipping local relayer')
+      return undefined
+    }
+
+    const trySwitchChain = async (chainId: bigint) => {
+      try {
+        await eth.request({
+          method: 'wallet_switchEthereumChain',
+          params: [
+            {
+              chainId: `0x${chainId.toString(16)}`,
+            },
+          ],
+        })
+      } catch (error) {
+        // Log and continue
+        console.error('Error switching chain', error)
+      }
+    }
+
+    return new LocalRelayer({
+      sendTransaction: async (args, chainId) => {
+        const accounts: string[] = await eth.request({ method: 'eth_requestAccounts' })
+        const from = accounts[0]
+        if (!from) {
+          console.warn('No account selected, skipping local relayer')
+          return undefined
+        }
+
+        await trySwitchChain(chainId)
+
+        const tx = await eth.request({
+          method: 'eth_sendTransaction',
+          params: [
+            {
+              from,
+              to: args.to,
+              data: args.data,
+            },
+          ],
+        })
+        return tx
+      },
+      getTransactionReceipt: async (txHash, chainId) => {
+        await trySwitchChain(chainId)
+
+        const rpcReceipt = await eth.request({ method: 'eth_getTransactionReceipt', params: [txHash] })
+        if (rpcReceipt) {
+          const receipt = TransactionReceipt.fromRpc(rpcReceipt)
+          if (receipt?.status === 'success') {
+            return 'success'
+          } else if (receipt?.status === 'reverted') {
+            return 'failed'
+          }
+        }
+        return 'unknown'
+      },
+    })
+  }
+
+  feeOptions(
+    wallet: Address.Address,
+    chainId: bigint,
+    calls: Payload.Call[],
+  ): Promise<{ options: FeeOption[]; quote?: FeeQuote }> {
+    return Promise.resolve({ options: [] })
+  }
+
+  private decodeCalls(data: Hex.Hex): Payload.Calls {
+    const executeSelector = AbiFunction.getSelector(Constants.EXECUTE)
+
+    let packedPayload
+    if (data.startsWith(executeSelector)) {
+      const decode = AbiFunction.decodeData(Constants.EXECUTE, data)
+      packedPayload = decode[0]
+    } else {
+      packedPayload = data
+    }
+
+    return Payload.decode(Bytes.fromHex(packedPayload))
+  }
+
+  async relay(to: Address.Address, data: Hex.Hex, chainId: bigint, _?: FeeQuote): Promise<{ opHash: Hex.Hex }> {
+    const txHash = await this.provider.sendTransaction(
+      {
+        to,
+        data,
+      },
+      chainId,
+    )
+    Hex.assert(txHash)
+
+    return { opHash: txHash }
+  }
+
+  async status(opHash: Hex.Hex, chainId: bigint): Promise<OperationStatus> {
+    const receipt = await this.provider.getTransactionReceipt(opHash, chainId)
+    if (receipt === 'unknown') {
+      // Could be pending but we don't know
+      return { status: 'unknown' }
+    }
+    return receipt === 'success'
+      ? { status: 'confirmed', transactionHash: opHash }
+      : { status: 'failed', reason: 'failed' }
+  }
+}