@plutoxyz/react-frame

A React library that provides components and hooks for Pluto frame UI. We recommend using the Frame component for most use cases. If you need more control, you can use the hooks in combination with the Frame component.

Installation

npm install @plutoxyz/react-frame

Usage

import { Frame } from "@plutoxyz/react-frame";

const handleProof = (proof) => {
  console.log(proof.data);
  console.log(proof.signature);
};

const handleError = (error) => {
  console.log(error.code);
  console.log(error.display_message);
  console.log(error.message);
};

function App() {
  return (
    <Frame
      script={`myScript`}
      onProof={handleProof}
      onError={handleError}
      brand={{
        name: "My Company",
        logo: "https://my-company.com/logo.png",
      }}
    />
  );
}

Frame

The Frame component is a wrapper around the Pluto frame. It provides everything you need out of the box for with Pluto in an easy-to-use package.

Note: Don’t mount the Frame component until you are ready to start the Pluto Frame flow. We recommend putting it behind a user-initiated action, like a button click.

Props:

script: The script to be executed in the frame.
onProof: A function that is called when a proof is generated. Parameter is a payload with the following properties:
- data: Record<string,string>
- signature: string
onError: A function that is called when an error occurs. Parameter is a payload with the following properties:
- code: string
- display_message: string
- message: string
brand: The brand to use for the frame. Parameter is a payload with the following properties:
- name: string
- logo: string

Advanced Usage

If your app is larger and needs to split the logic across multiple rendering trees, you can inject the Pluto Provider manually at the top level of your react app, and access the available hooks throughout your app. In addition, you can still use the Frame component safely even if you inject your own Provider.

PlutoProvider

The Frame component comes with it's own provider. If you are not using the Frame component, and instead using the hooks, you will need to use the PlutoProvider component.The PlutoProvider component provides a context for managing the state of a Pluto frame. Wrap your application or a part of it with this provider:

import { PlutoProvider } from "@plutoxyz/react-frame";

function App() {
  return <PlutoProvider>{/* Your components here */}</PlutoProvider>;
}

Using the Hooks

The library provides several hooks to access different aspects of the Pluto frame state:

import {
  usePlutoFrame,
  useProof,
  useError,
  useLogs,
} from "@plutoxyz/react-frame";

function MyComponent() {
  // Main hook that provides core functionality
  const { isReady, isConnected, connect, resetConnection } = usePlutoFrame();

  // Specialized hooks for specific use cases
  const proof = useProof();
  const error = useError();
  const logs = useLogs();

  const handleConnect = async () => {
    if (isReady && !isConnected) {
      try {
        // Pass your verification script here
        await connect(`
          const accessToken = await oauth({
            title: 'Connect with OAuth Demo',
            description: 'Connect with Demo App',
            clientId: '123',
          });

          // Your verification logic here

          await prove('my_data', { value: 42 });
        `);
      } catch (err) {
        console.error("Failed to connect:", err);
      }
    }
  };

  return (
    <div>
      <p>Pluto is {isReady ? "ready" : "initializing"}</p>
      <p>Connection status: {isConnected ? "Connected" : "Not connected"}</p>

      <button onClick={handleConnect} disabled={!isReady || isConnected}>
        Connect
      </button>

      <button onClick={resetConnection} disabled={!isConnected}>
        Reset Connection
      </button>

      {error && (
        <div className="error">
          <h3>Error:</h3>
          <p>{error.display_message}</p>
        </div>
      )}

      {proof && (
        <div className="proof">
          <h3>Proof Generated:</h3>
          <pre>{JSON.stringify(proof, null, 2)}</pre>
        </div>
      )}

      {logs.length > 0 && (
        <div className="logs">
          <h3>Logs:</h3>
          <ul>
            {logs.map((log, i) => (
              <li key={i}>{log}</li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}

API

Frame

A React component that provides the Pluto Frame

Props:

script: The script to be executed in the frame.
onProof: A function that is called when a proof is generated.
onError: A function that is called when an error occurs.

PlutoProvider

A React component that provides the Pluto frame context.

Props:

children: React nodes to be rendered within the provider.

usePlutoFrame

The main hook that provides access to the Pluto frame functionality.

Returns:

isReady: Boolean indicating whether Pluto has been initialized.
isConnected: Boolean indicating whether the frame is connected.
connect: Function to connect to the frame with a script.
resetConnection: Function to reset the connection to the frame.

useProof

Hook to access the proof payload.

Returns:

ProofPayload | null: The current proof payload or null if no proof has been generated.

useError

Hook to access the current error.

Returns:

ErrorPayload | null: The current error payload or null if no error has occurred.

useLogs

Hook to access the logs from the verification process.

Returns:

string[]: Array of log messages from the verification script.

usePluto

Hook that returns whether Pluto is ready. For most use cases, usePlutoFrame provides more functionality.

Returns:

boolean: Whether Pluto is ready.

License

MIT