Smart Contract Integration

This tutorial will guide you through integrating with Cardano smart contracts in the OADA UI project. You'll learn how to work with the Lucid library, manage transactions, handle UTxOs, and interact with Plutus smart contracts.

Integration Overview

The project integrates with:

• Cardano blockchain through Lucid

• Plutus smart contracts

• UTxO management system

• Real-time transaction monitoring

Lucid Integration

1. Base Configuration

The following code shows how we initialize the Lucid instance with a custom blockchain provider. This is the foundation for all Cardano blockchain interactions in the application. The BlockchainProvider is a custom implementation that handles network communication with the Cardano blockchain.

// src/store/hooks.ts
import { Lucid } from "lucid-cardano";
import { BlockchainProvider } from "./providers";

// Initialize Lucid with custom blockchain provider
export const lucid: LucidExt = await Lucid.new(
  new BlockchainProvider("", undefined),
  cardanoNetwork
);

2. Extended Lucid Interface

We extend the base Lucid interface to add additional functionality specific to our application. The LucidExt interface adds a new transaction builder method, while TxExt extends the base transaction interface with methods for collecting UTxOs, minting assets, and making payments to both addresses and smart contracts.

// src/lucid-ext.ts
export interface LucidExt extends Lucid {
  newTx(): TxExt;
}

export interface TxExt extends Tx {
  collectFrom(utxos: UTxO[], redeemer?: Redeemer): this;
  mintAssets(assets: Assets, redeemer?: Redeemer): this;
  payToAddress(address: Address, assets: Assets): this;
  payToContract(address: Address, datum: Datum, assets: Assets): this;
}

Transaction Management

1. Transaction Builder

The LucidTxPartialWrapper class implements a fluent interface for building Cardano transactions. It wraps the base Lucid transaction builder and adds additional methods for common operations like paying to smart contracts. This wrapper makes it easier to build complex transactions while maintaining type safety.

// src/tx.ts
class LucidTxPartialWrapper implements TxPartial {
  private lucidTx: LucidTx;

  payToContract(address: string, datum: string, assets: Assets): this {
    this.lucidTx = this.lucidTx.payToContract(address, datum, assets);
    return this;
  }

  // Additional transaction building methods...
}

2. Transaction Recipe

The transaction recipe system provides a high level abstraction for building complex transactions. The txRecipeToTx function takes a recipe (a declarative description of a transaction) and converts it into an actual Cardano transaction. It handles UTxO collection and script validation, making it easier to build transactions that interact with smart contracts.

// src/tx-recipe.ts
export const txRecipeToTx =
  (lucid: LucidExt) =>
  (txRecipe: TxRecipe): TxExt => {
    let tx = lucid.newTx();

    // Handle UTxO collection
    const txInRefUtxos = txRecipe.txInRefs.map(txInToUTxO);
    tx = tx.readFrom(txInRefUtxos);

    // Handle script validation
    if (txRecipe.script) {
      const validator = {
        type: "PlutusV2" as const,
        script: txRecipe.script.cbor,
      };
      tx = tx.attachSpendingValidator(validator);
    }

    // Additional transaction building...
    return tx;
  };

UTxO Management

1. UTxO Manager

The UTXOManager class provides a high level interface for managing UTxOs (Unspent Transaction Outputs). It handles fetching UTxOs from the blockchain, filtering spendable UTxOs, and optimizing UTxO selection for transactions. This class is crucial for managing the wallet's funds and ensuring efficient transaction building.

// src/utils/wallet-stuff.ts
export class UTXOManager {
  private readonly lucid: Lucid;
  private readonly address: string;

  async getUTXOs(address: string): Promise<UTXO[]> {
    const utxos = await this.lucid.utxosAt(address);
    return this.filterSpendableUTXOs(utxos);
  }

  async selectUTXOs(amount: bigint): Promise<UTXO[]> {
    const utxos = await this.getUTXOs(this.address);
    return this.optimizeUTXOSelection(utxos, amount);
  }
}

2. Virtual UTxO Tracking

The WalletUtxoMap type defines a data structure for tracking virtual UTxOs - UTxOs that are part of pending transactions. This tracking system helps prevent double-spending and ensures accurate balance calculations by maintaining relationships between wallet UTxOs and their corresponding output UTxOs.

// src/utils/wallet-stuff.ts
export type WalletUtxoMap = {
  outputUtxosRefByWalletUtxoId: {
    [walletUtxoId: string]: string;
  };
  outputUtxosByOutputUtxosRef: {
    [outputUtxosRef: string]: Server.Utxo[];
  };
  walletUtxoIdsByOutputUtxosRef: {
    [outputUtxosRef: string]: Set<string>;
  };
};

Smart Contract Interaction

1. Protocol Actions

The interactWithContract Redux thunk action handles smart contract interactions. It takes contract parameters, builds a transaction recipe, converts it to a transaction, signs it, and submits it to the blockchain. This action is used throughout the application for various smart contract interactions.

// src/oada/actions.ts
export const interactWithContract = createAsyncThunk(
  "oada/interactWithContract",
  async (params: ContractParams, { getState }) => {
    const { lucid } = getState().wallet;
    const txRecipe = buildContractInteractionRecipe(params);
    const tx = txRecipeToTx(lucid)(txRecipe);
    const signedTx = await tx.sign();
    const txHash = await signedTx.submit();
    return txHash;
  }
);

2. Script Validation

The handleScriptValidation function is responsible for attaching Plutus script validators to transactions. It checks if a script is provided and, if so, attaches it to the transaction with the appropriate type (in this case, PlutusV2). This is a crucial step for transactions that interact with smart contracts.

// src/tx-recipe.ts
const handleScriptValidation = (
  tx: TxExt,
  script: Script,
  redeemer?: Redeemer
) => {
  if (script.tag === "Script") {
    const validator = {
      type: "PlutusV2" as const,
      script: script.cbor,
    };
    tx = tx.attachSpendingValidator(validator);
  }
  return tx;
};

Best Practices

1. Transaction Building

   • Use transaction recipes for complex transactions

   • Handle UTxO selection carefully

   • Implement proper error handling

   • Use TypeScript for type safety

2. Smart Contract Interaction

   • Validate script parameters

   • Handle script execution errors

   • Implement proper witness handling

   • Use proper datum handling

3. UTxO Management

   • Track virtual UTxOs for pending transactions

   • Implement proper UTxO selection algorithms

   • Handle UTxO expiration

   • Manage dust UTxOs

4. Security

   • Validate all inputs

   • Handle script validation properly

   • Implement proper error handling

   • Use secure transaction signing

Next Steps

Now that you understand Cardano smart contract integration, you can proceed to:

1. Advanced UI Customization

2. Testing and Quality Assurance

Additional Resources

• Lucid Documentation

• Cardano Documentation

• Plutus Documentation

• CIP-30 Specification