https://github.com/bitsocialnet/mintpass
NFT-based authentication system for Bitsocial communities
https://github.com/bitsocialnet/mintpass
anti-spam anti-sybils authentication authentication-middleware bitsocial challenge decentralized nft pkc pkc-js sms-verification social-media social-network sybil-resistance
Last synced: about 2 months ago
JSON representation
NFT-based authentication system for Bitsocial communities
- Host: GitHub
- URL: https://github.com/bitsocialnet/mintpass
- Owner: bitsocialnet
- License: mit
- Created: 2025-06-05T14:19:29.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2026-04-18T07:56:15.000Z (2 months ago)
- Last Synced: 2026-04-18T09:37:26.449Z (2 months ago)
- Topics: anti-spam, anti-sybils, authentication, authentication-middleware, bitsocial, challenge, decentralized, nft, pkc, pkc-js, sms-verification, social-media, social-network, sybil-resistance
- Language: TypeScript
- Homepage: https://mintpass.org
- Size: 3.04 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
[](http://commitizen.github.io/cz-cli/)
# MintPass - NFT Authentication Middleware for Bitsocial
MintPass is an NFT-based authentication system that provides verified identity proofs for decentralized communities. It began as an anti‑spam challenge for Bitsocial communities, and it works equally well for other protocols and social applications. Users mint a non‑transferable verification NFT (e.g., after SMS OTP) that communities can check to reduce sybil attacks, such as fake upvotes/downvotes, fake conversations, and users evading bans.
## How people use MintPass
1) Visit `mintpass.org/request`, enter a phone number, and complete SMS OTP.
2) MintPass mints an NFT (on testnet in this reference deployment) to your wallet or records an equivalent “verified” state when on‑chain minting is disabled.
3) Communities (e.g., Bitsocial communities) check ownership of the NFT to treat you as authenticated for anti‑spam.
The request form looks like this:
## What is Bitsocial?
Bitsocial is p2p and decentralized social media protocol built completely with IPFS/IPNS/pubsub. It doesn't use any central server, central database, public HTTP endpoint or DNS, it is pure peer to peer (except for the web client that can't join a P2P swarm directly, web clients use interchangeable HTTP providers). It allows community owners to retain full ownership over their community. Whitepaper [here](https://github.com/pkc/whitepaper/discussions/2).
MintPass integrates as a challenge so Bitsocial communities can distinguish real users and limit abuse without central servers. Because the artifact is an NFT, other decentralized apps can use the same credential to authenticate users.
## Project Structure
```
mintpass/
├── contracts/ # MintPassV1 smart contract and tooling
├── challenge/ # Bitsocial challenge implementation (“mintpass”)
├── web/ # Next.js website + API (mintpass.org)
├── docs/ # Documentation and specifications
├── tests/ # Cross‑component integration tests
└── scripts/ # Deployment and utilities
```
### Subprojects
- `contracts/`: Solidity contracts (MintPassV1). Versioned, role‑based minting, token types per NFT (type 0 = SMS). See `contracts/README.md`.
- `challenge/`: The Bitsocial challenge that checks for a MintPass NFT and applies additional rules (e.g., transfer cooldowns) to resist sybils.
- `web/`: The user‑facing site and serverless backend. Sends SMS codes, verifies OTP, and mints or records successful verification. See `web/README.md`.
## Privacy and anti‑sybil design (high level)
- Short‑lived operational data (OTP codes, verification markers, rate‑limit state) stored in Redis with TTLs.
- Persistent “mint association” between wallet and phone to prevent duplicate mints.
- Optional IP reputation (VPN/proxy) and phone‑risk checks, optional geoblocking, and per‑IP cooldowns.
- Secrets live only in environment variables; logs avoid PII and never include OTPs or private keys.
## Getting started
1. Run `nvm install && nvm use`
2. Run `corepack enable` once per machine so `yarn` resolves to the pinned Yarn 4 release
3. Use plain `yarn install`, `yarn build`, and `yarn test`
- Contracts: `cd contracts && yarn install && yarn test`
- Challenge: `cd challenge && yarn install && yarn test`
- Web: `cd web && yarn install && yarn dev` then open `https://mintpass.localhost/request`
## Using MintPass in your community
Community owners add the MintPass challenge to their community settings. When enabled, every publication (post, reply, vote) requires the author to hold a valid MintPass NFT. The challenge is published as [`@bitsocial/mintpass-challenge`](https://www.npmjs.com/package/@bitsocial/mintpass-challenge) on npm.
### With pkc-js over RPC
If your RPC server is already running, first install the challenge on the server:
```bash
bitsocial challenge install @bitsocial/mintpass-challenge
```
Then from your RPC client, connect and set the challenge on your community by name — no npm install or challenge registration needed on the client side:
```ts
import PKC from "@pkcprotocol/pkc-js";
const pkc = await PKC({
pkcRpcClientsOptions: ["ws://localhost:9138"]
});
const community = await pkc.createCommunity({ address: "your-community-address.bso" });
await community.edit({
settings: {
challenges: [
{
name: "@bitsocial/mintpass-challenge",
options: {
chainTicker: "base",
contractAddress: "0x13d41d6B8EA5C86096bb7a94C3557FCF184491b9",
requiredTokenType: "0",
transferCooldownSeconds: "604800"
}
}
]
}
});
```
### With pkc-js (TypeScript)
Install the challenge package:
```bash
npm install @bitsocial/mintpass-challenge
```
Register the challenge and configure your community:
```typescript
import PKC from '@pkcprotocol/pkc-js'
import mintpassChallenge from '@bitsocial/mintpass-challenge'
// Register the challenge so it can be referenced by name
PKC.challenges['@bitsocial/mintpass-challenge'] = mintpassChallenge
const pkc = await PKC({ /* your pkc options */ })
const community = await pkc.createCommunity({ address: 'your-community.bso' })
await community.edit({
settings: {
challenges: [{
name: '@bitsocial/mintpass-challenge',
options: {
chainTicker: 'base',
contractAddress: '0x13d41d6B8EA5C86096bb7a94C3557FCF184491b9',
requiredTokenType: '0',
bindToFirstAuthor: 'true',
transferCooldownSeconds: '604800',
}
}]
}
})
```
#### Challenge options
All option values must be strings (pkc-js challenge convention).
| Option | Default | Description |
|--------|---------|-------------|
| `chainTicker` | `"base"` | Chain where MintPass is deployed |
| `contractAddress` | Base Sepolia default | Contract address (auto-detected for supported chains) |
| `requiredTokenType` | `"0"` | Token type (0 = SMS, 1 = Email) |
| `bindToFirstAuthor` | `"true"` | Bind NFT to first author per community |
| `transferCooldownSeconds` | `"604800"` | Cooldown after NFT transfer (1 week) |
| `error` | Default message | Custom error (`{authorAddress}` placeholder supported) |
| `rpcUrl` | Chain default | Optional custom RPC URL |
### With bitsocial-cli
Install the challenge package:
```bash
bitsocial challenge install @bitsocial/mintpass-challenge
```
Edit your community to use the challenge:
```bash
bitsocial community edit your-community.bso \
'--settings.challenges[0].name' @bitsocial/mintpass-challenge \
'--settings.challenges[0].options.chainTicker' base \
'--settings.challenges[0].options.contractAddress' '0x13d41d6B8EA5C86096bb7a94C3557FCF184491b9' \
'--settings.challenges[0].options.requiredTokenType' '0' \
'--settings.challenges[0].options.bindToFirstAuthor' 'true' \
'--settings.challenges[0].options.transferCooldownSeconds' '604800'
```
See the [bitsocial-cli documentation](https://github.com/bitsocial/bitsocial-cli) for full CLI reference.
## Where MintPass is useful
While designed for Bitsocial, any decentralized or serverless social app can use MintPass NFTs as a lightweight proof‑of‑personhood. Apps only need to check ownership of a token type (e.g., type 0 for SMS) to gate actions or increase trust in votes and reports.
## Roadmap and considerations
We plan to support multiple authentication methods alongside SMS OTP to fit different threat models and UX constraints:
- Add a “pay‑to‑mint” option with a small fee that is high enough to deter bulk purchases but low enough for regular users.
- Add additional human‑verification signals (e.g., email, government‑backed KYC providers, or proofs such as biometrics/world‑ID systems) when they can be integrated without compromising decentralization goals.
- Expand admin tooling, heuristics, and optional device signals to further reduce abuse.
These items are exploratory; concrete work will land incrementally and stay configurable so communities can choose what they trust.
## Technology Stack
- **Smart Contracts**: Solidity, Hardhat/Foundry
- **Website**: Next.js, React, Ethereum (ethers)
- **Challenges**: TypeScript, pkc-js integration
- **Deployment**: Base network (L2)
## License
MIT License — see [LICENSE](LICENSE).
Open source and commercial‑friendly. A hosted version is available at [mintpass.org](https://mintpass.org).