stellar-plus/lib/stellar-plus/core/contract-engine/index.d.ts

beta version of stellar-plus, an all-in-one sdk for the Stellar blockchain

import { Buffer } from 'buffer';
import { rpc as SorobanRpcNamespace, xdr } from '@stellar/stellar-sdk';
import { BaseInvocation, ContractConstructor, ContractEngineConstructorArgs, RestoreFootprintArgs, SorobanInvokeArgs, SorobanSimulateArgs, WrapClassicAssetArgs } from '../../../stellar-plus/core/contract-engine/types';
import { SorobanTransactionPipelineOutput } from '../../../stellar-plus/core/pipelines/soroban-transaction/types';
import { RpcHandler } from '../../../stellar-plus/rpc/types';
export declare class ContractEngine {
    private spec?;
    private contractId?;
    private wasm?;
    private wasmHash?;
    private networkConfig;
    private rpcHandler;
    private sorobanTransactionPipeline;
    private options;
    /**
     *
     * @param {NetworkConfig} networkConfig - The network to use.
     * @param contractParameters - The contract parameters.
     * @param {Spec} contractParameters.spec - The contract specification object.
     * @param {string=} contractParameters.contractId - The contract id.
     * @param {Buffer=} contractParameters.wasm - The contract wasm file as a buffer.
     * @param {string=} contractParameters.wasmHash - The contract wasm hash id.
     * @param {Options=} options - A set of custom options to modify the behavior of the contract engine.
     * @param {SorobanTransactionPipelineOptions=} options.sorobanTransactionPipeline - The Soroban transaction pipeline.
     * @description - The contract engine is used for interacting with contracts on the network. This class can be extended to create a contract client, abstracting away the Soroban integration.
     *
     * @example - The following example shows how to invoke a contract method that alters the state of the contract.
     * ```typescript
     * const contract = new ContractEngine(network, spec, contractId)
     *
     * const output = await contract.invoke({
     *   method: 'add',
     *   args: {
     *     a: 1,
     *     b: 2,
     *   },
     *   signers: [accountHandler],
     * })
     *
     * console.log(output) // 3
     * ```
     *
     * @example - The following example shows how to invoke a contract method that does not alter the state of the contract.
     * ```typescript
     * const contract = new ContractEngine(network, spec, contractId)
     * const output = await contract.read({
     *  method: 'get',
     * args: {
     *  key: 'myKey',
     * },
     * })
     * console.log(output) // 'myValue'
     * ```
     */
    constructor(args: ContractEngineConstructorArgs);
    getContractId(): string;
    getWasm(): Buffer;
    getWasmHash(): string;
    getContractFootprint(): xdr.LedgerKey;
    getRpcHandler(): RpcHandler;
    /**
     *
     * @param {void} args - No arguments.
     *
     * @returns {Promise<number>} The 'liveUntilLedgerSeq' value representing the ledger sequence number until which the contract instance is live.
     *
     * @description - Returns the ledger sequence number until which the contract instance is live. When the contract instance is live, it can be invoked. When the liveUntilLedgerSeq is reached, the contract instance is archived and can no longer be invoked until a restore is performed.
     
     */
    getContractInstanceLiveUntilLedgerSeq(): Promise<number>;
    /**
     *
     * @param {void} args - No arguments.
     *
     * @returns {Promise<number>} The 'liveUntilLedgerSeq' value representing the ledger sequence number until which the contract code is live.
     *
     * @description - Returns the ledger sequence number until which the contract code is live. When the contract code is live, it can be deployed into new instances, generating a new unique contract id for each. When the liveUntilLedgerSeq is reached, the contract code is archived and can no longer be deployed until a restore is performed.
     *
     * */
    getContractCodeLiveUntilLedgerSeq(): Promise<number>;
    /**
     *
     * @args {SorobanSimulateArgs<object>} args - The arguments for the invocation.
     * @param {string} args.method - The method to invoke as it is identified in the contract.
     * @param {object} args.methodArgs - The arguments for the method invocation.
     * @param {EnvelopeHeader} args.header - The header for the invocation.
     *
     * @returns {Promise<unknown>} The output of the invocation.
     *
     * @description - Simulate an invocation of a contract method that does not alter the state of the contract.
     * This function does not require any signers. It builds a transaction, simulates it, and extracts the output of the invocation from the simulation.
     *
     * @example - The following example shows how to simulate a contract method invocation.
     * ```typescript
     * const contract = new ContractEngine(network, spec, contractId)
     * const output = await contract.read({
     *  method: 'get',
     * args: {
     *  key: 'myKey',
     * },
     * })
     * console.log(output) // 'myValue'
     * ```
     */
    readFromContract(args: SorobanSimulateArgs<object>): Promise<SorobanTransactionPipelineOutput>;
    /**
     *
     * @args {SorobanInvokeArgs<object>} args - The arguments for the invocation.
     * @param {string} args.method - The method to invoke as it is identified in the contract.
     * @param {object} args.methodArgs - The arguments for the method invocation.
     * @param {EnvelopeHeader} args.header - The header for the invocation.
     * @param {AccountHandler[]} args.signers - The signers for the invocation.
     * @param {FeeBumpHeader=} args.feeBump - The fee bump header for the invocation.
     *
     * @returns {Promise<unknown>} The output of the invocation.
     *
     * @description - Invokes a contract method that alters the state of the contract.
     * This function requires signers. It builds a transaction, simulates it, signs it, submits it to the network, and extracts the output of the invocation from the processed transaction.
     *
     * @example - The following example shows how to invoke a contract method that alters the state of the contract.
     * ```typescript
     * const contract = new ContractEngine(network, spec, contractId)
     *
     * const output = await contract.invoke({
     *   method: 'add',
     *   args: {
     *     a: 1,
     *     b: 2,
     *   },
     *   signers: [accountHandler],
     * })
     *
     * console.log(output) // 3
     * ```
     */
    invokeContract(args: SorobanInvokeArgs<object> | SorobanSimulateArgs<object>): Promise<SorobanTransactionPipelineOutput>;
    runTransactionPipeline(args: SorobanInvokeArgs<object> | SorobanSimulateArgs<object>): Promise<SorobanTransactionPipelineOutput>;
    /**
     * @param {TransactionInvocation} txInvocation - The transaction invocation object to use in this transaction.
     *
     * @description - Uploads the contract wasm to the network and stores the wasm hash in the contract engine.
     *
     * @requires - The wasm file buffer to be set in the contract engine.
     *
     * */
    uploadWasm(args: BaseInvocation): Promise<SorobanTransactionPipelineOutput>;
    /**
     * @param {TransactionInvocation} txInvocation - The transaction invocation object to use in this transaction.
     *
     * @description - Deploys a new instance of the contract to the network and stores the contract id in the contract engine.
     *
     * @requires - The wasm hash to be set in the contract engine.
     *
     * */
    deploy(args: BaseInvocation & ContractConstructor<object>): Promise<SorobanTransactionPipelineOutput>;
    wrapAndDeployClassicAsset(args: WrapClassicAssetArgs): Promise<SorobanTransactionPipelineOutput | void>;
    restoreContractInstance(args: BaseInvocation): Promise<void>;
    /**
     *
     * @param {TransactionInvocation} txInvocation - The transaction invocation object to use in this transaction.
     *
     * @returns {Promise<void>} - The output of the invocation.
     *
     * @description - Restores the contract code.
     */
    restoreContractCode(args: BaseInvocation): Promise<void>;
    /**
     *
     * @param {void} args - No arguments.
     *
     * @returns {Promise<void>} - The output of the invocation.
     *
     * @description - Loads the contract specification from the wasm file and stores it in the contract engine.
     */
    loadSpecFromWasm(): Promise<void>;
    private requireContractId;
    private requireNoContractId;
    private requireWasm;
    private requireWasmHash;
    private requireSpec;
    protected getContractCodeLedgerEntry(): Promise<SorobanRpcNamespace.Api.LedgerEntryResult>;
    protected getContractInstanceLedgerEntry(): Promise<SorobanRpcNamespace.Api.LedgerEntryResult>;
    /**
     * @args {RestoreFootprintArgs} args - The arguments for the invocation.
     * @param {EnvelopeHeader} args.header - The header for the transaction.
     * @param {AccountHandler[]} args.signers - The signers for the transaction.
     * @param {FeeBumpHeader=} args.feeBump - The fee bump header for the transaction. This is optional.
     *
     * Option 1: Provide the keys directly.
     * @param {xdr.LedgerKey[]} args.keys - The keys to restore.
     * Option 2: Provide the restore preamble.
     * @param { RestoreFootprintWithRestorePreamble} args.restorePreamble - The restore preamble.
     * @param {string} args.restorePreamble.minResourceFee - The minimum resource fee.
     * @param {SorobanDataBuilder} args.restorePreamble.transactionData - The transaction data.
     *
     * @returns {Promise<void>}
     *
     * @description - Execute a transaction to restore a given footprint.
     */
    protected restore(args: RestoreFootprintArgs): Promise<void>;
}