JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • 0
  • Score
    100M100P100Q31714F
  • License Apache-2.0

A set of tools to develop frontends that interact with the Plutus Application Backend.

Package Exports

  • cardano-pab-client
  • cardano-pab-client/dist/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (cardano-pab-client) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Cardano PAB client library

Instalation

npm i cardano-pab-client

Basic usage

It follows a simple use case of the entire flow for starting a contract: first getting the unbalanced transaction from a PAB, then balancing, signing and submitting it to the blockchain.

function startContract(): ContractEndpoints {
  // NOTE: all the modules of this library MUST be imported dynamically like this
  const {
    CIP30WalletWrapper,
    Balancer,
    getProtocolParamsFromBlockfrost,
  } = await import("cardano-pab-client");

  // initialize cip30 wallet
  // assuming we already have initialized the CIP30 wallet in the browser environment
  const wallet = await CIP30WalletWrapper.init(walletInjectedFromBrowser);

  // Initialize Balancer
  const protocolParams = await getProtocolParamsFromBlockfrost(
    "https://cardano-preprod.blockfrost.io/api/v0",
    "preprodXXXXXXXXXXXXXXXX",
  );
  const balancer = await Balancer.init(protocolParams);

  // Try to get unbalanced transaction from PAB
  const walletId = await wallet.getWalletId();
  const pabApi = new PABApi("http://localhost:9080");

  const [endpoints, pabResponse] = await ContractEndpoints.start(
    walletId,
    { endpointTag: "Init", params: [] },
    pabApi,
  );

  if (!succeeded(pabResponse)) {
    alert(
      `Didn't got the unbalanced transaction from the PAB. Error: ${pabResponse.error}`
    );
  } else {
    // the pab yielded the unbalanced transaction. balance, sign and submit it.
    const etx = pabResponse.value;

    const walletInfo = await wallet.getWalletInfo();
    const txBudgetApi = new TxBudgetAPI({
      baseUrl: "http//:localhost:3001",
      timeout: 10000,
    });

    const fullyBalancedTx = await balancer.fullBalanceTx(
      etx,
      walletInfo,
      // configuration for the balanceTx and rebalanceTx methods which are interally
      // used by this method
      { feeUpperBound: 1000000, mergeSignerOutputs: false },
      // a high-order function that exposes the balanced tx and the inputs info so to
      // calculate the executions units, which are then set in the transaction and
      // goes to the rebalancing step
      async (balancedTx, inputsInfo) => {
        const txBudgetResponse = await txBudgetApi.estimate(balancedTx, inputsInfo);
        if (succeeded(txBudgetResponse)) {
            const units = txBudgetResponse.value;
            return units;
        }
        // if the tx budget service fails or it isn't available,
        // fallback to hardcoded units

        // directly use the serialization library is useful here
        // must be dynamically imported too!
        const { SerLibLoader } = await import("cardano-pab-client");
        await SerLibLoader.load();
        const S = SerLibLoader.lib;

        // parse the transaction cbor into a nice format
        const tx = S.Transaction.from_hex(balancedTx).to_js_value();
        // ... here you have all the info of the transaction
        // in particular, access to the redeemers like so
        const { redeemers } = tx.witness_set;
        // also, have the complete information about the inputs (not only
        // the references) in the inputsInfo object

        if (redeemers) {
          redeemers.forEach((r: S.RedeemerJSON) => /*...*/);
          // do stuff...
          return [
            [{ tag: "Mint", index: 0 }, { mem: 4000000, cpu: 1500000000 }],
            [{ tag: "Spend", index: 2 }, { mem: 6000000, cpu: 1800000000 }],
            // ...
          ];
        }
        // no redeemers, so no hardcoded units are needed.
        return [];
      },
    );
    // print to the console the fully balanced tx cbor for debugging purposes
    console.log(`Balanced tx: ${fullyBalancedTx}`);
    // now that the transaction is balanced, sign and submit it with the wallet
    const response = await wallet.signAndSubmit(fullyBalancedTx);
    if (succeeded(response)) {
      const txHash = response.value;
      alert(`Start suceeded. Tx hash: ${txHash}`);
    } else {
      alert(`Start failed when trying to submit it. Error: ${response.error}`);
    }
  }
  // the ContractEndpoints instance is connected to the PAB, so we can return it to
  // continue doing operations with it.
  return endpoints;
}

For getting the CIP30 wallet from the user's browser, we have an utility that could be used within a React hook or something like it.

const {
  getWalletInitialAPI,
  CIP30WalletWrapper,
} = await import("cardano-pab-client");

const walletInitialAPI = getWalletInitialAPI(window, "eternl");
// or
// const walletInitialAPI = getWalletInitialAPI(window, "nami");

// this will ask the user to give to this dApp access to their wallet methods
const walletInjectedFromBrowser = await walletInitialAPI.enable();

// then we can initialize the CIP30WalletWrapper class of the library
const wallet = await CIP30WalletWrapper.init(walletInjectedFromBrowser);

// ...