Your First Spanning Web App

This tutorial will walk you through locally deploying your own version of the Spanning demo web application. This application can send transactions from a variety of networks over the Spanning Network to a SpanningERC20 token and a SpanningERC721 NFT.

This is intended to be the third of a series of tutorials that will teach you the basics of writing Spanning applications, from smart contracts to frontend deployments. If you haven't yet completed the previous tutorials and deployed a multichain ERC20 and/or a multichain NFT, you may want to go back to the previous tutorials.

Your first step will be to download the open-source Git repository for the demo application. The repository can also be cloned with the following terminal command:

git clone https://github.com/spanninglabs/app-showcase.git

Next, you will want to install the necessary packages used in the project via NPM by running the following command from the project's root directory:

npm install

For a full list of the project's dependencies please refer to the /package.json.

At this point, you should be able to launch the project locally on your computer by running

npm run dev
# or
yarn dev

The app should now be viewable at http://localhost:3000/.

By default, the open source demo application code is set up to communicate with the Spanning Labs deployed DBUX and JadeNFT smart contracts, but it is designed for you to plug in your smart contracts just as easily.

The contract address definition for the token portion of the application is stored in /constants/tokenContract.ts. For adding your own NFT project, the contract definition is stored in /constants/nftContract.ts.

The lines to update in the token constants are

export const tokenName = "DBUX"; // Replace with your token name
//...
export const tokenSettlementChain = networkIds.get("Avalanche Fuji")!; // Replace with the network you deployed on
export const tokenLegacyAddress = "0x847281739023017403c5940c082DCe51DB251fE9"; // Replace with your tokens local address

And in the NFT constants:

export const nftName = "Jade"; // Replace with your NFT name
//...
export const nftSettlementChain = networkIds.get("Avalanche Fuji")!; // Replace with the network you deployed on
export const nftLegacyAddress = "0x8b6203dd90DDb61251baE83B40ad4822d1BB582d"; // Replace with your NFTs local address

If you followed along exactly with the previous tutorials and deployed your contracts to the Avalanche Fuji network, you won't have to change the first lines above. If you decided to deploy your contracts on another network like Goerli, you can find those keys in /constants/chains.ts.

Congratulations! Your multichain tokens are now accessible by users on any of the three chains included in the demo app. We will leave adding more chains to the site as an exercise for you, but here is a good place to start.

If you are interested in building a custom web app or expanding the demo app with further customizations, there are a few places that you will want to dive in.

For helpful examples of how to use these utilities, check out:

/components/SpanningWebContext.tsx is where the bulk of the Web 3 logic lives. This is where we link to the Spanning Delegate contract on the user's current network and call the only smart contract function used in the demo application, makeRequest.

/components/nft/* and /components/token/* contain examples of how to call the mint and transfer functions of the smart contracts via a Spanning Delegate makeRequest function call.

Front-end web app utilities can be found at @spanning/utils NPM package:

npm install @spanning/utils

This includes:

import {
  getShortLocalAddress, // used to get a human readable version of a local 20 byte address
  getSpanningAddress, // used to get a Spanning Address from a chain domain ID and a local 20 byte address
  toAbi, // used to encode human readable function calls to byte data that can be passed to `makeRequest`
  parseSpanningAddress, // used to get the domain ID and local address from a Spanning Address
  isBosUp, // used to monitor the instantaneous health of the Spanning Network
} from "@spanning/utils";