# SA Technical documentation

Super Accounts is a special [Safe Smart Account](https://safe.global/) equipped with several built-in features. Specifically, it includes a Safe Module to handle and manage all aspects related to Social Accounts and owner management and ERC4337 Module to handle gasless transaction. Additionally, we have a Safe Guard to ensure that every user has only one SA.

## 1. Badges
Badges are the means by which Super Accounts (SA) reward users for performing certain actions, both on-chain and off-chain. They serve as a recognition system, acknowledging user achievements, contributions, and participation within the ecosystem. For example, a user might receive a badge for donating a specific amount on platforms like Giveth or for owning an External Owned Account [(EOA)](https://ethereum.stackexchange.com/questions/5828/what-is-an-eoa-account).
### 1.1 How to Obtain Badges

To receive badges, users interact with a centralized system that calculates and allocates badges to each Super Account (SA) based on specific data sources. The process involves several key steps:

Data Collection: The system gathers relevant information from predefined data sources to assess the user's eligibility for certain badges and their corresponding levels.

Attestation and Injection: Levels for each eligible badge are [attested](https://attest.org/) and injected into the SA Module associated with the user's Super Account.

On-Chain Updates: The Safe Module updates the user's points and levels on-chain, ensuring that the badge information is securely recorded on the blockchain.

NFT Minting: For each badge claimed, a Non-Fungible Token (NFT) containing all relevant details is minted. This NFT represents the badge and is linked to the user's account.
#### Steps to Get Badges:

- **Eligibility Check**: Ensure that your account meets the criteria specified by the data sources for badge allocation.

- **Badge Claiming**: Once eligible, initiate the badge claiming process through the provided interface or API.

- **Attestation Submission**: Submit the required attestations to the SA Module to validate your badge levels.

- **Verification**: The system verifies the attestations and updates your badge levels accordingly.

- **Minting**: The NFT representing your badge is minted and associated with your Super Account.
### 1.2 How to retrieve badges data
Users and developers may need to access badges information, including general badge details and specific `tier` information. The `SuperChainBadges` smart contract provides functions to retrieve this information:

#### 1.2.1 Tokens ID standard

In the `SuperChainBadges` contract, token IDs are generated by combining the `badgeId` and the `tier` level into a single `uint256` number. This is achieved by shifting the `badgeId` and using bitwise operations to merge it with the tier. This method conforms to a pseudo-fungible ERC1155 standard, allowing for efficient handling of badge tiers within the token IDs.

The token ID encoding is defined as:

uint256 constant LEVEL_MASK = type(uint128).max;
uint256 constant LEVEL_SHIFT = 128;

function encodeTokenId(uint256 _badgeId, uint256 _tier) public pure returns (uint256) {
    return (_badgeId << LEVEL_SHIFT) | (_tier & LEVEL_MASK);
}

**How It Works:**
- Badge ID Positioning: The `badgeId` is shifted left by 128 bits (LEVEL_SHIFT), positioning it in the higher 128 bits of the `uint256`.
- Tier Masking: The `tier` is masked with LEVEL_MASK to ensure it occupies only the lower 128 bits.
- Combining Values: The two values are combined using the bitwise OR (|) operator to form a unique token ID.

**Example:**
If we have a `badgeId` 3 and a `tier` 1, the token Id will be:
$0\text{x}0000000000000000000000000000000300000000000000000000000000000001$ which is `3 << 128 | 1`, resulting in $1020847100762815390390123822295304634369$.

To get the URI for this token, you should call the uri function like this:

uint256 tokenId = 1020847100762815390390123822295304634369;
string memory tokenURI = uri(tokenId);

#### 1.2.2 Retrieve General Badge Information
To simplify the process of retrieving badge information, the `SuperChainBadges` contract provides a function to get the general URI associated with a badge. This URI contains the general badge data without the `tier` information.

To get the general URI, you should call the `getGeneralBadgeURI` function with the `badgeId` as the argument.

Example:
To get the general URI for the badgeId 3 you should call the function like this:

uint256 badgeId = 3;
string memory generalURI = getGeneralBadgeURI(badgeId);

#### 1.2.3 Retrieve Badge information for a specific user
To retrieve badge information for a specific user, including the badge ID, `tier`, and associated token ID, the `SuperChainBadges` contract provides a function to get the badge details. This function takes the user's Super Account address and the `badgeId` as arguments and returns the GeneralURI and current TierURI.
**Example:**
To get the badge information for a specific user you should call the function like this:

address user;
uint256 badgeId;

(string memory generalURI, string memory tierURI) = getBadgeInfo(user, badgeId);

#### 1.2.4 Get highest tier for a badge
To retrieve the highest tier available for a specific badge, the `SuperChainBadges` contract provides a function to get the maximum tier level. This function takes the `badgeId` as an argument and returns the maximum tier level.

**Example:**
To get the highest tier for a badge you should call the function like this:

uint256 badgeId;
uint256 highestTier = getHighestTier(badgeId);

## 2. Super Account Profile

Super accounts have a lot of social stuff and customizations for providing a richer and more personalized user experience. This includes features like custom domains, avatars, badges, and more that allow users to express their unique identities on the platform.

### 2.1 SuperChain domain

In this MVP, the SuperChain domain is essentially a unique username or handle stored on the SuperChainModule. The domain follows the format name**.Superchain**, where the name part is a unique identifier chosen by the user. This domain can be used for various on-chain and off-chain interactions, serving as the user's public-facing identity within the SuperChain ecosystem.

Key features of the SuperChain domain:

- **Uniqueness**: Each domain is unique, ensuring no two users can have the same domain.
- **On-chain storage**: The domain is recorded and managed on-chain through the SuperChainModule, providing immutability and verifiability.
- **Integration**: In the future iterations, the domain can be used across different SuperChain features, such as transactions, profile management, or social interactions.
- **Customization**: In future iterations, users may be able to customize their domain further, adding branding elements, special characters, or linking it with other digital assets.

### 2.2 Super Account avatar

In this MVP, the Super Account avatar is a personalized image based on the popular [Nouns](https://nouns.wtf/) collection. Each avatar is generated by combining different parts (head, body, accessories, etc.), and the smart contract only stores the indexes of these components, which are then used to reconstruct the avatar off-chain or on-chain, depending on the use case.

### 2.2.1 How to Get the Super Account Avatar for a Specific User

To retrieve the Super Account avatar for a specific user, you can access the smart contract and query the stored noun metadata, which includes the indexes of the noun parts such as the head, body, and accessories. This data is stored in the `SuperChainModule` contract under the `superChainAccount` mapping, where each user's `NounMetadata` can be retrieved and used to generate the corresponding avatar.

Here's an example of how to query the Super Account avatar data:

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.20;

struct NounMetadata {
    uint48 background;
    uint48 body;
    uint48 accessory;
    uint48 head;
    uint48 glasses;
}

contract SuperChainAvatarRetriever {
    ISuperChainModule private superChainModule;

    constructor(address _superChainModule) {
        superChainModule = ISuperChainModule(_superChainModule);
    }

    function getSuperAccountAvatar(address user) external view returns (NounMetadata memory) {
        // Retrieve the SuperChain smart account for the user
        Account memory account = superChainModule.getUserSuperChainAccount(user);
        return account.noun;
    }
}

This function allows you to retrieve the `NounMetadata` for a given user, which includes all the necessary indexes to reconstruct the avatar. Each index corresponds to a specific visual part of the avatar, such as head, body, or accessory, and can be used to render the image through Nouns SDK.

For example, to render the image in a react component:

import React from 'react'
import { getNounData, ImageData } from '@nouns/assets'
import { buildSVG } from '@nouns/sdk'
function NounsAvatar({ seed }) {
  const { parts, background } = getNounData(seed)
  const { palette } = ImageData
  const svgBinary = buildSVG(parts, palette, background)
  const svgBase64 = btoa(svgBinary)
  return (
    <img
      src={`data:image/svg+xml;base64,${svgBase64}`}
      alt="nouns"
    />
  )
}

export default NounsAvatar

Here’s the continuation of the section:

---

### 2.3 Super Account Points and Level

In this MVP, Super Accounts have a point-based system that helps determine the user's level. Points are accumulated through various interactions within the SuperChain ecosystem, such as completing tasks, contributing to the platform, or other predefined actions. These points are tracked and managed in the `SuperChainModule` contract, which stores the points for each user's account.

#### Points System

- **Point Accumulation**: Each Super Account collects points over time as users engage with the platform.
- **Point Management**: The points are incremented using the `incrementSuperChainPoints` function in the contract. This function ensures that points can only be increased by the resolver, which acts as a trusted entity or contract handling point rewards.
- **Simulated Increments**: The contract also provides a simulation function `simulateIncrementSuperChainPoints` to calculate if a user would level up without actually updating the on-chain state.

#### Levels and Rewards

The point system is tied directly to the leveling mechanism. As users gain more points, they level up. Levels unlock new features or rewards within the ecosystem, providing incentives for users to remain engaged.

- **Leveling Up**: When a user's points reach a threshold specified in the contract (`_tierTreshold`), their level increases. The contract automatically updates the user’s level based on their points and predefined thresholds using the `incrementSuperChainPoints` function.
- **Tier Thresholds**: These thresholds are stored in the contract and determine how many points are needed to reach each level. The contract owner can update or add new thresholds, adjusting the difficulty or rewards system dynamically.
- **Rewards for Levels**: As users level up, they unlock exclusive rewards. These rewards could be anything from badges, access to special features, or even on-chain benefits. The rewards for each level can be customized and tied to the logic within the resolver or other external modules.

#### Example Contract Interaction

Here’s a simplified example of how the point and level system works:

function incrementSuperChainPoints(
    uint256 _points,
    address recipient
) public returns (bool levelUp) {
    Account storage _account = superChainAccount[recipient];
    
    // Ensure only the resolver can increment points
    require(msg.sender == _resolver, "Only the resolver can increment points");
    
    // Add points to the user's account
    _account.points += _points;
    
    // Check if the user qualifies for a level up based on point thresholds
    for (uint16 i = uint16(_tierTreshold.length); i > 0; i--) {
        uint16 index = i - 1;
        if (_tierTreshold[index] <= _account.points) {
            if (_account.level == index + 1) {
                break;  // No level up if already at this level
            }
            _account.level = index + 1;  // Update level
            levelUp = true;
            break;
        }
    }
    
    // Emit event for points increment and level up
    emit PointsIncremented(recipient, _points, levelUp);
    
    return levelUp;
}

### Future Expansions
- **Custom Rewards**: As the platform evolves, rewards can include NFTs, tokens, or other custom assets that users can receive upon leveling up.
- **Level-Based Access**: Levels could grant users access to premium features or governance rights within the SuperChain ecosystem.

This system incentivizes users to remain active, engage with the platform, and strive for higher levels, unlocking valuable rewards along the way.

### 2.4 Perks

As users level up their Super Accounts, they unlock **perks** that enhance their experience in the SuperChain ecosystem. These perks serve as rewards for engagement and activity, and they could take various forms, providing both social recognition and functional benefits.

#### Possible Perks:
- **Exclusive Badges**: Higher-level users might unlock special badges that reflect their status, accomplishments, or contributions to the platform, displayed prominently on their profiles.
- **Access to Premium Features**: Advanced users could gain early or exclusive access to premium features, new tools, or beta releases within the platform.
- **Discounts and Offers**: Users may receive discounts on platform-related services, NFTs, or other products from partnerships with external brands.
- **Voting and Governance Rights**: As users reach higher levels, they could earn governance rights, giving them a say in decisions affecting the platform or community.
- **Avatar and Profile Customizations**: Leveling up might unlock additional customization options for user profiles or avatars, allowing for unique appearances or personalized content.
- **Special Invitations**: Top-level users might receive invitations to exclusive events, virtual or in-person, such as webinars, AMA sessions, or community gatherings.

These perks create a dynamic incentive for users to stay engaged and active on the platform, offering real value alongside recognition for their participation.

## 3 Account abstraction

By leveraging account abstraction through the [ERC4337](https://www.erc4337.io/) module in conjunction with [Pimlico](https://www.pimlico.io/), we are able to sponsor user operations within the SA Wallet DApp. This integration allows users to interact with the decentralized application more seamlessly by abstracting away gas fees and simplifying transaction management, thereby enhancing the overall user experience.

## 4. Deployments

| Smart Contract | Address |
| --------------------- | ------- |
| [SuperChainModule](https://github.com/Superchaineco/SuperChainSmartAccounts/blob/main/packages/smart-contracts/src/SuperChainModuleUpgradeable.sol) | [0x1Ee397850c3CA629d965453B3cF102E9A8806Ded](https://optimistic.etherscan.io/address/0x1Ee397850c3CA629d965453B3cF102E9A8806Ded) |
| [SuperChainGuard](https://github.com/Superchaineco/SuperChainSmartAccounts/blob/main/packages/smart-contracts/src/SuperChainGuard.sol) | [0xD5F838C84ADb53a6B1bEbBe7f54D4d54E924e7dF](https://optimistic.etherscan.io/address/0xD5F838C84ADb53a6B1bEbBe7f54D4d54E924e7dF) |
| [SuperChainBadges](https://github.com/Superchaineco/SuperChainSmartAccounts/blob/main/packages/smart-contracts/src/SuperChainBadges.sol) |[0x03e2c563cf77e3Cdc0b7663cEE117dA14ea60848](https://optimistic.etherscan.io/address/0x03e2c563cf77e3Cdc0b7663cEE117dA14ea60848) |
| [SuperChainAccountSetup](https://github.com/Superchaineco/SuperChainSmartAccounts/blob/main/packages/smart-contracts/src/SuperChainAccountSetup.sol) | [0x3b134026f14A697eEEE4623397E9c9DdC1223577](https://optimistic.etherscan.io/address/0x3b134026f14A697eEEE4623397E9c9DdC1223577) |
| [SuperChainResolver](https://github.com/Superchaineco/SuperChainSmartAccounts/blob/main/packages/smart-contracts/src/SuperChainResolver.sol) | 0x.... |

## 5. Internal

| Service | Account |
| --------------------- | ------- |
| Pimlico (UserOps) | Team account (Share your email to be added) |
| Gelato (Relay) | Team Account (Share your email to be added) |
| Backend address | [0x8835669696Fb92839aB198cD80ce9f0d35F45aD5](https://optimistic.etherscan.io/address/0x8835669696Fb92839aB198cD80ce9f0d35F45aD5) |