@sovereign-sdk/web3 0.14.1 → 0.15.0

package/dist/index.d.ts

@@ -4,7 +4,8 @@ import * as SovereignClient from '@sovereign-sdk/client';
 export { SovereignClient };
 import { RollupSchema as RollupSchema$1, Serializer as Serializer$1 } from '@sovereign-sdk/serializers';
 import { Signer } from '@sovereign-sdk/signers';
-import { TxDetails, UnsignedTransaction, Transaction, TransactionV1 } from '@sovereign-sdk/types';
+import { Multisig } from '@sovereign-sdk/multisig';
+import { TxDetails, UnsignedTransaction, TransactionSigningPayload, Transaction } from '@sovereign-sdk/types';
 
 /**
  * Encodes a public key as a bech32m address with the given human-readable part (hrp).
@@ -34,6 +35,22 @@ type EventPayload = {
         type: "moduleRef";
         name: string;
     };
+    /**
+     * The run of numbering this copy of the event is served under.
+     *
+     * Present on every event served by the sequencer, from its cache or read back from the
+     * ledger: the sequencer's epoch at the time of serving. Before applying this event to a
+     * state snapshot, check it against the `x-sov-event-epoch` header that snapshot came with:
+     * if they differ, the sequencer has discarded soft confirmations since the snapshot was
+     * taken and the client must resynchronise. Comparing `number` alone is not enough, because
+     * a rollback that re-emits past where it rewound leaves the number higher than before.
+     *
+     * Absent on events from the node's ledger API, which has no epoch. An absent epoch counts
+     * as the all-zero epoch, which only a publisher that never reissues numbers, such as the
+     * standard sequencer, reports. On a DA layer without instant finality, a DA reorg can still
+     * renumber events in non-finalized slots; no epoch guards against that.
+     */
+    epoch?: string;
 };
 interface SubscriptionToCallbackMap {
     events: (event: EventPayload) => Promise<void>;
@@ -54,6 +71,10 @@ type BaseTypeSpec = {
      * The type of unsigned transaction used in the rollup.
      */
     UnsignedTransaction: any;
+    /**
+     * The type of transaction signing payload used in the rollup.
+     */
+    TransactionSigningPayload: any;
     /**
      * The type of runtime call used in the rollup.
      */
@@ -128,14 +149,21 @@ type TransactionContext<S extends BaseTypeSpec, C extends RollupContext> = {
     signature: Uint8Array;
     rollup: Rollup<S, C>;
 };
+type TransactionSigningPayloadContext<S extends BaseTypeSpec, C extends RollupContext> = {
+    unsignedTx: S["UnsignedTransaction"];
+    chainHash: Uint8Array;
+    rollup: Rollup<S, C>;
+};
 type TypeBuilder<S extends BaseTypeSpec, C extends RollupContext> = {
     unsignedTransaction: (context: UnsignedTransactionContext<S, C>) => Promise<S["UnsignedTransaction"]>;
+    transactionSigningPayload: (context: TransactionSigningPayloadContext<S, C>) => Promise<S["TransactionSigningPayload"]>;
     transaction: (context: TransactionContext<S, C>) => Promise<S["Transaction"]>;
 };
 /**
  * Arbitrary context that is associated with the rollup.
  */
 type RollupContext = Record<string, unknown>;
+type CredentialIdToAddress = (credentialId: Uint8Array, schema: RollupSchema$1) => string;
 /**
  * The configuration for a rollup client.
  */
@@ -156,6 +184,10 @@ type RollupConfig<C extends RollupContext> = {
      * is detected then it will be called again with the new rollup schema.
      */
     getSerializer: (schema: RollupSchema$1) => Serializer$1;
+    /**
+     * Optional hook for converting multisig credential IDs into the rollup's native address format.
+     */
+    credentialIdToAddress?: CredentialIdToAddress;
     /**
      * Arbitrary context that is associated with the rollup.
      */
@@ -224,6 +256,16 @@ declare class Rollup<S extends BaseTypeSpec, C extends RollupContext> {
      * TODO: How to request a specific uniqueness strategy explicitly
      */
     dedup(publicKey: Uint8Array): Promise<S["Dedup"]>;
+    /**
+     * Retrieve dedup information about the provided credential ID.
+     */
+    dedupByCredentialId(credentialId: HexString): Promise<S["Dedup"]>;
+    /**
+     * Builds an unsigned transaction for the provided runtime call.
+     */
+    buildUnsignedTransaction(runtimeCall: S["RuntimeCall"], params?: {
+        overrides?: DeepPartial<S["UnsignedTransaction"]>;
+    }): Promise<S["UnsignedTransaction"]>;
     /**
      * Submits a transaction to the rollup.
      *
@@ -267,8 +309,8 @@ declare class Rollup<S extends BaseTypeSpec, C extends RollupContext> {
     prepareCall(runtimeCall: S["RuntimeCall"], { signer, overrides }: CallParams<S>): Promise<S["Transaction"]>;
     /**
      * Signs an unsigned transaction using the provided signer.
-     * Creates a signature by combining the serialized unsigned transaction with the chain hash,
-     * then constructs a fully signed transaction.
+     * Creates a signature over the serialized transaction signing payload, then constructs a fully
+     * signed transaction.
      *
      * @param unsignedTx - The unsigned transaction to sign.
      * @param signer - The signer to use for signing the transaction.
@@ -322,14 +364,18 @@ declare class Rollup<S extends BaseTypeSpec, C extends RollupContext> {
     private _fetchSchema;
 }
 
+declare function chainHashFragment(chainHash: Uint8Array): string;
+
 type Dedup = {
     nonce: number;
 };
 type StandardRollupContext = {
     defaultTxDetails: TxDetails;
+    credentialIdToAddress?: CredentialIdToAddress;
 };
 type StandardRollupSpec<RuntimeCall> = {
     UnsignedTransaction: UnsignedTransaction<RuntimeCall>;
+    TransactionSigningPayload: TransactionSigningPayload<RuntimeCall>;
     Transaction: Transaction<RuntimeCall>;
     RuntimeCall: RuntimeCall;
     Dedup: Dedup;
@@ -337,9 +383,23 @@ type StandardRollupSpec<RuntimeCall> = {
 declare function standardTypeBuilder<S extends StandardRollupSpec<unknown>>(): TypeBuilder<S, StandardRollupContext>;
 /**
  * The parameters for simulating a runtime call transaction.
+ *
+ * Adds `address_override` until `@sovereign-sdk/client` is republished with it.
+ * As of `0.1.0-alpha.39` the generated `RollupSimulateParams` is missing the
+ * field even though the Rust type and OpenAPI spec ship it (added in commit
+ * `6e7d22a52`). Once a newer client publishes `address_override` natively,
+ * drop this `Omit`-extension AND the `as SovereignClient.RollupSimulateParams`
+ * cast in `simulate()`.
  */
-type SimulateParams = Omit<SovereignClient__default.RollupSimulateParams, "call" | "sender"> & SignerParams;
+type SimulateParams = Omit<SovereignClient__default.RollupSimulateParams, "call" | "sender"> & SignerParams & {
+    address_override?: string | null;
+};
 declare class StandardRollup<RuntimeCall> extends Rollup<StandardRollupSpec<RuntimeCall>, StandardRollupContext> {
+    private updateDefaultChainHashFragment;
+    private credentialAddressFromId;
+    submitTransaction(transaction: StandardRollupSpec<RuntimeCall>["Transaction"], options?: SovereignClient__default.RequestOptions): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
+    hydrate(): Promise<void>;
+    multisigSigningBytes(unsignedTx: UnsignedTransaction<RuntimeCall>, multisig: Multisig): Promise<Uint8Array>;
     /**
      * Simulates a runtime call transaction.
      *
@@ -347,9 +407,9 @@ declare class StandardRollup<RuntimeCall> extends Rollup<StandardRollupSpec<Runt
      *
      * @param runtimeMessage - The runtime message to call.
      */
-    simulate(runtimeMessage: StandardRollupSpec<RuntimeCall>["RuntimeCall"], { signer }: SimulateParams): Promise<SovereignClient__default.Rollup.RollupSimulateResponse>;
+    simulate(runtimeMessage: StandardRollupSpec<RuntimeCall>["RuntimeCall"], { signer, ...params }: SimulateParams): Promise<SovereignClient__default.Rollup.RollupSimulateResponse>;
 }
-declare const DEFAULT_TX_DETAILS: Omit<TxDetails, "chain_id">;
+declare const DEFAULT_TX_DETAILS: Omit<TxDetails, "chain_hash_fragment">;
 declare function createStandardRollup<RuntimeCall, C extends StandardRollupContext = StandardRollupContext>(rollupConfig?: Partial<RollupConfig<DeepPartial<C>>>, typeBuilderOverrides?: Partial<TypeBuilder<StandardRollupSpec<RuntimeCall>, C>>): Promise<StandardRollup<RuntimeCall>>;
 
 /**
@@ -399,12 +459,12 @@ declare abstract class Serializer {
      */
     serializeRuntimeCall(input: unknown): Uint8Array;
     /**
-     * Serialize an unsigned transaction to Borsh bytes.
+     * Serialize a transaction signing payload to Borsh bytes.
      *
-     * @param input - The unsigned transaction to serialize.
+     * @param input - The transaction signing payload to serialize.
      * @returns The serialized Borsh bytes.
      */
-    serializeUnsignedTx(input: unknown): Uint8Array;
+    serializeSigningPayload(input: unknown): Uint8Array;
     /**
      * Serialize a transaction to Borsh bytes.
      *
@@ -416,24 +476,36 @@ declare abstract class Serializer {
     get schema(): RollupSchema;
 }
 
-type SolanaOffchainUnsignedTransaction<RuntimeCall> = UnsignedTransaction<RuntimeCall> & {
+type SolanaOffchainSigningPayloadV0<RuntimeCall> = Omit<UnsignedTransaction<RuntimeCall>, "address_override"> & {
     chain_name: string;
+    /**
+     * Message format version. Must be 0 for V0 payloads.
+     */
+    version: 0;
+    /**
+     * Signer-declared address override.
+     * See `AuthorizationData::address_override` (Rust) for routing semantics.
+     */
+    address_override?: string;
 };
-type SolanaOffchainUnsignedTransactionV1<RuntimeCall> = SolanaOffchainUnsignedTransaction<RuntimeCall> & {
-    multisig_id: string;
-    version: number;
+type SolanaOffchainSigningPayloadV1<RuntimeCall, MultisigId = unknown> = Omit<SolanaOffchainSigningPayloadV0<RuntimeCall>, "version"> & {
+    multisig_id: MultisigId;
+    /**
+     * Message format version. Must be 1 for V1 payloads.
+     */
+    version: 1;
 };
-type SolanaOffchainSimpleMessage = {
+type SolanaOffchainSimpleEnvelope = {
     signed_message: Uint8Array;
     chain_hash: Uint8Array;
     pubkey: Uint8Array;
     signature: Uint8Array;
 };
-type SolanaOffchainSpecCompliantMessage = {
+type SolanaOffchainSpecCompliantEnvelope = {
     signed_message_with_preamble: Uint8Array;
     signature: Uint8Array;
 };
-type SolanaOffchainSimpleMultisigMessage = {
+type SolanaOffchainSimpleMultisigEnvelope = {
     /** Wire format: [0x80][JSON payload]. The 0x80 prefix is a parsing discriminator only. */
     wire_bytes: Uint8Array;
     chain_hash: Uint8Array;
@@ -444,26 +516,14 @@ type SolanaOffchainSimpleMultisigMessage = {
     unused_pub_keys: Uint8Array[];
     min_signers: number;
 };
-type SolanaOffchainSpecCompliantMultisigMessage = {
+type SolanaOffchainSpecCompliantMultisigEnvelope = {
     signed_message_with_preamble: Uint8Array;
     signatures: Uint8Array[];
     signer_bitfield: number;
     min_signers: number;
 };
 type Authenticator = "standard" | "solanaSimple" | "solana" | "solanaAuto";
-type SolanaMultisigAuthenticator = "solanaSimple" | "solana";
-type SolanaMultisigParams = {
-    multisigAddress: Uint8Array;
-    multisigPubkeys: Uint8Array[];
-};
-type SolanaMultisigSubmitParams = {
-    authenticator: "standard";
-} | ({
-    authenticator: SolanaMultisigAuthenticator;
-} & SolanaMultisigParams);
-type SolanaMultisigSignParams = SolanaMultisigSubmitParams & {
-    signer: Signer;
-};
+type SubmissionAuthenticator = Exclude<Authenticator, "solanaAuto">;
 declare class SolanaSignableRollup<RuntimeCall> {
     private inner;
     private solanaEndpoint;
@@ -491,10 +551,6 @@ declare class SolanaSignableRollup<RuntimeCall> {
      * Submits a Solana spec-compliant multisig message to the rollup.
      */
     private submitSolanaSpecMultisigMessage;
-    /**
-     * Helper to build an unsigned transaction using the standard type builder.
-     */
-    private buildUnsignedTransaction;
     /**
      * Helper to build a transaction result object.
      */
@@ -509,7 +565,7 @@ declare class SolanaSignableRollup<RuntimeCall> {
      */
     private canonicalizeMultisigPubkeys;
     /**
-     * Helper to create and serialize a SolanaOffchainUnsignedTransaction to JSON bytes.
+     * Helper to create and serialize a SolanaOffchainSigningPayloadV0 to JSON bytes.
      */
     private createSolanaJsonBytes;
     /**
@@ -547,60 +603,51 @@ declare class SolanaSignableRollup<RuntimeCall> {
         signer: Signer;
         authenticator: Authenticator;
     }, options?: SovereignClient__default.RequestOptions): Promise<TransactionResult<Transaction<RuntimeCall>>>;
+    buildUnsignedTransaction(runtimeCall: RuntimeCall, params?: {
+        overrides?: DeepPartial<UnsignedTransaction<RuntimeCall>>;
+    }): Promise<UnsignedTransaction<RuntimeCall>>;
     /**
      * Creates V1 JSON bytes for a multisig transaction, including multisig_id and version.
      * The resulting JSON is what each signer signs directly (no discriminator prefix).
      */
     private createMultisigJsonBytes;
     /**
-     * Creates the preamble+JSON bytes signed by every signer in a spec-compliant multisig flow.
+     * Formats the multisig credential in the rollup's configured address format.
      */
-    private createSpecCompliantMultisigSignedMessage;
+    private multisigIdFromMultisig;
     /**
-     * Signs an unsigned transaction using Solana offchain simple multisig signing.
+     * Creates multisig state from a finalized transaction envelope.
      */
-    private signForSolanaSimpleMultisig;
+    private multisigFromTransaction;
+    private normalizeMultisigTransaction;
     /**
-     * Signs an unsigned transaction using the spec-compliant multisig preamble.
+     * Extracts the V0-shaped unsigned fields from a finalized multisig transaction.
      */
-    private signForSolanaSpecMultisig;
+    private unsignedTxFromTransaction;
     /**
-     * Signs an unsigned transaction for use in a Solana offchain multisig.
-     *
-     * `authenticator: "standard"` delegates directly to the wrapped standard rollup.
-     * `authenticator: "solanaSimple"` signs the V1 JSON payload directly.
-     * `authenticator: "solana"` signs the spec-compliant preamble+JSON bytes.
-     * Solana multisig authenticators treat `multisigPubkeys` as an unordered set and
-     * canonicalize it before signing.
+     * Creates the preamble+JSON bytes signed by every signer in a spec-compliant multisig flow.
      */
-    signTransactionForMultisig(unsignedTx: UnsignedTransaction<RuntimeCall>, params: SolanaMultisigSignParams): Promise<Transaction<RuntimeCall>>;
+    private createSpecCompliantMultisigSignedMessage;
+    multisigSigningBytes(unsignedTx: UnsignedTransaction<RuntimeCall>, multisig: Multisig, authenticator: SubmissionAuthenticator): Promise<Uint8Array>;
     /**
-     * Builds a spec-compliant multisig envelope from a V1 transaction and ordered multisig pubkeys.
+     * Builds a spec-compliant multisig envelope from a V1 transaction.
      */
     private buildSpecCompliantMultisigEnvelope;
     /**
-     * Submits a multisig transaction using the Solana offchain simple multisig format.
-     *
-     * Accepts the V1 transaction produced by `MultisigTransaction.asTransaction()`.
-     * `authenticator: "standard"` delegates directly to the wrapped standard rollup.
-     * Solana authenticators rebuild the appropriate Solana multisig envelope and
-     * submit it to the Solana offchain endpoint.
-     */
-    submitMultisigTransaction(multisigTx: TransactionV1<RuntimeCall>, params: SolanaMultisigSubmitParams): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
-    /**
-     * Submits a standard transaction.
+     * Submits a finalized V1 multisig transaction using a Solana authenticator.
      */
-    submitTransaction(transaction: StandardRollupSpec<RuntimeCall>["Transaction"], authenticator: "standard", options?: SovereignClient__default.RequestOptions): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
+    private submitMultisigTransactionWithAuthenticator;
     /**
-     * Submits a Solana offchain message.
+     * Submits a finalized V0 transaction using a Solana authenticator.
      */
-    submitTransaction(transaction: SolanaOffchainSimpleMessage, authenticator: "solanaSimple", options?: SovereignClient__default.RequestOptions): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
+    private submitSingleSignatureTransactionWithAuthenticator;
     /**
-     * Submits a Solana spec-compliant message.
+     * Submits a transaction with the specified authenticator.
      */
-    submitTransaction(transaction: SolanaOffchainSpecCompliantMessage, authenticator: "solana", options?: SovereignClient__default.RequestOptions): Promise<SovereignClient__default.Sequencer.TxCreateResponse>;
+    submitTransaction(transaction: Transaction<RuntimeCall>, authenticator: SubmissionAuthenticator, 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>;
+    dedupByCredentialId(credentialId: HexString): Promise<Dedup>;
     serializer(): Promise<Serializer>;
     chainHash(): Promise<Uint8Array>;
     /**
@@ -616,15 +663,15 @@ declare class SolanaSignableRollup<RuntimeCall> {
     get rollup(): SovereignClient__default.Rollup;
     get http(): SovereignClient__default;
     /**
-     * Helper method to serialize a SolanaOffchainSimpleMessage using borsh encoding.
+     * Helper method to serialize a SolanaOffchainSimpleEnvelope using borsh encoding.
      */
     private serializeSolanaMessage;
     /**
-     * Helper method to serialize a SolanaOffchainSpecCompliantMessage using borsh encoding.
+     * Helper method to serialize a SolanaOffchainSpecCompliantEnvelope using borsh encoding.
      */
     private serializeSolanaSpecMessage;
     /**
-     * Serializes a SolanaOffchainSimpleMultisigMessage using borsh encoding.
+     * Serializes a SolanaOffchainSimpleMultisigEnvelope using borsh encoding.
      * Layout matches the Rust struct:
      *   [u32 LE: wire_bytes.len][wire_bytes]
      *   [32 bytes: chain_hash]
@@ -636,7 +683,7 @@ declare class SolanaSignableRollup<RuntimeCall> {
      */
     private serializeSolanaMultisigMessage;
     /**
-     * Serializes a SolanaOffchainSpecCompliantMultisigMessage using borsh encoding.
+     * Serializes a SolanaOffchainSpecCompliantMultisigEnvelope using borsh encoding.
      * Layout matches the Rust struct:
      *   [u32 LE: signed_message_with_preamble.len][signed_message_with_preamble]
      *   [u32 LE: signatures.len]
@@ -668,4 +715,4 @@ declare class SchemaError extends SovereignError {
     constructor(message: string, reason: string, schema: object);
 }
 
-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 SolanaMultisigAuthenticator, type SolanaMultisigSignParams, type SolanaMultisigSubmitParams, type SolanaOffchainSimpleMessage, type SolanaOffchainSimpleMultisigMessage, type SolanaOffchainSpecCompliantMessage, type SolanaOffchainSpecCompliantMultisigMessage, type SolanaOffchainUnsignedTransaction, type SolanaOffchainUnsignedTransactionV1, SolanaSignableRollup, SovereignError, StandardRollup, type StandardRollupContext, type StandardRollupSpec, type Subscription, type TransactionContext, type TransactionResult, type TypeBuilder, type UnsignedTransactionContext, VersionMismatchError, addressFromPublicKey, createSolanaSignableRollup, createStandardRollup, standardTypeBuilder };
+export { type Authenticator, type BaseTypeSpec, type CallParams, type CredentialIdToAddress, DEFAULT_TX_DETAILS, type Dedup, type EventPayload, InvalidRollupConfigError, Rollup, type RollupConfig, type RollupContext, type RollupTypeSpec, SchemaError, type SignerParams, type SimulateParams, type SolanaOffchainSigningPayloadV0, type SolanaOffchainSigningPayloadV1, type SolanaOffchainSimpleEnvelope, type SolanaOffchainSimpleMultisigEnvelope, type SolanaOffchainSpecCompliantEnvelope, type SolanaOffchainSpecCompliantMultisigEnvelope, SolanaSignableRollup, SovereignError, StandardRollup, type StandardRollupContext, type StandardRollupSpec, type SubmissionAuthenticator, type Subscription, type TransactionContext, type TransactionResult, type TransactionSigningPayloadContext, type TypeBuilder, type UnsignedTransactionContext, VersionMismatchError, addressFromPublicKey, chainHashFragment, createSolanaSignableRollup, createStandardRollup, standardTypeBuilder };