GENERA Project: Web3 (Blockchain) Backend Logic
A smart contract is a self-executing contract with terms of the agreement directly written into code.
It automatically performs transactions when predefined conditions are met, without the need for intermediaries.
It is typically built on blockchain technology, ensuring transparency, security, and efficiency.
In simple terms, it's a piece of immutable code that lives on the blockchain that provides functionality.
Similar to a venting machine (Smart Contract) located in a park (Blockchain).
Currently, our platform utilizes 2 Smart Contracts.
- Address: 0x300302fEc3D905eb66Cb7743C636F8741B72dB3a
- Network: GENERA (Chain ID: 20231)
- ABI: click here
This Contract is tasked with the purpose of issuing and removing (burning) MGS (MyGreenScore) Tokens.
These tokens are used as way to motivate users to explore and utilize the platform's web services.
Users can accumulate these tokens by performing specific actions or tasks.
Contract's API
-
Write (State alterating) functions:
function addPoints(string _serviceName, string _eventName) public returns (bool)
function createUser(string _name) public returns (bool)
function createService(string _serviceName) public returns (bool)
function createEvent(string _eventName, string _serviceName, uint64 _multiplier) public returns (bool)
function setBaseReward(uint _initValue) public returns (bool)
function redeemer(uint _productPrice, string _serviceName) public returns (bool)
-
Read/View (State non-alterating) functions:
Getters for: baseReward, contractAddress, numServices, numUsers, services, users
function viewYourPoints(string _serviceName, string _eventName) public returns (bool)
function viewEvent(string _serviceName, string _eventName) public view returns (ServiceEvent)
How to use the Contract
Step #1:
You have to insert/import a JavaScript Library in your Frontend that can interact with Blockchain Networks.
The most popular choices are:
- ethers.js
- web3.js
However, nowdays more abstract libraries exist that make this process event easier (ex. wagmi react hooks)
Once, this step is completed you should have a Contract instance that the library constructed based on the
address and ABI you provided as arguments.
Step #2:
Create a Service Object and its Events in the Smart Contract.
For example, a Service could be: "MOOC" and one of its Events could be: "videoWathced"
This step is a bit tricky, because it is not similar to how frontend development works.
This is because the Smart Contract's storage is not limited to only memory
(meaning that it will be erased when the user closes the browser tab or window).
Most of the time, we need to permanetly store information.
The easiest way to create these Service and Event objects is through the Remix IDE
This video demonstrates how to perform the mentioned operations: emptyVideoLink
Step #3:
Finally, the only thing left to do is to call the contract's functions whenever you need them in your code, for example:
async function sumbitComment() {
// Your previous code...
// Supposing your Contract Instance name is "rewardContract"
// This example uses ethers.js v5.7.2 syntax, but web3.js is very similar
const { wasSuccessful } = await rewardContract.addPoints("MOOC", "videoWathced");
if(!wasSuccessful) throw new Error("Contract Interaction Failed!")
// The rest of your code...
}- Address: 0xdceAE859c3590A5E91688FFb166ec5708f1c2d99
- Network: GENERA (Chain ID: 20231)
- ABI: click here
This Contract creates and transfers NFT representations of the Game's Cards.
It's using the OpenZeppelin's ERC-1155 Token Standard which is
one of the most battletested and trusted Solidty Open-source Libraries.
Contract's API
-
Write (State alterating) functions:
function createPlayer(string calldata _name, uint _server_id) public returns (void)
function createCard(uint _card_id, uint _template_id, bool _inMP) public returns (void)
function transferCard(address _seller, address _buyer, uint _cardId) public returns (void)
-
Read/View (State non-alterating) functions:
Getters for: cardsNFT, cardsServer, contractAddress, numCards, numPlayers, owner, players
function getCardOwner(uint _card_id) public view returns (address)
// Polymorphism #1: uses the msg.sender address to look up the tokens function getOwnedTokens() public view returns (uint256[] memory)
// Polymorphism #2: uses the provided (_owner) address to look up the tokens function getOwnedTokens(address _owner) public view returns (uint256[] memory)
function getOwnedTokens() public view returns (uint256[] memory)
How to use the Contract
Step #1:
You have to insert/import a JavaScript Library in your Frontend that can interact with Blockchain Networks.
The most popular choices are:
- ethers.js
- web3.js
However, nowdays more abstract libraries exist that make this process event easier (ex. wagmi react hooks)
Once, this step is completed you should have a Contract instance that the library constructed based on the
address and ABI you provided as arguments.
Step #2:
Call the createPlayer(playerName, playerId) contract function in the same place where your Player creation happens.
async function createNewPlayer(playerData) {
axios.post('https://your-web-server/players', playerData)
.then((response) => {
if (response.ok === true) {
try {
// ... Your code ...
// The Player's ID from the server is required so that
// the Contract and the Server stay in sync
await gameContract.createPlayer(playerData.name, response.newPlayer.id)
} catch {
// Important! Here you must find way to a handle the edge case where
// the server-side player is created successfully, but the one in the
// Smart Contract fails! And vice versa
console.error("Problem occured in the Blockchain when creating new player");
}
}
})
.catch((error) => {
console.error(error);
});
}Step #3:
Call the createCard(card_id, template_id, inMP) contract method above or below the point where you create the new Card object.
async function createNewCard(cardData) {
axios.post('https://your-web-server/cards', cardData)
.then((response) => {
if (response.ok === true) {
try {
// ... Your code ...
// The Card's ID from the server is required so that
// the Contract and the Server stay in sync
await gameContract.createCard(cardData.id, cardData.templateId, false)
} catch {
// Important! Here you must find way to a handle the edge case where
// the server-side player is created successfully, but the one in the
// Smart Contract fails! And vice versa
console.error("Problem occured in the Blockchain when creating new Card");
}
}
})
.catch((error) => {
console.error(error);
});
}Step #4:
Finally, call the transferCard(_seller, _buyer, _cardId) contract method above or below the point where you handle the Card's ownership swap.
async function changeCardOwner(_buyer, _seller, _cardId) {
axios.put('https://your-web-server/cards', {buyer: _buyer, seller: _seller, cardId: _cardId})
.then((response) => {
if (response.ok === true) {
try {
// ... Your code ...
// The Card's ID from the server is required so that
// the Contract and the Server stay in sync
await gameContract.transferCard(_buyer, _seller, _cardId)
} catch {
// Important! Here you must find way to a handle the edge case where
// the server-side player is created successfully, but the one in the
// Smart Contract fails! And vice versa
console.error("Problem occured in the Blockchain when transfering the Card");
}
}
})
.catch((error) => {
console.error(error);
});
}