SongBirdz Back-End

This project contains the back-end for the SongBirdz NFT collection. It includes the solidity contract, test code for that contract, a NodeJS server to serve images, metadata, and merkle proof, as well as the scripts used to generate and deploy the collection.

You can find the front-end application here.

NOTE: The species names and merkle trees are hidden for now until each bird in the NFT collection has been successfully identified. This means the ./private folder is not included in this repo, so you will need to generate it yourself if forking this repo!

Solidity (ERC721 Contract)

The ERC721 contract for the SongBirdz NFT collection is in the ./contracts/SongBirdz.sol file.

Test code for the contract is in the ./test/SongBirdz.js file.

Hardhat configuration for the contract is in the ./hardhat.config.js file.

There are 2 scripts related to the ERC721 contract:

1. ./scripts/solidity/deployContract.js can be used to deploy the ERC721 contract to the local, test, and production environments.

2. ./scripts/solidity/populateCollection.js can be used to populate the NFT collection once the ERC721 contract has been deployed to the local, test, and production environments.

There are npm commands related to the ERC721 contract:

1. npm run compile-contracts can be used to compile the ERC721 contract.

2. npm run test-contracts can be used to test the ERC721 contract.

NodeJS (Server)

The ./server folder contains all logic related to the back-end server which is used to serve images, metadata, and merkle proofs for the NFT collection.

Since each bird starts out unidentified, this back-end server is used to obfuscate the species name and image file associated with each bird until they've all been successfully identified. At that point in time, the back-end server will be shut-down and all species names, image data, and merkle trees will be moved to the front-end... and then eventually stored in a decentralized provider such as nft.storage.

The API endpoints for the server are:

• GET /birds/image/:id -> Returns the image file associated with the given bird ID.

• GET /birds/metadata/:id -> Returns the metadata associated with the given bird ID. If the bird is not yet identified, then the species name and description will be hidden. See here for the expected JSON structure of the response.

• GET /birds/merkle-proof/:id -> Returns the merkle tree proof associated with the given bird ID and species name guess.

There are 4 node scripts related to the server:

1. ./scripts/node/generateImages.js can be used to generate the image files using Dalle-3 for a collection of 1000 birds.

2. ./scripts/node/generateSpeciesAndAudio.js can be used to generate the species names, answer choices, and audio files for a collection of 1000 birds.

3. ./scripts/node/generateMerkleTree.js can be used to generate the merkle tree for a collection of 1000 birds.

4. ./scripts/node/backfillPoints.js can be used to backfill any missing points based on transfer and sale events on OpenSea.

• npx api install "@opensea/v2.0#tyjem2mlwzlfgof"

There are 2 bash scripts related to the server:

1. ./scripts/bash/trimAudioFiles can be used to clean up the final audio files for a collection of 1000 birds.

2. ./scripts/bash/processImageFilesXXX can be used to clean up the final image files for a collection of 1000 birds.

Setup

1. If you don’t have Node.js installed, install it from here (Node.js version >= 16.18.0 required)

2. Clone this repository

3. Navigate into the project directory

   $ cd songbirdz-collection-backend

4. Install the requirements

   $ npm install

5. Make a copy of the example environment variables file

   On Linux systems:

   $ cp .env.example .env.development

   On Windows:

   $ copy .env.example .env.development

6. Add your API keys, contract address, and wallet data to the newly created .env.development file

7. Start the blockchain on your local machine at http://localhost:8545

   $ npm run start-blockchain

8. Deploy the contract on your local machine at 0x5fbdb2315678afecb367f032d93f642f64180aa3

   $ npm run deploy-local

9. Populate the NFT collection in the contract on your local machine

   $ npm run populate-local

10. Start the server on your local machine at http://localhost:3080

    $ npm run start-server

You should now be able to succesfully run the front-end application!

Deploying to Testnet

