@sovereign-sdk/web3 0.0.12 → 0.0.14

package/README.md

@@ -0,0 +1,119 @@
+# @sovereign-sdk/web3
+
+[![npm version](https://img.shields.io/npm/v/@sovereign-sdk/web3.svg)](https://www.npmjs.com/package/@sovereign-sdk/web3)
+[![CI](https://github.com/Sovereign-Labs/sovereign-sdk-web3-js/actions/workflows/ci.yaml/badge.svg)](https://github.com/Sovereign-Labs/sovereign-sdk-web3-js/actions/workflows/ci.yaml)
+
+A TypeScript client library for interacting with Sovereign SDK rollups.
+
+## Installation
+
+```bash
+npm install @sovereign-sdk/web3
+```
+
+## Features
+
+- 🔄 Type-safe transaction submission and signing
+- 🔍 Runtime call simulation for gas estimation
+- 📦 Borsh serialization with schema validation
+- 🎯 Strongly typed rollup interactions with customizable type specifications
+- 🌐 Full access to ledger, sequencer, and rollup APIs
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { StandardRollup } from '@sovereign-sdk/web3';
+import { newMetaMaskSnapSigner } from '@sovereign-sdk/signers';
+
+// Initialize the rollup client
+const rollup = new StandardRollup({
+  url: 'https://your-rollup-node.com',
+  schema: yourSchema,
+  defaultTxDetails: {
+    max_priority_fee_bips: 1000,
+    max_fee: 1000000,
+    chain_id: 1,
+  },
+});
+
+// Initialize a signer
+const signer = newMetaMaskSnapSigner({
+  curve: 'ed25519',
+  schema: yourSchema,
+  snapId: 'npm:@sovereign-sdk/metamask-snap',
+});
+```
+
+### Submitting Transactions
+
+```typescript
+// Submit a runtime call
+const result = await rollup.call(
+  {
+    value_setter: {
+      set_value: 100,
+    },
+  },
+  { signer }
+);
+```
+
+### Type Safety
+
+```typescript
+type MyRollupTypes = RollupTypeSpec<{
+  RuntimeCall: {
+    value_setter: {
+      set_value: number;
+    };
+  };
+  // Add other type specifications as needed
+}>;
+
+const typedRollup = new StandardRollup<MyRollupTypes>({
+  // ... config
+});
+
+// Now your calls will be type-checked!
+const result = await typedRollup.call(
+  {
+    value_setter: {
+      set_value: 100, // Type checked and automatically serialized to Borsh bytes
+    },
+  },
+  { signer }
+);
+```
+
+### Simulation
+
+```typescript
+// Simulate a call to estimate gas
+const simulation = await rollup.simulate(
+  {
+    value_setter: {
+      set_value: 100,
+    },
+  },
+  {
+    signer,
+    txDetails: {
+      max_priority_fee_bips: 1000,
+      max_fee: 1000000,
+      chain_id: 1,
+    },
+  }
+);
+```
+
+## API Reference
+
+The package exports the following main components:
+
+- `StandardRollup`: The main client class for interacting with rollups
+- `RollupTypeSpec`: Type utility for creating type-safe rollup interactions
+- `createSerializer`: Function to create a Borsh serializer for your rollup schema
+
+For detailed API documentation, please refer to the inline TypeScript documentation in the source code.

package/dist/index.d.mts

@@ -2,68 +2,372 @@ import SovereignClient__default from '@sovereign-sdk/client';
 import * as SovereignClient from '@sovereign-sdk/client';
 export { SovereignClient };
 import { Signer } from '@sovereign-sdk/signers';
+export { Schema } from '@sovereign-sdk/universal-wallet-wasm';
 
+/**
+ * A rollup schema is a description of the types that are utilized in the rollup.
+ * It is used to serialize and deserialize the types.
+ * As well as display them in a human-readable way that is verified by the rollup.
+ */
 type RollupSchema = object;
+/**
+ * A serializer is used to serialize rollup types to Borsh bytes.
+ *
+ * @example
+ * ```typescript
+ * const serializer = createSerializer(yourSchema);
+ * const runtimeCall = {
+ *   value_setter: {
+ *     set_value: 100,
+ *   },
+ * };
+ * const borshBytes = serializer.serializeRuntimeCall(runtimeCall);
+ * ```
+ */
 type RollupSerializer = {
+    /**
+     * Serialize an input to Borsh bytes.
+     *
+     * Treats `Uint8Array` as a plain array of numbers as this is the format used by universal-wallet-wasm
+     * to represent Borsh bytes.
+     *
+     * @param input - The input to serialize.
+     * @param index - The index of the type in the schema to serialize.
+     * @returns The serialized Borsh bytes.
+     */
     serialize(input: unknown, index: number): Uint8Array;
+    /**
+     * Serialize a runtime call to Borsh bytes.
+     *
+     * @param input - The runtime call to serialize.
+     * @returns The serialized Borsh bytes.
+     */
     serializeRuntimeCall(input: unknown): Uint8Array;
+    /**
+     * Serialize an unsigned transaction to Borsh bytes.
+     *
+     * @param input - The unsigned transaction to serialize.
+     * @returns The serialized Borsh bytes.
+     */
     serializeUnsignedTx(input: unknown): Uint8Array;
+    /**
+     * Serialize a transaction to Borsh bytes.
+     *
+     * @param input - The transaction to serialize.
+     * @returns The serialized Borsh bytes.
+     */
     serializeTx(input: unknown): Uint8Array;
 };
+/**
+ * Create a serializer for a rollup schema.
+ *
+ * @throws {@link SovereignError} - If the schema is invalid.
+ * @param schemaObject - The rollup schema.
+ * @returns The serializer.
+ */
 declare function createSerializer(schemaObject: RollupSchema): RollupSerializer;
 
+/**
+ * The base type specification for a rollup.
+ *
+ * Defines a centralised set of types that are used in the rollup.
+ * This allows for a single source of truth for the types used in the rollup.
+ */
 type BaseTypeSpec = {
+    /**
+     * The type of transaction used in the rollup.
+     */
     Transaction: any;
+    /**
+     * The type of unsigned transaction used in the rollup.
+     */
     UnsignedTransaction: any;
+    /**
+     * The type of runtime call used in the rollup.
+     */
     RuntimeCall: any;
+    /**
+     * The type of the dedup data used to deduplicate transactions.
+     */
+    Dedup: any;
 };
 type OverrideType<Base, Override> = {
     [K in keyof Base]: K extends keyof Override ? Override[K] : Base[K];
 };
+/**
+ * The type specification for a rollup.
+ *
+ * Extends the base type specification with concrete types.
+ *
+ * @example
+ * ```typescript
+ * type TxDetails = {
+ *   maxPriorityFeeBips: number;
+ *   maxFee: number;
+ *   gasLimit?: bigint;
+ *   chainId: number;
+ * };
+ *
+ * type UnsignedTransaction = {
+ *   runtimeMsg: Uint8Array;
+ *   nonce: number;
+ *   details: TxDetails;
+ * };
+ *
+ * type Transaction = {
+ *   pubKey: string;
+ *   signature: string;
+ * } & UnsignedTransaction;
+ *
+ * type MyTypeSpec = RollupTypeSpec<{
+ *   UnsignedTransaction: UnsignedTransaction,
+ *   Transaction: Transaction,
+ *   // ...
+ * }>;
+ *
+ * // The typespec can now be used with the rollup class to provide type safety
+ * // for the transaction types.
+ * const rollup = new StandardRollup<MyTypeSpec>({
+ *   schema: yourSchema,
+ *   // ...
+ * });
+ * const result = await rollup.signAndSubmitTransaction({
+ *   // ...
+ * });
+ * const tx = result.transaction; // Strongly typed as `Transaction` on your RollupTypeSpec.
+ * ```
+ *
+ * @param T - The type specification to extend the base type specification with.
+ */
 type RollupTypeSpec<T extends Partial<BaseTypeSpec>> = OverrideType<BaseTypeSpec, T>;
 
-type TransactionResult<Tx> = {
-    response: SovereignClient__default.Sequencer.TxCreateResponse;
-    transaction: Tx;
+type DeepPartial<T> = T extends unknown[] ? T : T extends Record<string, unknown> ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+
+type UnsignedTransactionContext<S extends BaseTypeSpec, C extends RollupContext> = {
+    runtimeCall: S["RuntimeCall"];
+    sender: Uint8Array;
+    overrides: DeepPartial<S["UnsignedTransaction"]>;
+    rollup: Rollup<S, C>;
+};
+type TransactionContext<S extends BaseTypeSpec, C extends RollupContext> = {
+    unsignedTx: S["UnsignedTransaction"];
+    sender: Uint8Array;
+    signature: Uint8Array;
+    rollup: Rollup<S, C>;
 };
-type RollupConfig = {
+type TypeBuilder<S extends BaseTypeSpec, C extends RollupContext> = {
+    unsignedTransaction: (context: UnsignedTransactionContext<S, C>) => Promise<S["UnsignedTransaction"]>;
+    transaction: (context: TransactionContext<S, C>) => Promise<S["Transaction"]>;
+};
+/**
+ * Arbitrary context that is associated with the rollup.
+ */
+type RollupContext = Record<string, unknown>;
+/**
+ * The configuration for a rollup client.
+ */
+type RollupConfig<C extends RollupContext> = {
+    /**
+     * The base URL of the rollup full node API.
+     */
     url?: string;
-    schema: RollupSchema;
-    defaultTxDetails: TxDetails;
+    /**
+     * The Sovereign SDK client to use for the rollup.
+     * If not provided, the default client will be used using {@link RollupConfig.url}.
+     */
+    client?: SovereignClient__default;
+    /**
+     * The schema of the rollup.
+     */
+    schema?: RollupSchema;
+    /**
+     * The serializer to use for the rollup.
+     * If not provided, a serializer will be created using the provided {@link RollupConfig.schema}.
+     */
+    serializer?: RollupSerializer;
+    /**
+     * Arbitrary context that is associated with the rollup.
+     */
+    context: C;
 };
-type TxDetails = {
-    max_priority_fee_bips: number;
-    max_fee: number;
-    gas_limit?: number[];
-    chain_id: number;
+/**
+ * The result of signing and submitting a transaction.
+ *
+ * @template Tx The type of the transaction
+ */
+type TransactionResult<Tx> = {
+    /**
+     * The response from the sequencer.
+     */
+    response: SovereignClient__default.Sequencer.TxCreateResponse;
+    /**
+     * The transaction that was submitted.
+     */
+    transaction: Tx;
 };
+/**
+ * The parameters for signing and submitting a transaction.
+ */
 type SignerParams = {
+    /**
+     * The signer to use for signing the transaction.
+     */
     signer: Signer;
 };
-type CallParams = {
-    txDetails?: TxDetails;
-} & SignerParams;
-type SimulateParams = {
-    txDetails: TxDetails;
+/**
+ * The parameters for calling executing a runtime call transaction.
+ */
+type CallParams<S extends BaseTypeSpec> = {
+    overrides?: DeepPartial<S["UnsignedTransaction"]>;
 } & SignerParams;
-declare class StandardRollup<T extends BaseTypeSpec = BaseTypeSpec> {
+/**
+ * A generic rollup client.
+ *
+ * @template S - The type specification for the rollup.
+ *               If not provided, the base type specification will be used which uses `any` for all types.
+ * @template C - The context for the rollup.
+ */
+declare class Rollup<S extends BaseTypeSpec, C extends RollupContext> {
     private readonly _config;
     private readonly _client;
     private readonly _serializer;
-    constructor(config: RollupConfig);
-    submitTransaction(transaction: T["Transaction"]): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
-    signAndSubmitTransaction(unsignedTx: T["UnsignedTransaction"], { signer }: SignerParams): Promise<TransactionResult<T["Transaction"]>>;
-    call(runtimeMessage: T["RuntimeCall"], { signer, txDetails }: CallParams): Promise<TransactionResult<T["Transaction"]>>;
-    simulate(runtimeMessage: T["RuntimeCall"], { signer, txDetails }: SimulateParams): Promise<SovereignClient__default.Rollup.SimulateExecutionResponse>;
+    private readonly _typeBuilder;
+    /**
+     * Creates a new rollup client.
+     *
+     * @throws {@link InvalidRollupConfigError} - If no schema or serializer is provided.
+     *
+     * @param config - The configuration for the rollup client.
+     * @param typeBuilder - The type builder for the rollup.
+     */
+    constructor(config: RollupConfig<C>, typeBuilder: TypeBuilder<S, C>);
+    /**
+     * Retrieve dedup information about the provided address.
+     *
+     * @param address - The public key to dedup.
+     */
+    dedup(address: Uint8Array): Promise<S["Dedup"]>;
+    /**
+     * Submits a batch to the rollup.
+     *
+     * @param batch - The batch of transactions to submit.
+     */
+    submitBatch(batch: S["Transaction"][]): Promise<SovereignClient__default.Sequencer.BatchCreateResponse>;
+    /**
+     * Submits a transaction to the rollup.
+     *
+     * @param transaction - The transaction to submit.
+     */
+    submitTransaction(transaction: S["Transaction"]): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
+    /**
+     * Signs and submits a transaction to the rollup.
+     * Utilizes the provided signer to sign the transaction.
+     *
+     * @param unsignedTx - The unsigned transaction to sign and submit.
+     * @param {SignerParams} params - The params for signing and submitting the transaction.
+     */
+    signAndSubmitTransaction(unsignedTx: S["UnsignedTransaction"], { signer }: SignerParams): Promise<TransactionResult<S["Transaction"]>>;
+    /**
+     * Performs a runtime call transaction.
+     * Utilizes the provided signer to sign the transaction.
+     *
+     * @param runtimeCall - The runtime message to call.
+     * @param {CallParams<S>} params - The params for submitting a runtime call transaction.
+     */
+    call(runtimeCall: S["RuntimeCall"], { signer, overrides }: CallParams<S>): Promise<TransactionResult<S["Transaction"]>>;
+    /**
+     * A ledger client that can be used to query the ledger.
+     */
     get ledger(): SovereignClient__default.Ledger;
+    /**
+     * A sequencer client that can be used to submit transactions & batches to the rollup.
+     */
     get sequencer(): SovereignClient__default.Sequencer;
+    /**
+     * A rollup client that can be used to perform operations on the rollup.
+     */
     get rollup(): SovereignClient__default.Rollup;
+    /**
+     * A client that can be used to perform HTTP requests to the Sovereign API.
+     * This can be used as an escape hatch to execute arbitrary requests to the Sovereign API
+     * if the operation is not supported by `ledger`, `sequencer`, or `rollup` clients.
+     */
     get http(): SovereignClient__default;
+    /**
+     * The serializer for the rollup.
+     * Can be used to serialize transactions, runtime calls, etc.
+     * See {@link RollupSerializer} for more information.
+     */
     get serializer(): RollupSerializer;
+    /**
+     * The context for the rollup.
+     */
+    get context(): C;
 }
 
+type TxDetails = {
+    max_priority_fee_bips: number;
+    max_fee: number;
+    gas_limit?: number[];
+    chain_id: number;
+};
+type UnsignedTransaction = {
+    runtime_msg: Uint8Array;
+    nonce: number;
+    details: TxDetails;
+};
+type Transaction = {
+    pub_key: {
+        pub_key: Uint8Array;
+    };
+    signature: {
+        msg_sig: Uint8Array;
+    };
+} & UnsignedTransaction;
+type Dedup = {
+    nonce: number;
+};
+type StandardRollupContext = {
+    defaultTxDetails: TxDetails;
+};
+type StandardRollupSpec<RuntimeCall> = {
+    UnsignedTransaction: UnsignedTransaction;
+    Transaction: Transaction;
+    RuntimeCall: RuntimeCall;
+    Dedup: Dedup;
+};
+declare function standardTypeBuilder<S extends StandardRollupSpec<unknown>>(): TypeBuilder<S, StandardRollupContext>;
+/**
+ * The parameters for simulating a runtime call transaction.
+ */
+type SimulateParams = {
+    /**
+     * The transaction details to use for the simulation.
+     */
+    txDetails: TxDetails;
+    nonce?: number;
+} & SignerParams;
+declare class StandardRollup<RuntimeCall> extends Rollup<StandardRollupSpec<RuntimeCall>, StandardRollupContext> {
+    /**
+     * Simulates a runtime call transaction.
+     *
+     * This method can be useful to estimate the gas cost of a runtime call transaction.
+     *
+     * @param runtimeMessage - The runtime message to call.
+     */
+    simulate(runtimeMessage: StandardRollupSpec<RuntimeCall>["RuntimeCall"], { signer, txDetails, nonce: overrideNonce }: SimulateParams): Promise<SovereignClient__default.Rollup.SimulateExecutionResponse>;
+}
+declare function createStandardRollup<RuntimeCall, C extends StandardRollupContext = StandardRollupContext>(config: RollupConfig<C>, typeBuilderOverrides?: Partial<TypeBuilder<StandardRollupSpec<RuntimeCall>, C>>): StandardRollup<RuntimeCall>;
+
+/**
+ * Base error class for Sovereign SDK Web3.
+ */
 declare class SovereignError extends Error {
     constructor(message: string);
 }
+declare class InvalidRollupConfigError extends SovereignError {
+}
 
-export { type BaseTypeSpec, type RollupConfig, type RollupSchema, type RollupSerializer, type RollupTypeSpec, SovereignError, StandardRollup, type TransactionResult, createSerializer };
+export { type BaseTypeSpec, type CallParams, type Dedup, InvalidRollupConfigError, Rollup, type RollupConfig, type RollupContext, type RollupSchema, type RollupSerializer, type RollupTypeSpec, type SignerParams, type SimulateParams, SovereignError, StandardRollup, type StandardRollupContext, type StandardRollupSpec, type Transaction, type TransactionContext, type TransactionResult, type TxDetails, type TypeBuilder, type UnsignedTransaction, type UnsignedTransactionContext, createSerializer, createStandardRollup, standardTypeBuilder };