Non-transferrable ERC1155 token standard for accomplishments, certifications, and proof of completion.

Empowering communities to govern their own "blue checkmarks".

• Landing: https://www.soulbound.fyi (coming soon)
• App client: TBD

Alpha launching Summer 2023

What we do makes up who we are.

But our accomplishments don't "live anywhere" and it's hard to prove and share them.

If they do exist online, they're scattered. Career history is on LinkedIn. Travel history is on Instagram. My scuba diving certification is a plastic card in my wallet.

What if we could collect our experiences in a single place? What if the community that shared in those accomplishments could issue them? What if they were provable and trustworthy? What if other apps and services could easily integrate them?

A platform where:

• Communities can issue proof of completion/endorsement for anything
• Users can collect, share, and prove their endorsements without necessarily managing a wallet
• Other services and platforms can easily integrate, display, and build on top of these endorsements

• New York Road Runners (Marathon/Race Org): issues race medals as Soulbound tokens to participants. Includes rich metadata for race placement, timing, age group, and charity involvement.
• Padi Scuba Diving Organization: represents various diving certifications (Open Water Diver, Underwater Hunter, Master Diver, etc.) via Soulbound tokens with expiration date stored on chain. Tokens are proveable and recognizable at any international dive shop.
• Forbes 30 under 30 Award: represents being a recipeient of the Forbes 30 under 30 award. This badge can then be shared across socials including Instagram (Instagram Collectibles) and Twitter.

Org customizes their BadgeSet (contract-level) metadata and deploys it. Can manage via their own wallets, or use Soulbound's DAPP client with wallet custody (WIP).

badgeTypes are like token blueprints. For example: PADI may create a high level "Open Water Diver" certification badge, which has a base set of metadata, but that badgeType can be minted to any number of people. Each individual's badge can have token-level metadata, such as expiration, location of certification, etc. badgeTypes are fully customizable.

Orgs can mint tokens to any address. However, they have the special ability to mint to a user's liteWallet.

A liteWallet is an address representing the hashed combination of a user's first name, last name, and phone number.

Because tokens are non-transferable and issued to real people, it does not matter if a user (or anyone) has the private key to the liteWallet. Instead, it acts as an escrow account that users can prove is theirs (via KYC) if they ever choose to (but not required).

Users can view all Soulbound tokens minted to their liteWallet or real wallet via smart contract view functions, or via our DAPP client (WIP).

Openness and free discovery of tokens is important. In many cases, liteWallets will be enough for people to demonstrate token ownership, especially when there is already sufficient social trust (someone believes your name and phone number). This will give rise to all sorts of lightweight authentication and proof of completion, without the need for on-chain signatures.

With that said, users can still link their liteWallets to a real wallet to provide signing functionality and prove they own their tokens.

A liteWallet can be associated with a real wallet if a user decides to link them. Once linked, a user can use their linked real wallet to sign transactions proving ownership of Soulbound tokens.

This can be very useful across a variety of applications. For example: showing Soulbound tokens on Instagram Collectibles, adding them to an OpenSea account, etc. These use cases will gain even more utility over time as more applications are built with token gating and proof of ownership.

In order to link a liteWallet to a real wallet, a user must verify their identity to ensure Soulbound tokens are not attributed to the wrong person. To start, this verification process will be centralized, but we will explore ways to decentralize it in the future.

Once wallets are linked:

1. A liteWallet to real wallet mapping is added to the WalletRegistry smart contract for reference
2. All BadgeSets will update their balances to point to the real wallet
3. Any future mints to a liteWallet will automatically be forwarded to the real wallet.

Wallets can also be unlinked and re-linked.

Communities and users can use Soulbound tokens for a variety of use cases.

For instance: sharing and proving accomplishments online and through various platforms, token gating to services and events, replacement for ID or loyalty cards, and many more.

• Tokens are ERC1155 compliant: Soulbound tokens use the ERC1155 token interface, and are fully ERC1155 compliant. This means Soulbound tokens will show up on OpenSea or any protocol that supports the ERC1155 standard.

• Tokens are non-transferable: Soulbound tokens cannot be transferred once they are minted. All ERC1155 standard transfer and approval functions (transfer(), transferFrom(), setApprovalForAll()) are overridden to revert. However, the issuing organization can revoke Soulbound tokens, effectively burning them for a given user. An organization can revoke and mint new tokens as many times as they'd like.

• Token expiry stored on chain: Soulbound token contracts store a specific token's expiration timestamp directly on chain (if provided at mint). This is queryable via the contract's expiryOf() function, and can be included in a token's metadata.

• Metadata is customizable, can be hosted anywhere: organizations can decide how they'd like to structure token metadata and where they'd like to host it. Soulbound will provide a centralized, out of the box metadata creation and storage solution if orgs decide to use it.

