Class Transaction

The Transaction class represents a transaction in the context of the application.

  • It handles various transaction operations like fetching PDA addresses, shuffling UTXOs, sending transactions and more.
  • This class encapsulates data related to a transaction, including inputs, parameters, remaining accounts and more.

Hierarchy

  • Transaction

Constructors

constructor

Properties

appParams? firstPath merkleTreeProgram? params proofInput provider remainingAccounts? shuffleEnabled transactionInputs

Methods

closeVerifierState compile compileAndProve getAppProof getIndices getInstructions getMint getPdaAddresses getProof getProofInternal getRootIndex sendAndConfirmTransaction sendTransaction shuffleUtxos getMerkleProofs getNullifierPdaPublicKey getRegisteredVerifierPda getSignerAuthorityPda getTokenAuthority getTransactionHash

Constructors

constructor

  • Creates an instance of the Transaction class.

    Throws

    TransactionError:

    • When the verifier needs to be application enabled but it's not.
    • When the node or browser wallet and senderFee used to instantiate yourself as relayer at deposit are inconsistent.

    Parameters

    • params: {
          appParams?: any;
          params: TransactionParameters;
          provider: Provider;
          shuffleEnabled?: boolean;
      }

      The parameters for the constructor.

      • Optional appParams?: any

        Parameters required for application-specific transactions.

      • params: TransactionParameters

        Contains all the parameters required for a transaction.

      • provider: Provider

        The provider used for the transaction.

      • Optional shuffleEnabled?: boolean

        A flag to enable shuffling of UTXOs.

    Returns Transaction

Properties

Optional appParams

appParams?: any

Parameters required for application-specific transactions.

firstPath

firstPath: string

Optional merkleTreeProgram

merkleTreeProgram?: Program<MerkleTreeProgram>

params

params: TransactionParameters

Contains all the parameters required for a transaction.

proofInput

proofInput: any

provider

provider: Provider

The provider used for the transaction.

Optional remainingAccounts

remainingAccounts?: {
    leavesPdaPubkeys?: remainingAccount[];
    nullifierPdaPubkeys?: remainingAccount[];
}

The remaining accounts after the transaction.

Type declaration

shuffleEnabled

shuffleEnabled: Boolean

A flag to enable shuffling of UTXOs.

transactionInputs

transactionInputs: {
    encryptedUtxos?: Uint8Array;
    proofBytes?: any;
    proofBytesApp?: any;
    publicInputs?: PublicInputs;
    publicInputsApp?: any;
    rootIndex?: BN;
}

The inputs for the transaction.

Type declaration

  • Optional encryptedUtxos?: Uint8Array
  • Optional proofBytes?: any
  • Optional proofBytesApp?: any
  • Optional publicInputs?: PublicInputs
  • Optional publicInputsApp?: any
  • Optional rootIndex?: BN

Methods

closeVerifierState

  • This method creates a Solana transaction to close the state of the verifier.

    • The transaction is sent and confirmed using the provider's wallet.
    • The method first checks if the necessary dependencies like the provider's wallet and the transaction parameters are properly defined.
    • If the appParams property is set, it uses those parameters to create the instruction.

    Note

    This method is used by applications not the relayer.

    Throws

    TransactionError: If the provider's wallet or the transaction parameters are not properly defined, or if the verifier program is undefined.

    Returns Promise<string>

    Returns a promise that resolves to the transaction signature if the transaction was successfully sent and confirmed.

compile

  • Async

    This asynchronous method prepares proof inputs for a transaction.

    • It starts by shuffling the UTXOs (Unspent Transaction Outputs) for both inputs and outputs.

    • The method then fetches the transaction integrity hash and ensures it is defined, otherwise throws an error.

    • It then proceeds to generate Merkle proofs for the input UTXOs and uses these proofs along with other transaction parameters to build the proofInput object.

    • If appParams are provided, the method calculates the transaction hash accordingly and adds it to the proofInput object.

    • Additionally, it prepares the proofInput for the application-specific logic by incorporating appParams.inputs and public keys of the input UTXOs.

    • The proofInput object is used later on in the transaction process to generate zk-SNARK proofs.

    Throws

    TransactionError: Throws an error if the transaction integrity hash is undefined after calling getTxIntegrityHash.

    Example

    const transaction = new Transaction(params);
    await transaction.compile();

    Returns Promise<void>

    Returns a Promise that resolves when the method has finished executing.

