Skip to main content

Quickstart: React npm

The React SDK adds a small abstraction over the Typescript SDK but this simplifies interacting with OPENFORMAT even further.

Installation

You can install the SDK with NPM or Yarn.

npm install @openformat/react ethers@^5

Setup

Constellations

A Constellation in our ecosystem is a metaphorical representation of a core or parent contract, acting as a central hub that governs and coordinates a collection of child contracts, referred to as "stars." Think of a Constellation as an application or organisational suite that houses various features or modules.

Features of a Constellation:

  • Fungible Token Integration: Each Constellation has its own fungible token associated with it. This token can represent value, ownership, or participation within the Constellation's ecosystem.
  • Modularity: Constellations are designed to host multiple stars. This allows for an expandable and customizable system where different functionalities can be added or removed as stars.
  • Interoperability: The design ensures that each Star within a Constellation can interact seamlessly with each other by using the Constellation Token. This token becomes a universal medium of exchange, collaboration, and communication among stars, enabling them to share information and functionality as defined by the Constellation.

Stars

Stars are child contracts connected to a Constellation. They represent individual features, applications, or components that operate under the governance of the parent Constellation. Each Star is like a unique tool or service within the broader application suite.

Features of a Star:

  • Independence: Though governed by the Constellation, each Star can have its own logic, data, and functionality. This enables developers to create diverse and specialized modules.
  • Interaction with Constellation Token: Stars can interact with the fungible token of the parent Constellation. This can be leveraged for various purposes, such as payment or access control within a Star.
  • Integration: Stars are fully integrated within the Constellation, allowing for seamless communication and collaboration with other stars in the same Constellation via the Constellation token.
  • Upgradeability: Depending on the design of the Constellation, stars can be added, removed, or updated without disrupting the entire system.

By organising your smart contracts into constellations and stars, you provide a hierarchical and modular system that promotes scalability, customisation, and efficient management. These concepts align well with both the technical architecture and the real-world analogies they represent, facilitating understanding and engagement with your ecosystem.

Creating Constellations and Stars

Join Our Dashboard Private Beta

Our Dashboard for creating and managing Constellations and Stars is now available in private beta. This innovative tool allows you to easily build and oversee your ecosystem without writing a single line of code. If you're interested in joining our beta program and exploring these powerful features, please email us at dev@openformat.tech.

Before interacting with the OPENFORMAT protocol, you first need to deploy a Constellation and Star via our Typescript SDK.

import { Chains, OpenFormatSDK } from "@openformat/sdk";

const sdk = new OpenFormatSDK({
network: Chains.polygonMumbai,
starId: "", // Pass an empty string here for Constellation and Star creation
signer: process.env.PRIVATE_KEY, // Your wallet's private key
});

const constellation = await sdk.factory.createConstellation({
name: "CONSTELLATION",
symbol: "CONST",
decimals: 18,
supply: 1000,
});

const star = await sdk.factory.createStar({
name: "STAR",
constellation: constellation.constellationAddress,
owner: "YOUR_WALLET_ADDRESS",
});

console.log({
constellation: constellation.constellationAddress,
star: star.starAddress,
});

Provider

Start by wrapping the OpenFormatProvider around your app.

The <OpenFormatProvider> is how you initialise the SDK. It should typically wrap your entire application so you can access the various hooks it provides.

As the provider takes care of initialising the SDK for you, you don't have to do much else but you need to pass it a config object to specify which network you want to interact with.

The config object can be passed through as a config prop to the provider.

import { OpenFormatProvider, Chains } from "@openformat/react";

function App() {
return (
<>
<OpenFormatProvider
config={{ networks: [Chains.polygonMumbai], appId: "INSERT_APP_ID" }}
>
{/* the rest of your app... */}
</OpenFormatProvider>
</>
);
}

Reading from the subgraph

There are numerous hooks that you can use to pull data from the subgraph. These return a Query from react-query, please refer to their documentation for further information.

You can also make raw requests against the subgraph.

import { useRawRequest } from "@openformat/react";
import { gql } from "graphql-request";

function MyComponent() {
const { data } = useRawRequest({
query: gql`
{
apps {
id
}
}
`,
});

return <>{data && <pre>{JSON.stringify(data, null, 2)}</pre>}</>;
}

Connecting to a wallet

Before you can deploy or perform any interactions with the contract you'll want to connect a wallet.

You can allow people to connect their wallets using the <ConnectButton /> component (which uses Wagmi and ConnectKit) and the useWallet hook to get the connection state and the address of the wallet if required.

import { ConnectButton, useWallet } from "@openformat/react";

function MyComponent() {
const { isConnected, address } = useWallet();

return (
<>
<ConnectButton />
</>
);
}

Additional configuration

Some additional configuration is required when using Webpack 5 and Create React App.

Webpack 5

You'll need to add some dev dependencies with the following command:

npm install --save-dev assert buffer crypto-browserify stream-http https-browserify os-browserify process stream-browserify util stream

Then add the following to your webpack.config.js file:

const webpack = require("webpack");

module.exports = {
resolve: {
alias: {
assert: "assert",
buffer: "buffer",
crypto: "crypto-browserify",
http: "stream-http",
https: "https-browserify",
os: "os-browserify/browser",
process: "process/browser",
stream: "stream-browserify",
util: "util",
},
},
experiments: {
asyncWebAssembly: true,
},
plugins: [
new webpack.ProvidePlugin({
process: "process/browser",
Buffer: ["buffer", "Buffer"],
}),
],
};

If you're running a Next.js or still get the Uncaught ReferenceError: Buffer is not defined in React error with react-scripts v5 / webpack 5 after the above config, add the following to your App.

import { Buffer } from "buffer";
window.Buffer = window.Buffer || require("buffer").Buffer;
Buffer.from("anything", "base64");

Usage with Create React App

CRACO provides an easy way to override webpack config which is obfuscated in Create React App built applications.

craco.config.js
const webpack = require("webpack");

module.exports = {
webpack: {
resolve: {
alias: {
assert: "assert",
buffer: "buffer",
crypto: "crypto-browserify",
http: "stream-http",
https: "https-browserify",
os: "os-browserify/browser",
process: "process/browser",
stream: "stream-browserify",
util: "util",
},
},
experiments: {
asyncWebAssembly: true,
},
plugins: [
new webpack.ProvidePlugin({
process: "process/browser",
Buffer: ["buffer", "Buffer"],
}),
],
},
};

Create a craco.config.js with the above content, and ensure its at the root of your project.

Update the existing calls to react-scripts in the scripts section of your `package.json`` file to use the craco CLI:

"scripts": {
"start": "craco start",
"build": "craco build",
"test": "craco test"
}