• Populate the .env.staging file.
• Ensure your Base Sepolia account has sufficient ETH to cover gas costs.
• Deploy contract on Base Sepolia testnet via npm run deploy-testnet.
• Navigate to https://sepolia.basescan.org and double check the contract on basescan.
• Verify contract on Base Sepolia testnet via npm run verify-testnet.
• Use the publicSetBaseURI method on basescan to update the _baseURI variable to "https://songbirdz.cc/birds/metadata/".
• Use the publicGetbaseURI method to verify the _baseURI variable on basescan.
• Use the owner method to verify the owner address on basescan.
• Upload Picasso collection on Base Sepolia testnet via npm run populate-testnet.
• Use the publicGetNumBirds and collections methods to verify Picasso collection on basescan.
• Deploy the back-end server to gcloud/aws/azure/etc.
• Deploy the front-end application to gcloud/aws/azure/etc.
• Navigate to https://songbirdz.cc and verify that the application is working!
• Successfully mint a bird NFT with Metamask - Chrome
• Incorrectly mint a bird NFT with Metamask - Chrome
• Successfully mint a bird NFT with Coinbase Wallet - Chrome
• Incorrectly mint a bird NFT with Coinbase Wallet - Chrome
• Successfully mint a bird NFT with Metamask - Mobile
• Incorrectly mint a bird NFT with Metamask - Mobile
• Successfully mint a bird NFT with Coinbase Wallet - Mobile
• Incorrectly mint a bird NFT with Coinbase Wallet - Mobile
• Verify the collection (i.e. metadata) on OpenSea testnet.

Deploying to Production

• Populate the .env.production file.
• Ensure your Base account has sufficient ETH to cover gas costs.
• Deploy contract on Base mainnet via npm run deploy-mainnet.
• Navigate to https://basescan.org and double check the contract on basescan.
• Verify contract on Base mainnet via npm run verify-mainnet.
• Use the publicSetBaseURI method on basescan to update the _baseURI variable to "https://songbirdz.cc/birds/metadata/".
• Use the publicGetbaseURI method to verify the _baseURI variable on basescan.
• Use the owner method to verify the owner address on basescan.
• Upload the Picasso collection on Base mainnet via npm run populate-mainnet.
• Use the publicGetNumBirds and collections methods to verify Picasso collection on basescan.
• Update front-end application About page to include link to Discord.
• Update front-end application About page to include link to Contract on Base mainnet.
• Update front-end application About page to include links to Github.
• Deploy the back-end server to gcloud/aws/azure/etc.
• Deploy the front-end application to gcloud/aws/azure/etc.
• Navigate to https://songbirdz.cc and verify that the application is working!
• Successfully mint a bird NFT with Metamask - Chrome
• Incorrectly mint a bird NFT with Metamask - Chrome
• Successfully mint a bird NFT with Coinbase Wallet - Chrome
• Incorrectly mint a bird NFT with Coinbase Wallet - Chrome
• Successfully mint a bird NFT with Metamask - Mobile
• Incorrectly mint a bird NFT with Metamask - Mobile
• Successfully mint a bird NFT with Coinbase Wallet - Mobile
• Incorrectly mint a bird NFT with Coinbase Wallet - Mobile
• Verify the collection (i.e. metadata) on OpenSea mainnet.

Roadmap for Production

• Upload the first 1,000 birds in the "Picasso Genesis" flock.
• Successfully mint all 1,000 birds (0-999) in the "Picasso Genesis" flock.
• Make public the (merkle-tree, images, species, audio) files for the "Picasso Genesis" flock.
• Successfully mint all 1,000 birds (1000-1999) in the "Deep Blue" flock.
• Make public the (merkle-tree, images, species, audio) files for the "Deep Blue" flock.
• Successfully mint all 1,000 birds (2000-2999) in the "Small & Mighty" flock.
• Make public the (merkle-tree, images, species, audio) files for the "Small & Mighty" flock.
• Successfully mint all 1,000 birds (3000-3999) in the "Night & Day" flock.
• Make public the (merkle-tree, images, species, audio) files for the "Night & Day" flock.
• Successfully mint all 1,000 birds (4000-4999) in the "Fire & Ice" flock.
• Make public the (merkle-tree, images, species, audio) files for the "Fire & Ice" flock.
• Successfully mint all 1,000 birds (5000-5999) in the "Predator & Prey" flock.
• Make public the (merkle-tree, images, species, audio) files for the "Predator & Prey" flock.
• Repeat for TBD collection with birds 6000-6999.
• Repeat for TBD collection with birds 7000-7999.
• Repeat for TBD collection with birds 8000-8999.
• Repeat for final TBD collection with birds 9000-9999.
• Upload all (metadata, merkle-trees, images, species, audio) files for the entire 10,000 NFT collection to a decentralized storage provider (i.e. ipfs via nft.storage).
• Use the publicSetBaseURI method on basescan to update the _baseURI variable to the new metadata URL in ipfs. TBD: Freeze it permanently!
• Deploy a 2nd Solidity Contract to store Life List and Points data onchain.
• TBD: Upload the web application to ipfs.
• TBD: Shut down the back-end server.
• Roadmap is now complete!