@sovereign-sdk/web3 0.11.1 → 0.12.1

package/README.md

@@ -1,7 +1,7 @@
 # @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)
+[![CI](https://github.com/Sovereign-Labs/sovereign-sdk/actions/workflows/typescript.ci.yml/badge.svg)](https://github.com/Sovereign-Labs/sovereign-sdk/actions/workflows/typescript.ci.yml)
 
 A TypeScript client library for interacting with Sovereign SDK rollups.
 

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { HexString } from '@sovereign-sdk/utils';
 import SovereignClient__default from '@sovereign-sdk/client';
 import * as SovereignClient from '@sovereign-sdk/client';
 export { SovereignClient };
-import { RollupSchema, Serializer } from '@sovereign-sdk/serializers';
+import { RollupSchema as RollupSchema$1, Serializer as Serializer$1 } from '@sovereign-sdk/serializers';
 import { Signer } from '@sovereign-sdk/signers';
 import { TxDetails, UnsignedTransaction, Transaction } from '@sovereign-sdk/types';
 
@@ -155,7 +155,7 @@ type RollupConfig<C extends RollupContext> = {
      * This can be called more than once, for example if the chain hash changes (i.e a new rollup version)
      * is detected then it will be called again with the new rollup schema.
      */
-    getSerializer: (schema: RollupSchema) => Serializer;
+    getSerializer: (schema: RollupSchema$1) => Serializer$1;
     /**
      * Arbitrary context that is associated with the rollup.
      */
@@ -308,7 +308,7 @@ declare class Rollup<S extends BaseTypeSpec, C extends RollupContext> {
      * The serializer for the rollup.
      * Can be used to serialize transactions, runtime calls, etc.
      */
-    serializer(): Promise<Serializer>;
+    serializer(): Promise<Serializer$1>;
     /**
      * The context for the rollup.
      */
@@ -346,6 +346,205 @@ declare class StandardRollup<RuntimeCall> extends Rollup<StandardRollupSpec<Runt
 declare const DEFAULT_TX_DETAILS: Omit<TxDetails, "chain_id">;
 declare function createStandardRollup<RuntimeCall, C extends StandardRollupContext = StandardRollupContext>(rollupConfig?: Partial<RollupConfig<DeepPartial<C>>>, typeBuilderOverrides?: Partial<TypeBuilder<StandardRollupSpec<RuntimeCall>, C>>): Promise<StandardRollup<RuntimeCall>>;
 
+/**
+ * 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 = Record<string, any>;
+/**
+ * A serializer is used to serialize rollup types to Borsh bytes.
+ *
+ * @example
+ * ```typescript
+ * const serializer = createSerializer(yourSchema);
+ * const runtimeCall = {
+ *   value_setter: {
+ *     set_value: {
+ *       value: 100,
+ *       gas: null
+ *     },
+ *   },
+ * };
+ * const borshBytes = serializer.serializeRuntimeCall(runtimeCall);
+ * ```
+ */
+declare abstract class Serializer {
+    protected _schema: RollupSchema;
+    constructor(schema: RollupSchema);
+    protected abstract jsonToBorsh(input: unknown, index: number): Uint8Array;
+    private lookupKnownTypeIndex;
+    /**
+     * Serialize an input to Borsh bytes.
+     *
+     * Treats `Uint8Array` as a plain array of numbers as this is the format used by universal-wallet
+     * 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;
+    /** Returns the Schema JSON used by the serializer. */
+    get schema(): RollupSchema;
+}
+
+type SolanaOffchainUnsignedTransaction<RuntimeCall> = {
+    runtime_call: RuntimeCall;
+    uniqueness: {
+        nonce: number;
+    } | {
+        generation: number;
+    };
+    details: {
+        max_priority_fee_bips: number;
+        max_fee: string;
+        gas_limit: number[] | null;
+        chain_id: number;
+    };
+    chain_name: string;
+};
+type SolanaOffchainSimpleMessage = {
+    signed_message: Uint8Array;
+    chain_hash: Uint8Array;
+    pubkey: Uint8Array;
+    signature: Uint8Array;
+};
+type SolanaOffchainSpecCompliantMessage = {
+    signed_message_with_preamble: Uint8Array;
+    signature: Uint8Array;
+};
+type Authenticator = "standard" | "solanaSimple" | "solana" | "solanaAuto";
+/**
+ * Creates a Solana offchain message preamble according to the spec.
+ * See https://docs.anza.xyz/proposals/off-chain-message-signing#message-preamble
+ */
+declare function createSolanaPreamble(pubkey: Uint8Array, chainHash: Uint8Array, messageLength: number): Uint8Array;
+declare class SolanaSignableRollup<RuntimeCall> {
+    private inner;
+    private solanaEndpoint;
+    private typeBuilder;
+    constructor(inner: StandardRollup<RuntimeCall>, solanaEndpoint?: string);
+    /**
+     * Determines the appropriate authenticator based on the signer type.
+     * Returns "solana" for LedgerSolanaSigner (hardware wallet with spec-compliant signing)
+     * and "solanaSimple" for software signers.
+     */
+    private getAutoAuthenticator;
+    /**
+     * Submits serialized data to the Solana endpoint.
+     */
+    private submitSerializedMessage;
+    /**
+     * Submits a Solana offchain message to the rollup.
+     */
+    private submitSolanaMessage;
+    /**
+     * Submits a Solana spec-compliant message to the rollup.
+     */
+    private submitSolanaSpecMessage;
+    /**
+     * Helper to build an unsigned transaction using the standard type builder.
+     */
+    private buildUnsignedTransaction;
+    /**
+     * Helper to build a transaction result object.
+     */
+    private buildTransactionResult;
+    /**
+     * Helper to create and serialize a SolanaOffchainUnsignedTransaction to JSON bytes.
+     */
+    private createSolanaJsonBytes;
+    /**
+     * Signs an unsigned transaction using Solana offchain simple signing and submits it.
+     * Returns the transaction result in the same format as standard rollup.
+     */
+    private signWithSolanaSimpleAndSubmit;
+    /**
+     * Signs an unsigned transaction using Solana spec-compliant signing and submits it.
+     * Returns the transaction result in the same format as standard rollup.
+     */
+    private signWithSolanaSpecAndSubmit;
+    /**
+     * Performs a runtime call transaction with the specified authenticator.
+     *
+     * @param runtimeCall - The runtime call to execute
+     * @param params - Parameters including signer, authenticator type, and optional overrides
+     * @param options - Optional request options
+     * @returns The transaction result including hash and transaction object
+     */
+    call(runtimeCall: RuntimeCall, params: {
+        signer: Signer;
+        authenticator: Authenticator;
+        overrides?: DeepPartial<UnsignedTransaction<RuntimeCall>>;
+    }, options?: SovereignClient__default.RequestOptions): Promise<TransactionResult<Transaction<RuntimeCall>>>;
+    /**
+     * Signs and submits a transaction with the specified authenticator.
+     *
+     * @param unsignedTx - The unsigned transaction to sign and submit
+     * @param params - Parameters including signer and authenticator type
+     * @param options - Optional request options
+     * @returns The transaction result
+     */
+    signAndSubmitTransaction(unsignedTx: UnsignedTransaction<RuntimeCall>, params: {
+        signer: Signer;
+        authenticator: Authenticator;
+    }, options?: SovereignClient__default.RequestOptions): Promise<TransactionResult<Transaction<RuntimeCall>>>;
+    /**
+     * Submits a standard transaction.
+     */
+    submitTransaction(transaction: StandardRollupSpec<RuntimeCall>["Transaction"], authenticator: "standard", options?: SovereignClient__default.RequestOptions): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
+    /**
+     * Submits a Solana offchain message.
+     */
+    submitTransaction(transaction: SolanaOffchainSimpleMessage, authenticator: "solanaSimple", options?: SovereignClient__default.RequestOptions): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
+    /**
+     * Submits a Solana spec-compliant message.
+     */
+    submitTransaction(transaction: SolanaOffchainSpecCompliantMessage, authenticator: "solana", options?: SovereignClient__default.RequestOptions): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
+    simulate(runtimeMessage: RuntimeCall, params: Parameters<StandardRollup<RuntimeCall>["simulate"]>[1]): Promise<SovereignClient__default.Rollup.RollupSimulateResponse>;
+    dedup(address: Uint8Array): Promise<Dedup>;
+    serializer(): Promise<Serializer>;
+    chainHash(): Promise<Uint8Array>;
+    healthcheck(timeout?: number): Promise<boolean>;
+    subscribe<T extends keyof SubscriptionToCallbackMap>(type: T, callback: SubscriptionToCallbackMap[T]): Subscription;
+    get context(): StandardRollupContext;
+    get ledger(): SovereignClient__default.Ledger;
+    get sequencer(): SovereignClient__default.Sequencer;
+    get rollup(): SovereignClient__default.Rollup;
+    get http(): SovereignClient__default;
+    /**
+     * Helper method to serialize a SolanaOffchainSimpleMessage using borsh encoding.
+     */
+    private serializeSolanaMessage;
+    /**
+     * Helper method to serialize a SolanaOffchainSpecCompliantMessage using borsh encoding.
+     */
+    private serializeSolanaSpecMessage;
+}
+declare function createSolanaSignableRollup<RuntimeCall>(rollupConfig?: Partial<RollupConfig<DeepPartial<StandardRollupContext>>>, solanaEndpoint?: string): Promise<SolanaSignableRollup<RuntimeCall>>;
+
 /**
  * Base error class for Sovereign SDK Web3.
  */
@@ -366,4 +565,4 @@ declare class SchemaError extends SovereignError {
     constructor(message: string, reason: string, schema: object);
 }
 
-export { type BaseTypeSpec, type CallParams, DEFAULT_TX_DETAILS, type Dedup, type EventPayload, InvalidRollupConfigError, Rollup, type RollupConfig, type RollupContext, type RollupTypeSpec, SchemaError, type SignerParams, type SimulateParams, SovereignError, StandardRollup, type StandardRollupContext, type StandardRollupSpec, type Subscription, type TransactionContext, type TransactionResult, type TypeBuilder, type UnsignedTransactionContext, VersionMismatchError, addressFromPublicKey, createStandardRollup, standardTypeBuilder };
+export { type Authenticator, type BaseTypeSpec, type CallParams, DEFAULT_TX_DETAILS, type Dedup, type EventPayload, InvalidRollupConfigError, Rollup, type RollupConfig, type RollupContext, type RollupTypeSpec, SchemaError, type SignerParams, type SimulateParams, type SolanaOffchainSimpleMessage, type SolanaOffchainSpecCompliantMessage, type SolanaOffchainUnsignedTransaction, SolanaSignableRollup, SovereignError, StandardRollup, type StandardRollupContext, type StandardRollupSpec, type Subscription, type TransactionContext, type TransactionResult, type TypeBuilder, type UnsignedTransactionContext, VersionMismatchError, addressFromPublicKey, createSolanaPreamble, createSolanaSignableRollup, createStandardRollup, standardTypeBuilder };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { HexString } from '@sovereign-sdk/utils';
 import SovereignClient__default from '@sovereign-sdk/client';
 import * as SovereignClient from '@sovereign-sdk/client';
 export { SovereignClient };
-import { RollupSchema, Serializer } from '@sovereign-sdk/serializers';
+import { RollupSchema as RollupSchema$1, Serializer as Serializer$1 } from '@sovereign-sdk/serializers';
 import { Signer } from '@sovereign-sdk/signers';
 import { TxDetails, UnsignedTransaction, Transaction } from '@sovereign-sdk/types';
 
@@ -155,7 +155,7 @@ type RollupConfig<C extends RollupContext> = {
      * This can be called more than once, for example if the chain hash changes (i.e a new rollup version)
      * is detected then it will be called again with the new rollup schema.
      */
-    getSerializer: (schema: RollupSchema) => Serializer;
+    getSerializer: (schema: RollupSchema$1) => Serializer$1;
     /**
      * Arbitrary context that is associated with the rollup.
      */
@@ -308,7 +308,7 @@ declare class Rollup<S extends BaseTypeSpec, C extends RollupContext> {
      * The serializer for the rollup.
      * Can be used to serialize transactions, runtime calls, etc.
      */
-    serializer(): Promise<Serializer>;
+    serializer(): Promise<Serializer$1>;
     /**
      * The context for the rollup.
      */
@@ -346,6 +346,205 @@ declare class StandardRollup<RuntimeCall> extends Rollup<StandardRollupSpec<Runt
 declare const DEFAULT_TX_DETAILS: Omit<TxDetails, "chain_id">;
 declare function createStandardRollup<RuntimeCall, C extends StandardRollupContext = StandardRollupContext>(rollupConfig?: Partial<RollupConfig<DeepPartial<C>>>, typeBuilderOverrides?: Partial<TypeBuilder<StandardRollupSpec<RuntimeCall>, C>>): Promise<StandardRollup<RuntimeCall>>;
 
+/**
+ * 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 = Record<string, any>;
+/**
+ * A serializer is used to serialize rollup types to Borsh bytes.
+ *
+ * @example
+ * ```typescript
+ * const serializer = createSerializer(yourSchema);
+ * const runtimeCall = {
+ *   value_setter: {
+ *     set_value: {
+ *       value: 100,
+ *       gas: null
+ *     },
+ *   },
+ * };
+ * const borshBytes = serializer.serializeRuntimeCall(runtimeCall);
+ * ```
+ */
+declare abstract class Serializer {
+    protected _schema: RollupSchema;
+    constructor(schema: RollupSchema);
+    protected abstract jsonToBorsh(input: unknown, index: number): Uint8Array;
+    private lookupKnownTypeIndex;
+    /**
+     * Serialize an input to Borsh bytes.
+     *
+     * Treats `Uint8Array` as a plain array of numbers as this is the format used by universal-wallet
+     * 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;
+    /** Returns the Schema JSON used by the serializer. */
+    get schema(): RollupSchema;
+}
+
+type SolanaOffchainUnsignedTransaction<RuntimeCall> = {
+    runtime_call: RuntimeCall;
+    uniqueness: {
+        nonce: number;
+    } | {
+        generation: number;
+    };
+    details: {
+        max_priority_fee_bips: number;
+        max_fee: string;
+        gas_limit: number[] | null;
+        chain_id: number;
+    };
+    chain_name: string;
+};
+type SolanaOffchainSimpleMessage = {
+    signed_message: Uint8Array;
+    chain_hash: Uint8Array;
+    pubkey: Uint8Array;
+    signature: Uint8Array;
+};
+type SolanaOffchainSpecCompliantMessage = {
+    signed_message_with_preamble: Uint8Array;
+    signature: Uint8Array;
+};
+type Authenticator = "standard" | "solanaSimple" | "solana" | "solanaAuto";
+/**
+ * Creates a Solana offchain message preamble according to the spec.
+ * See https://docs.anza.xyz/proposals/off-chain-message-signing#message-preamble
+ */
+declare function createSolanaPreamble(pubkey: Uint8Array, chainHash: Uint8Array, messageLength: number): Uint8Array;
+declare class SolanaSignableRollup<RuntimeCall> {
+    private inner;
+    private solanaEndpoint;
+    private typeBuilder;
+    constructor(inner: StandardRollup<RuntimeCall>, solanaEndpoint?: string);
+    /**
+     * Determines the appropriate authenticator based on the signer type.
+     * Returns "solana" for LedgerSolanaSigner (hardware wallet with spec-compliant signing)
+     * and "solanaSimple" for software signers.
+     */
+    private getAutoAuthenticator;
+    /**
+     * Submits serialized data to the Solana endpoint.
+     */
+    private submitSerializedMessage;
+    /**
+     * Submits a Solana offchain message to the rollup.
+     */
+    private submitSolanaMessage;
+    /**
+     * Submits a Solana spec-compliant message to the rollup.
+     */
+    private submitSolanaSpecMessage;
+    /**
+     * Helper to build an unsigned transaction using the standard type builder.
+     */
+    private buildUnsignedTransaction;
+    /**
+     * Helper to build a transaction result object.
+     */
+    private buildTransactionResult;
+    /**
+     * Helper to create and serialize a SolanaOffchainUnsignedTransaction to JSON bytes.
+     */
+    private createSolanaJsonBytes;
+    /**
+     * Signs an unsigned transaction using Solana offchain simple signing and submits it.
+     * Returns the transaction result in the same format as standard rollup.
+     */
+    private signWithSolanaSimpleAndSubmit;
+    /**
+     * Signs an unsigned transaction using Solana spec-compliant signing and submits it.
+     * Returns the transaction result in the same format as standard rollup.
+     */
+    private signWithSolanaSpecAndSubmit;
+    /**
+     * Performs a runtime call transaction with the specified authenticator.
+     *
+     * @param runtimeCall - The runtime call to execute
+     * @param params - Parameters including signer, authenticator type, and optional overrides
+     * @param options - Optional request options
+     * @returns The transaction result including hash and transaction object
+     */
+    call(runtimeCall: RuntimeCall, params: {
+        signer: Signer;
+        authenticator: Authenticator;
+        overrides?: DeepPartial<UnsignedTransaction<RuntimeCall>>;
+    }, options?: SovereignClient__default.RequestOptions): Promise<TransactionResult<Transaction<RuntimeCall>>>;
+    /**
+     * Signs and submits a transaction with the specified authenticator.
+     *
+     * @param unsignedTx - The unsigned transaction to sign and submit
+     * @param params - Parameters including signer and authenticator type
+     * @param options - Optional request options
+     * @returns The transaction result
+     */
+    signAndSubmitTransaction(unsignedTx: UnsignedTransaction<RuntimeCall>, params: {
+        signer: Signer;
+        authenticator: Authenticator;
+    }, options?: SovereignClient__default.RequestOptions): Promise<TransactionResult<Transaction<RuntimeCall>>>;
+    /**
+     * Submits a standard transaction.
+     */
+    submitTransaction(transaction: StandardRollupSpec<RuntimeCall>["Transaction"], authenticator: "standard", options?: SovereignClient__default.RequestOptions): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
+    /**
+     * Submits a Solana offchain message.
+     */
+    submitTransaction(transaction: SolanaOffchainSimpleMessage, authenticator: "solanaSimple", options?: SovereignClient__default.RequestOptions): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
+    /**
+     * Submits a Solana spec-compliant message.
+     */
+    submitTransaction(transaction: SolanaOffchainSpecCompliantMessage, authenticator: "solana", options?: SovereignClient__default.RequestOptions): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
+    simulate(runtimeMessage: RuntimeCall, params: Parameters<StandardRollup<RuntimeCall>["simulate"]>[1]): Promise<SovereignClient__default.Rollup.RollupSimulateResponse>;
+    dedup(address: Uint8Array): Promise<Dedup>;
+    serializer(): Promise<Serializer>;
+    chainHash(): Promise<Uint8Array>;
+    healthcheck(timeout?: number): Promise<boolean>;
+    subscribe<T extends keyof SubscriptionToCallbackMap>(type: T, callback: SubscriptionToCallbackMap[T]): Subscription;
+    get context(): StandardRollupContext;
+    get ledger(): SovereignClient__default.Ledger;
+    get sequencer(): SovereignClient__default.Sequencer;
+    get rollup(): SovereignClient__default.Rollup;
+    get http(): SovereignClient__default;
+    /**
+     * Helper method to serialize a SolanaOffchainSimpleMessage using borsh encoding.
+     */
+    private serializeSolanaMessage;
+    /**
+     * Helper method to serialize a SolanaOffchainSpecCompliantMessage using borsh encoding.
+     */
+    private serializeSolanaSpecMessage;
+}
+declare function createSolanaSignableRollup<RuntimeCall>(rollupConfig?: Partial<RollupConfig<DeepPartial<StandardRollupContext>>>, solanaEndpoint?: string): Promise<SolanaSignableRollup<RuntimeCall>>;
+
 /**
  * Base error class for Sovereign SDK Web3.
  */
@@ -366,4 +565,4 @@ declare class SchemaError extends SovereignError {
     constructor(message: string, reason: string, schema: object);
 }
 
-export { type BaseTypeSpec, type CallParams, DEFAULT_TX_DETAILS, type Dedup, type EventPayload, InvalidRollupConfigError, Rollup, type RollupConfig, type RollupContext, type RollupTypeSpec, SchemaError, type SignerParams, type SimulateParams, SovereignError, StandardRollup, type StandardRollupContext, type StandardRollupSpec, type Subscription, type TransactionContext, type TransactionResult, type TypeBuilder, type UnsignedTransactionContext, VersionMismatchError, addressFromPublicKey, createStandardRollup, standardTypeBuilder };
+export { type Authenticator, type BaseTypeSpec, type CallParams, DEFAULT_TX_DETAILS, type Dedup, type EventPayload, InvalidRollupConfigError, Rollup, type RollupConfig, type RollupContext, type RollupTypeSpec, SchemaError, type SignerParams, type SimulateParams, type SolanaOffchainSimpleMessage, type SolanaOffchainSpecCompliantMessage, type SolanaOffchainUnsignedTransaction, SolanaSignableRollup, SovereignError, StandardRollup, type StandardRollupContext, type StandardRollupSpec, type Subscription, type TransactionContext, type TransactionResult, type TypeBuilder, type UnsignedTransactionContext, VersionMismatchError, addressFromPublicKey, createSolanaPreamble, createSolanaSignableRollup, createStandardRollup, standardTypeBuilder };