compileAndProve

  • Async

    This asynchronous method is an extension of the compile method that includes additional steps.

    • It not only compiles the transaction which includes preparing proof inputs and arranging the UTXOs in a specific order, but also generates the zk-SNARK proofs, fetches the root index from the on-chain Merkle tree and calculates the Program Derived Addresses (PDAs).

    • Next, it generates the proof for the transaction. If application parameters (appParams) are defined, it generates an additional proof for application-specific logic.

    • The method then fetches the index of the root of the local Merkle tree in the Merkle tree stored on-chain. This is an important step in validating the transaction, as it verifies that the state of the transaction matches the state of the on-chain Merkle tree.

    • Finally, it calculates and stores the Program Derived Addresses (PDAs) for the transaction. PDAs are used in the Solana program to handle accounts that are dynamically created during the execution of the program.

    Returns Promise<void>

    Returns a Promise that resolves when the method has finished executing.

getAppProof

  • Async

    This method generates an application-specific proof and assigns the results to 'proofBytesApp' and 'publicInputsApp' of 'transactionInputs'. It is used for general app verifier programs

    Throws

    Will throw an error if 'appParams' is not defined or 'path' is not defined in 'appParams'.

    Returns Promise<void>

    A promise that resolves when the application-specific proof generation and assignment is complete.

getIndices

  • This method computes the indices in which the asset for the UTXO is in the asset pubkeys array. Using these indices, the zero-knowledge proof circuit enforces that only UTXOs containing the assets in the asset pubkeys array are included in the transaction. This means that the UTXOs that are part of the transaction must correspond to the assets specified in the assetPubkeysCircuit array.

    Throws

    TransactionError: If the assetPubkeysCircuit property is not defined in the params object.

    Parameters

    • utxos: Utxo[]

      An array of UTXOs that are part of the transaction.

    Returns string[][][]

    Returns a three-dimensional array of strings that represent the indices of the assets in the asset pubkeys array.

getInstructions

  • Asynchronously generates an array of transaction instructions based on the provided transaction parameters.

    1. Validates that the required properties of transactionInputs and verifier are defined.
    2. Retrieves ordered instruction names from the verifier program by: a. Filtering instructions based on a suffix pattern (e.g., "First", "Second", "Third", etc.). b. Sorting instructions according to the order of suffixes.
    3. Constructs an input object containing the necessary data for encoding.
    4. Iterates through the instruction names, encoding the inputs and generating transaction instructions.
    5. Returns an array of generated transaction instructions.

    Parameters

    Returns Promise<TransactionInstruction[]>

    • Promise resolving to an array of generated transaction instructions.

getMint

  • This method returns the mint of the spl token in the utxo.

    Remark

    • If the publicAmountSpl parameter of the transaction parameters is zero, the method returns zero.
    • If the assetPubkeysCircuit property exists in the transaction parameters, the method returns the second item in the array.

    Throws

    TransactionError: When the assetPubkeysCircuit property is not available in the transaction parameters.

    Returns string | BN

    Returns a Big Number (BN) instance representing the mint value of the transaction.

getPdaAddresses

  • This method generates and stores PDA (Program Derived Addresses) for nullifier, leaves, and verifier state.

    • It first validates that all necessary data is present (transaction inputs, verifier IDL, relayer, remaining accounts).
    • It then generates PDAs for the nullifiers and output commitments (leaves) from the transaction inputs.
    • Finally, it generates the PDA for the verifier state, using the relayer's public key and the verifier program ID.

    Throws

    TransactionError: If any of the required properties (transaction inputs, verifier IDL, relayer, remaining accounts) are not properly defined.

    Example

    myTransaction.getPdaAddresses();

    Returns void

