# 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;
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kuthulu.xyz/contracts/badges.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.