@stellar/stellar-sdk
Version:
A library for working with the Stellar network, including communication with the Horizon and Soroban RPC servers.
290 lines (289 loc) • 10.9 kB
TypeScript
import { Transaction, xdr } from "../base/index.js";
import type { SignAuthEntryLike, SignTransactionLike } from "./signer.js";
import { Server } from "../rpc/index.js";
export type XDR_BASE64 = string;
/**
* An unsigned 32-bit integer.
*/
export type u32 = number;
/**
* A signed 32-bit integer.
*/
export type i32 = number;
/**
* An unsigned 64-bit integer.
*/
export type u64 = bigint;
/**
* A signed 64-bit integer.
*/
export type i64 = bigint;
/**
* An unsigned 128-bit integer.
*/
export type u128 = bigint;
/**
* A signed 128-bit integer.
*/
export type i128 = bigint;
/**
* An unsigned 256-bit integer.
*/
export type u256 = bigint;
/**
* A signed 256-bit integer.
*/
export type i256 = bigint;
export type Option<T> = T | undefined;
/**
* @deprecated Use {@link Timepoint} instead.
*/
export type Typepoint = bigint;
/**
* An unsigned 64-bit integer.
*/
export type Timepoint = bigint;
/**
* An unsigned 64-bit integer.
*/
export type Duration = bigint;
/**
* A "regular" transaction, as opposed to a FeeBumpTransaction.
*/
export type Tx = Transaction;
export interface WalletError {
message: string;
code: number;
ext?: Array<string>;
}
/**
* A function to request a wallet to sign a built transaction
*
* This function takes an XDR provided by the requester and applies a signature to it.
* It returns a base64-encoded string XDR-encoded Transaction Envelope with Decorated Signatures
* and the signer address back to the requester.
*
* @param xdr - The XDR string representing the transaction to be signed.
* @param opts - Options for signing the transaction.
* - `networkPassphrase`: The network's passphrase on which the transaction is intended to be signed.
* - `address`: The public key of the account that should be used to sign.
* - `submit`: If set to true, submits the transaction immediately after signing.
* - `submitUrl`: The URL of the network to which the transaction should be submitted, if applicable.
*
* @returns A promise resolving to an object with the signed transaction XDR and optional signer address and error.
*/
export type SignTransaction = (xdr: string, opts?: {
networkPassphrase?: string;
address?: string;
submit?: boolean;
submitUrl?: string;
}) => Promise<{
signedTxXdr: string;
signerAddress?: string;
} & {
error?: WalletError;
}>;
/**
* A function to request a wallet to sign an authorization entry preimage.
*
* Similar to signing a transaction, this function takes an authorization entry preimage provided by the
* requester and applies a signature to it.
* It returns a signed hash of the same authorization entry and the signer address back to the requester.
*
* @param authEntry - The authorization entry preimage to be signed.
* @param opts - Options for signing the authorization entry.
* - `networkPassphrase`: The network's passphrase on which the authorization entry is intended to be signed.
* - `address`: The public key of the account that should be used to sign.
*
* @returns A promise resolving to an object with the signed authorization entry and optional signer address and error.
*/
export type SignAuthEntry = (authEntry: string, opts?: {
networkPassphrase?: string;
address?: string;
}) => Promise<{
signedAuthEntry: string;
signerAddress?: string;
} & {
error?: WalletError;
}>;
/**
* Options for a smart contract client.
*/
export type ClientOptions = {
/**
* The public key of the source account for this transaction. You can
* override this for specific methods later; see {@link MethodOptions}.
*/
publicKey?: string;
/**
* A function to sign the transaction using the private key corresponding to
* the given `publicKey`. You do not need to provide this, for read-only
* calls, which only need to be simulated. If you do not provide it during
* initialization, you can provide it later, either when you initialize a
* method (see {@link MethodOptions}) or when you call
* {@link contract.AssembledTransaction.signAndSend | signAndSend}.
*
* Matches signature of `signTransaction` from Freighter. May instead be a
* {@link Signer} or a {@link Keypair}, which are converted internally.
*/
signTransaction?: SignTransactionLike;
/**
* A function to sign a specific auth entry for a transaction, using the
* private key corresponding to the provided `publicKey`. This is only needed
* for multi-auth transactions, in which one transaction is signed by
* multiple parties. If you do not provide it during initialization, you can
* provide it later either when you initialize a method (see {@link MethodOptions})
* or when you call {@link contract.AssembledTransaction.signAuthEntries | signAuthEntries}.
*
* Matches signature of `signAuthEntry` from Freighter. May instead be a
* {@link Signer} or a {@link Keypair}, which are converted internally.
*/
signAuthEntry?: SignAuthEntryLike;
/** The address of the contract the client will interact with. */
contractId: string;
/**
* The network passphrase for the Stellar network this contract is deployed
* to.
*/
networkPassphrase: string;
/**
* The URL of the RPC instance that will be used to interact with this
* contract.
*/
rpcUrl: string;
/**
* If true, will allow HTTP requests to the RPC. If false, will
* only allow HTTPS requests.
* @defaultValue false
*/
allowHttp?: boolean;
/** Optional headers to include in requests to the RPC. */
headers?: Record<string, string>;
/**
* This gets filled in automatically from the ContractSpec when you
* instantiate a {@link Client}.
*
* Background: If the contract you're calling uses the `#[contracterror]`
* macro to create an `Error` enum, then those errors get included in the
* on-chain XDR that also describes your contract's methods. Each error will
* have a specific number.
*
* A Client makes method calls with an {@link contract.AssembledTransaction | AssembledTransaction}.
* When one of these method calls encounters an error, `AssembledTransaction`
* will first attempt to parse the error as an "official" `contracterror`
* error, by using this passed-in `errorTypes` object. See `parseError`
* on {@link contract.AssembledTransaction}. If `errorTypes` is blank or no
* matching error is found, then it will throw the raw error.
* @defaultValue `{}`
*/
errorTypes?: Record<number, {
message: string;
}>;
/**
* The Server instance to use for RPC calls. If not provided, one will be
* created automatically from `rpcUrl` and `serverOptions`.
*/
server?: Server;
};
/**
* Options for a smart contract method invocation.
*/
export type MethodOptions = {
/**
* The fee to pay for the transaction.
* @defaultValue 100
*/
fee?: string;
/**
* The timebounds which should be set for transactions generated by this
* contract client. {@link contract.DEFAULT_TIMEOUT}
* @defaultValue 300
*/
timeoutInSeconds?: number;
/**
* Whether to automatically simulate the transaction when constructing the
* AssembledTransaction.
* @defaultValue true
*/
simulate?: boolean;
/**
* If true, will automatically attempt to restore the transaction if there
* are archived entries that need renewal.
* @defaultValue false
*/
restore?: boolean;
/**
* If true, simulation records v2 address credentials (CAP-71) instead of
* the legacy v1 address credentials. Best-effort: it only affects the
* recording auth modes and is silently ignored on protocol versions whose
* host cannot emit v2 credentials.
*
* @deprecated This flag is transitional. Once the network returns v2
* credentials by default (protocol 28), it becomes a no-op — do not rely on
* omitting it to keep receiving the legacy v1 format.
* @defaultValue false
*/
useUpgradedAuth?: boolean;
/**
* The public key of the source account for this transaction.
*
* Default: the one provided to the {@link Client} in {@link ClientOptions}
*/
publicKey?: string;
/**
* A function to sign the transaction using the private key corresponding to
* the given `publicKey`. You do not need to provide this, for read-only
* calls, which only need to be simulated.
*
* Matches signature of `signTransaction` from Freighter. May instead be a
* {@link Signer} or a {@link Keypair}, which are converted internally.
*
* Default: the one provided to the {@link Client} in {@link ClientOptions}
*/
signTransaction?: SignTransactionLike;
/**
* A function to sign a specific auth entry for a transaction, using the
* private key corresponding to the provided `publicKey`. This is only needed
* for multi-auth transactions, in which one transaction is signed by
* multiple parties.
*
* Matches signature of `signAuthEntry` from Freighter. May instead be a
* {@link Signer} or a {@link Keypair}, which are converted internally.
*
* Default: the one provided to the {@link Client} in {@link ClientOptions}
*/
signAuthEntry?: SignAuthEntryLike;
};
export type AssembledTransactionOptions<T = string> = MethodOptions & ClientOptions & {
method: string;
args?: any[];
parseResultXdr: (xdr: xdr.ScVal) => T;
/**
* The address of the account that should sign the transaction. Useful when
* a wallet holds multiple addresses to ensure signing with the intended one.
*/
address?: string;
/**
* This option will be passed through to the SEP43-compatible wallet extension. If true, and if the wallet supports it, the transaction will be signed and immediately submitted to the network by the wallet, bypassing the submit logic in {@link SentTransaction}.
* @defaultValue false
*/
submit?: boolean;
/**
* The URL of the network to which the transaction should be submitted.
* Only applicable when 'submit' is set to true.
*/
submitUrl?: string;
};
/**
* The default timebounds, in seconds, during which a transaction will be valid.
* This is attached to the transaction _before_ transaction simulation (it is
* needed for simulation to succeed). It is also re-calculated and re-added
* _before_ transaction signing.
* @defaultValue 300
*/
export declare const DEFAULT_TIMEOUT: number;
/**
* An impossible account on the Stellar network
* @defaultValue GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF
*/
export declare const NULL_ACCOUNT = "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF";