> For the complete documentation index, see [llms.txt](https://docs.kuthulu.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kuthulu.xyz/contracts/badges.md).

# Badges

This API documentation provides details of the Badges smart contract that has been deployed on the Polygon network.

The Badges contract allows KUTHULU to manage a set of badges which can be issued to users based on their participation and achievements. Badges can be added, removed and verified based on certain conditions set by the application admins.

Badges can be awarded via calls from KUTHULU or self-verification if the badge has an `allowedAddress` set to a smart contract of any ERC-20 or ERC-721 token. When a user verifies their address, the smart contract will call out to the connected token smart contract to get the balance of the users ERC-20 or ERC-721 tokens and verify that they own at least the minimum required that is setup when creating the badge. The token smart contract can also deploy the optional `kuthuluVerifyBadgeType()` function should multiple badges be awarded from a single smart contract. See [Amulets](/contracts/amulets.md) smart contract for code examples.

### Table of Contents

1. [External Contract Functions](#external-contract-functions)
2. [Public Functions](#public-functions)
3. [kuthuluVerifyBadgeType Example](#kuthuluverifybadgetype-example)

***

## <mark style="color:purple;">External Contract Functions</mark>

These functions are designed to interact with the Badges smart contract from external sources.

### addBadgeToUser

This function allows admins or allowed addresses to add a badge to a user.

| Parameter   | Type    | Description                                     |
| ----------- | ------- | ----------------------------------------------- |
| userAddress | address | Wallet address of the user to add the badge to. |
| badgeID     | uint256 | The badge ID.                                   |

Returns: This function does not return a value.

Example usage with ethers.js:

```javascript
let userAddress = "0x1234567890abcdef1234567890abcdef1234567890";
let badgeID = 1;

let contract = new ethers.Contract(contractAddress, contractABI, provider);

let tx = await contract.addBadgeToUser(userAddress, badgeID);
await tx.wait();
```

### removeBadgeFromUser

This function allows admins or allowed addresses to remove a badge from a user.

| Parameter   | Type    | Description                                          |
| ----------- | ------- | ---------------------------------------------------- |
| userAddress | address | Wallet address of the user to remove the badge from. |
| badgeID     | uint256 | The badge ID.                                        |

Returns: This function does not return a value.

Example usage with ethers.js:

```javascript
let userAddress = "0x1234567890abcdef1234567890abcdef1234567890";
let badgeID = 1;

let contract = new ethers.Contract(contractAddress, contractABI, provider);

let tx = await contract.removeBadgeFromUser(userAddress, badgeID);
await tx.wait();
```

***

## <mark style="color:purple;">Public Functions</mark>

These functions can be called by any user and are designed to interact with the Badges smart contract internally.

### verifyBadge

This function allows a user to verify if they qualify for a badge.

| Parameter | Type    | Description                                               |
| --------- | ------- | --------------------------------------------------------- |
| badgeID   | uint256 | The badge ID to check to see if they qualify to be added. |

Returns: This function does not return a value.

Example usage with ethers.js:

```javascript
let badgeID = 1;

let contract = new ethers.Contract(contractAddress, contractABI, provider);

let tx = await contract.verifyBadge(badgeID);
await tx.wait();
```

### getUserBadges

This function returns a list of user's badge IDs.

| Parameter   | Type    | Description                                |
| ----------- | ------- | ------------------------------------------ |
| userAddress | address | The address of the user to get badges for. |

Returns: Array of badge IDs (uint256\[]).

Example usage with ethers.js:

```javascript
let userAddress = "0x1234567890abcdef1234567890abcdef1234567890";

let contract = new ethers.Contract(contractAddress, contractABI, provider);

let badges = await contract.getUserBadges(userAddress);
console.log(badges);
```

### getBadgeDetails

This function retrieves the details of a badge.

| Parameter | Type    | Description                                 |
| --------- | ------- | ------------------------------------------- |
| badgeID   | uint256 | The ID of the badge to get the details for. |

Returns: Array of badge details (string\[]).

Example usage with ethers.js:

```javascript
let badgeID = 1;

let contract = new ethers.Contract(contractAddress, contractABI, provider);

let badgeDetails = await contract.getBadgeDetails(badgeID);
console.log(badgeDetails);
```

### getBadges

This function retrieves a list of all the available badge IDs.

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| None      |      |             |

Returns: Array of badge IDs (uint256\[]).

Example usage with ethers.js:

```javascript
let contract = new ethers.Contract(contractAddress, contractABI, provider);

let badgeIDs = await contract.getBadges();
console.log(badgeIDs);
```

***

## <mark style="color:purple;">kuthuluVerifyBadgeType Example</mark>

This code example is pulled from the [Amulets](/contracts/amulets.md) contract. This will verify that an address owns a specific badge type that is associated with their tokens.

```solidity
function kuthuluVerifyBadgeType(uint256 badgeTypeID) public view returns (bool) {
    for (uint i=0; i < balanceOf(tx.origin); i++) {
        if (getAmuletType(tokenOfOwnerByIndex(tx.origin, i))[1] == badgeTypeID){
            return true;
        }
    }
    return false;
}
```