Prerequisites

Before you start coding you need the following prerequisites:

• An account on the Whal3s app
• An NFT (ERC-721) in one of your wallets + associated smart contract address.
  • If you don't have an NFT yet:
    • Head over to our Demo Page
    • Request Testnet tokens (Testnet tokens)
    • • Network: Mumbai*
        - Token: Matic tokens
      • Claim your free Whal3s NFT on Demo Page
• An NFT validation utility (Whal3s app -> NFT validation -> Add utility)
  - If you want to use the Whal3s NFT use the following configuration:
  - Network: Matic Mumbai (Polygon Testnet)
  - Smart Contract Address: 0x8f4d3Cf1998Fbf203F221c8986A0A11e14Fdb1a9
• A server :)

Clone the skeleton project from git, navigate into it and install JavaScript dependencies.

git clone https://github.com/Whal3s-xyz/nft-validation-utility-skeleton.git
cd nft-validation-utility-skeleton
npm install

If you are familiar with node scripts head ofter to Get started section

Getting started

Follow the steps and build your own utility dApp.

Install whal3s.js

npm i @whal3s/whal3s.js axios

Insert Utility ID

const id = '[YOUR-UTILITY-ID]';

Create Whal3s object

const whal3s = new Whal3s();

Create Validation Utility Instance

whal3s.createValidationUtility(id).then((newUtility) => {
    newUtility.addEventListener('stepChanged', (step) => {
        setStep(step.detail.step)
    })
    setUtility(newUtility)
    setStep(newUtility.step)
})

Let users connect their wallet

Call utility.connectWallet() when the Connect-Wallet-Button in 1_ConnectWallet.jsx is clicked.

<Button onClick={() => utility.connectWallet()}>Connect Wallet</Button>

Let users select one of their eligible NFTs

We already prepared an example visualization of all eligable NFTs.
You just need to set the token ID that should be used.

if(nft.valid)
    utility.tokenId = e.target.value

Reserve usage spot

In this example we make use of the reservation feature. This is optional but can be used to block this usage spot while asking for additional data like shipping address.
To do so, call reserveEngagement() when the Button in 3_SelectNft.jsx is clicked.

utility.reserveEngagement()

Claim utility

This is the point where the serverside workflow differentiates from the serverless workflow.
As already mentioned, we can add additional metadata to an engagement. But if you don't want to store it on the Whal3s server or if you want to process the data on your own, you can send the data to your server first, process it and claim the utility manually.
In this example (4_ClaimNft.jsx) we only ask for a text input you can exchange it for name and email for example.
To send the data to your server just create a claimUtility as shown below and call this function when the user hits the claim-button to send the data to your server.

const claimUtility = async () => {

        axios.post('http://localhost:3000/claim', {
            "utilityId": utility.id,
            "walletAddress": utility.wallet.address,
            "tokenId": utility.tokenId,
            "signature": utility.signature,
            "additionalData": additionalData
        }, {
            headers: {
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            },
        })
            .then(response => {
               utility.engagement = response.data.engagement
            })
            .catch(error => console.log(error));


    }


//...

 <Button className="mt-5" disabled={!additionalData} onClick={() => {
                claimUtility()
            }}>Claim Utility</Button>

Next, you proceed on your server.

1. Extract the data out of the request
2. Create an engagement on the Whal3s server
3. Proceed with your logic
4. Send back response

app.post('/claim', async (req, res) => {

    let {additionalData, signature, tokenId, utilityId, walletAddress} = req.body


    let response;
    try {

        // https://docs.whal3s.xyz/reference/cb8d2f91158914045a0e3d93102bef78
        response = await axios.post(`https://app.whal3s.xyz/api/v0/user/nft-validation-utilities/${utilityId}/engagements`, {
            token_id: tokenId,
            wallet_address: walletAddress,
            signature: signature
        })
    } catch (err) {
        res.status(400).json({success: false, data: err}).end()
    }

    //Engagement created, now execute you logic here and use `additionalData`
    //...
    console.log(additionalData)

    res.status(201).json({success: true, engagement: response.data}).end()

})

Alternatively check out the regarding recipe:

Finished

Check out your dApp by running it using npm run start.
You are now able to claim your own utility on http://localhost:3000
Finally head over to Whal3s App and check the freshly created engagement.

Tips and tricks

Account Center

You can customize the Wallet Configuration, like account center position, by passing a Configuration during Whal3s initialization.

const whal3s = new Whal3s({
    accountCenter: {
        desktop: {
            position: 'bottomRight', // position the account center to bottom right
        },
    }
});

Learn More

You can learn more in the Whal3s documentation.

Available Scripts

In the project directory, you can run:

npm start

Runs the app in the development mode.
Open http://localhost:3000 to view it in your browser.

The page will reload when you make changes.
You may also see any lint errors in the console

npm test

Launches the test runner in the interactive watch mode.
See the section about running tests for more information.

npm run build

Builds the app for production to the build folder.