• liteWallets: orgs can mint to any address, but they have the option to mint to a user's liteWallet. A liteWallet is a read-only ETH address representing the hashed combination of a user's first name, last name, and phone number. Because tokens are non-transferable and issued to real people, it does not matter if a user (or anyone) has the private key to the liteWallet. Instead, it acts as an escrow account that users can prove is theirs (via KYC) if they ever choose to.

• WalletRegistry stores liteWallet mapping: liteWallet to real wallet mapping is maintained in the separate WalletRegistry.sol contract. This contract is the only centrally owned contract by the Soulbound protocol, as full KYC verification must be done centrally for cases where users want to link a wallet. We are exploring other KYC options to make this feature fully decentralized, but for the interim the registry is managed by the Soulbound organization. We're getting there!

• tokenIds are serialized: traditionally, ERC1155 tokenIds are sequential/static (uint256). Soulbound tokens, however, derive tokenIds by serializing a user's address (address) and the badgeType (uint96). Because each user can only have one of each badgeType, this allows for unique ids for each user/badgeType combination, and in turn the ability to blend both badgeType and user level metadata.

• Bitmaps: token ownership is represented via Bitmaps. Bitmaps are a great fit data structure because each user can only own one of each badgeType, and ownership state must be transitioned on-chain to a real wallet (if a user links) as gas-efficiently as possible. Copying over bitmaps is easy (a single uint256 to store 256 badgeType ownership flags)! Individual key/value mappings are not a good fit for these use cases.

• Orgs decide contract management/ownership: Soulbound smart contracts are designed so that any community can deploy and manage their own contracts within the Soulbound ecosystem on their own and with their own wallets. However, we will also provide a number of custodial services and user-friendly front end clients to remove complexity and friction for communities (if they so choose).

• Built on Base: Soulbound smart contracts will be deployed to Base.

1. Contracts drafted: version 1.0 finished, deployed to Base testnet (done)
2. Contracts finalized: deployed to mainnet (July 2023)
3. Closed alpha: 5 orgs, tokens managed and minted manually with white-glove service, gather feedback (August 2023)
4. Client DAPPS: Org and user front ends finished, allowing for self service signup, minting, basic wallet custody, and token management (September 2023)
5. Open beta: 25 orgs (October 2023)

• Centralization of verifying wallet ownership during transition: if a user decides to link a real wallet to their liteWallet, we must be sure that the user is who they say they are (and deserves the already minted badges in the liteWallet). In the future, we'll be exploring decentralized and community-based ID verification to do this, but for the initial launch we will be verifying each wallet link manually. Not ideal, but decentralization is important and we'll get there.

• Token data is public: a tradeoff with non-transferable tokens is that they exist on-chain, and so their data is public. If a user wishes to keep some accomplishments/verifications private, that isn't currently supported. This is an important protocol design consideration to minimize discrimination and maximize user privacy. This is a high priority, and we want to build towards a solution.

• Token minting is permissionless: in other words, users will always "have" minted tokens in their wallets, and will not be required to accept and approve them. Current token standards also work this way, and the filtering/hiding of unwanted tokens happens on the view layer (OpenSea, etc.). A request/approval feature for minted badges is interesting and something we're considering.

• BadgeSetFactory.sol: 0x41469267878F9F0cF668A1bda2daB9CdB3838e26
• WalletRegistry.sol: 0x62dD845af0614234865E5D2A15B8C133eDC51E1b

1. Clone repository: git clone https://github.com/brianwatroba/soulbound.git
2. Install base project dependencies: cd into root, run npm install
3. Add local .env file to project root. Include below env variables (replace keys with your own):
4. If you're deploying, ensure you have Base Goerli ETH in your deployer address

/.env

# Wallet private keys for deployment
PRIVATE_KEY=xxx

# RPC URL
BASE_GOERLI_URL=https://goerli.base.org

1. Local testing: tests written in Chai/Mocha using Hardhat/Ethers.js. Run npx hardhat test for test suite.
2. Deployment to Base (Goerli): ensure your .env file includes your BASE_GOERLI_URL and private key corresponding to a funded account. Then run npx hardhat run scripts/deployContracts.ts --network base-goerli. Deploy script deploys BadgeSetFactory, two test BadgetSet contracts, WalletRegistry, and verifies all bytecode.
3. Deployment to other networks: add your desired network to the networks object in hardhat-config.ts using the following format:

/hardhat.config.ts

"base-goerli": {
      url: process.env.BASE_GOERLI_URL || "",
      accounts: process.env.PRIVATE_KEY !== undefined ? [process.env.PRIVATE_KEY] : [],
    },

And copy/edit one of the existing deploy scripts to work with your network of choice.

Pull requests are welcome. Thanks for your interest!

MIT