cardano-pab-client

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 | undefined {
  // NOTE: all the modules of this library MUST be imported dynamically like this
  const {
    CIP30WalletWrapper,
    Balancer,
    getProtocolParamsFromBlockfrost,
    failed,
  } = 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);

  // connect to a existing contract
  const pabUrl = "http://localhost:9080";
  const endpoints = await ContractEndpoints.connect(pabUrl, { tag: "Connect", contents: [] });
  // try to get unbalanced transaction from PAB
  const pabResponse = endpoints.doOperation({ tag: "operation", contents: "some needed parameter" });

  if (failed(pabResponse)) {
    alert(
      `Didn't get the unbalanced transaction from the PAB. Error: ${pabResponse.error}`
    );
    return;
  }
  // 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 balancerResponse = await balancer.fullBalanceTx(
    etx,
    walletInfo,
    // configuration for the balanceTx and rebalanceTx methods which are interally
    // used by this method
    { feeUpperBound: 1000000, mergeSignerOutputs: false },
    // the tx budget service api that will calculate the execution units of the redeemers of the tx
    txBudgetApi,
  );
  if (failed(balancerResponse)) {
    alert(`Balancer failed with error: ${balancerResponse.error}`);
    return;
  }
  const fullyBalancedTx = balancerResponse.value;
  // 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 walletResponse = await wallet.signAndSubmit(fullyBalancedTx);
  if (failed(walletResponse)) {
    alert(`Start failed when trying to submit it. Error: ${walletResponse.error}`);
    return;
  }
  const txHash = response.value;
  alert(`Start suceeded. Tx hash: ${txHash}`);
  // 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);

// ...

Codebase docs as website

They are a set of HTMLs, so to run them into a website you could go to the docs/ folder and run the following commands

docker build --tag docs-site:latest .
docker run -it --name docs -p 5000:80 docs-site:latest

That will run the docs at http://localhost:5000.