getProof

  • Async

    This method generates a proof and assigns the results to 'proofBytes' and 'publicInputs' of 'transactionInputs'. It is used for system verifier programs.

    Throws

    Will throw an error if any issue arises in the 'getProofInternal' method.

    Returns Promise<void>

    A promise that resolves when the proof generation and assignment is complete.

getProofInternal

  • Async

    This method generates and verifies a proof.

    Note

    • The proof inputs and public inputs are stored in the application verifier program's idl.

    Throws

    TransactionError:

    • Will throw an error if 'verifierIdl' is missing in TransactionParameters.
    • Will throw an error if the proof generation fails.
    • Will throw an error if the proof is invalid.

    Parameters

    • params: any

      An object that contains parameters for the transaction.

    • firstPath: string

      The first path to be used by the Prover Class.

    Returns Promise<{
        parsedProof: {
            proofA: number[];
            proofB: number[][];
            proofC: number[];
        };
        parsedPublicInputsObject: any;
    }>

    A promise that resolves to an object with 'parsedProof' and 'parsedPublicInputsObject'.

getRootIndex

  • Async

    For this method the essence is that the merkle tree root index is sent to the program onchain as instruction data instead of the complete root because of two things.

    • To check that the root exists onchain (which we can check in constant time if we know the index of the root in the root history array of the Merkle tree pda).
    • To save 24 bytes of data in the instruction data by sending a u64 of 8 bytes instead of the root hash of 32 bytes.

    Remark

    • If the provider or the merkle tree are not defined in the provider.solMerkleTree, it defaults the root index to 0.
    • Otherwise, it fetches the merkle tree account data and finds the root index from there.

    Throws

    TransactionError:

    • If the root index is not found in the merkle tree account data.

    Returns Promise<void>

    Returns a promise that resolves when the method has completed. The resolved value is undefined.

sendAndConfirmTransaction

  • This method prepares, sends, and then confirms a transaction on the Solana blockchain.

    • The transaction is sent using the provider's connection and the transaction parameters.
    • If the appParams property is set, it uses those parameters to get the instructions.

    Throws

    TransactionError: If there's an issue with sending the transaction, or if it fails to get the transaction instructions.

    Example

    const transactionSignature = await myTransaction.sendAndConfirmTransaction();

    Returns Promise<string>

    Returns a promise that resolves to the transaction signature if the transaction was successfully sent and confirmed.

sendTransaction

  • This method sends a transaction to the Solana blockchain.

    • If the action of the transaction parameters is not SHIELD, the transaction will be sent to a relayer.
    • Otherwise, it will be sent directly using the provider's connection.

    Throws

    TransactionError: If the provider's connection, transaction parameters, relayer, root index, or remaining accounts are not properly defined.

    Example

    const transactionSignature = await myTransaction.sendTransaction(instruction);

    Parameters

    • ix: any

      The transaction instruction to be sent.

    Returns Promise<undefined | string>

    Returns a promise that resolves to the transaction signature if the transaction was successfully sent, or undefined if there was an issue.

shuffleUtxos

  • Shuffles the array of Unspent Transaction Outputs (UTXOs) in-place using the Fisher-Yates (aka Knuth) algorithm.

    Note

    The method is useful when you want to add an additional layer of unpredictability to the transactions.

    Throws

    TransactionError: If the shuffle operation is not enabled.

    Example

    const shuffledUtxos = shuffleUtxos(utxosArray);

    Parameters

    • utxos: Utxo[]

      An array of unspent transaction outputs that will be shuffled.

    Returns undefined | Utxo[]

    • The shuffled array of UTXOs.

Static getMerkleProofs

  • This method retrieves the Merkle proofs for each input UTXO where amounts are greater than 0.

    • For input UTXOs where amounts equal 0, it returns Merkle paths with all elements equal to 0.
    • This is important for the verification of transactions, where a Merkle proof is used to demonstrate the inclusion of a transaction within a Merkle tree stored on the Solana blockchain, without revealing the entire tree.

    Throws

    TransactionError: If the solMerkleTree is not defined in the provider object.

    Example

    const { inputMerklePathIndices, inputMerklePathElements } = Transaction.getMerkleProofs(provider, inputUtxos);

    Parameters

    • provider: Provider

      The provider instance that includes the solMerkleTree.

    • inputUtxos: Utxo[]

      An array of input UTXOs to retrieve the Merkle proofs for.

    Returns {
        inputMerklePathElements: string[][];
        inputMerklePathIndices: string[];
    }

    Returns an object that includes two properties: inputMerklePathIndices and inputMerklePathElements. inputMerklePathIndices is an array of strings representing the indices of the input UTXOs within the Merkle tree. inputMerklePathElements is a two-dimensional array of strings representing the path elements of the input UTXOs within the Merkle tree.

    • inputMerklePathElements: string[][]
    • inputMerklePathIndices: string[]

Static getNullifierPdaPublicKey

  • Parameters

    • nullifier: number[]
    • merkleTreeProgramId: PublicKey

    Returns PublicKey

Static getRegisteredVerifierPda

  • This method derives the Program Derived Address (PDA) for a registered verifier by using the provided Merkle tree and verifier program public keys. Similar to getSignerAuthorityPda method, this derived address can be used by the program for additional control and security.

    Example

    const registeredVerifierPda = Transaction.getRegisteredVerifierPda(merkleTreeProgramId, verifierProgramId);

    Parameters

    • merkleTreeProgramId: PublicKey

      The public key of the Merkle tree program.

    • verifierProgramId: PublicKey

      The public key of the verifier program.

    Returns PublicKey

    Returns the derived PublicKey of the registered verifier PDA.

Static getSignerAuthorityPda

  • Description

    This method derives the Program Derived Address (PDA) for a signer authority by using the provided Merkle tree and verifier program public keys. The PDA serves as an account that the program itself controls, providing an additional layer of security and flexibility in Solana programs.

    Example

    const signerAuthorityPda = Transaction.getSignerAuthorityPda(merkleTreeProgramId, verifierProgramId);

    Parameters

    • merkleTreeProgramId: PublicKey

      The public key of the Merkle tree program.

    • verifierProgramId: PublicKey

      The public key of the verifier program.

    Returns PublicKey

    Returns the derived PublicKey of the signer authority PDA.

Static getTokenAuthority

  • This static method retrieves the Program Derived Address (PDA) that is associated with the SPL tokens within the context of the Merkle Tree Program.

    Remarks

    • This method utilizes the findProgramAddressSync method of the PublicKey class which returns a PDA based on the provided seeds and program ID.
    • The seed here is a UTF-8 encoded string "spl".

    Returns PublicKey

    The PDA related to the SPL tokens within the context of the Merkle Tree Program.

Static getTransactionHash

  • Static

    This static method is used to generate the hash of a transaction. It is a poseidon hash that commits to all parameters contained in the shielded transaction (all commitment hashes, and the tx integrity hash).

    • It takes the transaction parameters and a poseidon instance as arguments.
    • It generates separate hashes for input UTXOs and output UTXOs and combines them with the txIntegrityHash to produce the transaction hash.

    Throws

    TransactionError:When the txIntegrityHash property is not available in the transaction parameters.

    Parameters

    • params: TransactionParameters

      The transaction parameters object. It should contain the inputUtxos, outputUtxos and txIntegrityHash properties.

    • poseidon: any

      The Poseidon hash function instance used for hashing.

    Returns string

    Returns a string representing the transaction hash.

Settings

Member Visibility

Theme

On This Page

Generated using TypeDoc