Complete guide for deploying, integrating, and interacting with Lilith's smart contract ecosystem.
Overview#
Lilith's blockchain layer provides:
- Access Tokens (ERC-1155): Subscription and course access management
- Content License NFTs (ERC-721): Content licensing with royalty distribution
- Creator Royalties: Creator registration and royalty tracking
- Identity & Reputation: Decentralized identity verification and reputation scores
- Security: Flash loan guards and reentrancy protection
Contract Architecture#
┌─────────────────────────────────────────────────────────────┐
│ User/Marketplace │
└────────────────────────┬────────────────────────────────────┘
│
┌───────────────┴───────────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────────┐
│ AccessToken │ │ RoyaltyLicenseManager│
│ (ERC-1155) │ │ (Orchestrator) │
└─────────────────┘ └──────────┬──────────┘
│
┌────────────────────┴────────────────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ CreatorRoyalties │ │ ContentLicenseNFT│
│ (Registry) │ │ (ERC-721) │
└─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ IdentityReputation│
│ (Verification) │
└─────────────────┘
AccessToken (ERC-1155)#
Multi-token standard for managing subscriptions, course access, and feature unlocks.
Token Types#
| Type | ID | Description |
|---|---|---|
| Basic Subscription | 1 | Monthly basic access |
| Premium Subscription | 2 | Monthly premium access |
| Lifetime Premium | 3 | One-time premium purchase |
| Course Access | 4 | Individual course access |
| Feature Access | 5 | Specific feature unlock |
| Content Access | 6 | Individual content access |
| Creator Token | 7 | Creator-specific benefits |
| Community Access | 8 | Community membership |
Key Functions#
// Purchase a token
function purchaseToken(
uint256 tokenId,
uint256 durationDays
) external payable;
// Check if user has premium access
function hasPremiumAccess(address user) external view returns (bool);
// Check if token is active for user
function isTokenActive(
address user,
uint256 tokenId
) external view returns (bool);
// Get user's active tokens (paginated)
function getUserActiveTokensPaginated(
address user,
uint256 offset,
uint256 limit
) external view returns (uint256[] memory tokenIds, uint256[] memory expirations);
Creating Token Types (Admin)#
function createTokenType(
uint256 tokenId,
string memory name,
uint256 price,
uint256 maxSupply,
bool transferable,
bool isPremium
) external onlyOwner;
Integration Example#
import { ethers } from 'ethers';
import { AccessToken__factory } from '@lilith/contracts';
const provider = new ethers.JsonRpcProvider(RPC_URL);
const signer = new ethers.Wallet(PRIVATE_KEY, provider);
const accessToken = AccessToken__factory.connect(CONTRACT_ADDRESS, signer);
// Purchase monthly subscription
const price = await accessToken.getTokenPrice(2); // Premium subscription
await accessToken.purchaseToken(2, 30, { value: price });
// Check access
const hasPremium = await accessToken.hasPremiumAccess(userAddress);
ContentLicenseNFT (ERC-721)#
NFT-based content licensing with royalty distribution following EIP-2981.
License Types#
| Type | Description |
|---|---|
| Personal | Personal use only |
| Commercial | Commercial use allowed |
| Derivative | Create derivative works |
| Redistribution | Redistribute content |
| Exclusive | Exclusive rights |
| Creator Rights | Full creator rights |
| Attribution Only | Free with attribution |
License Scopes#
| Scope | Description |
|---|---|
| Single Use | One-time use |
| Time Limited | Limited duration |
| Perpetual | Forever |
| Usage Limited | Limited uses |
| Territory Limited | Geographic restriction |
| Platform Limited | Platform-specific |
Key Functions#
// Issue a license NFT
function issueLicense(
address to,
string memory contentId,
LicenseType licenseType,
LicenseScope scope,
uint256 price,
address creator,
uint96 royaltyPercentage
) external payable returns (uint256 tokenId);
// Batch issue licenses
function batchIssueLicenses(
address[] memory recipients,
string[] memory contentIds,
LicenseType[] memory licenseTypes,
LicenseScope[] memory scopes,
uint256[] memory prices,
address creator,
uint96 royaltyPercentage
) external payable returns (uint256[] memory tokenIds);
// Get royalty info (EIP-2981)
function royaltyInfo(
uint256 tokenId,
uint256 salePrice
) external view returns (address receiver, uint256 royaltyAmount);
// Claim pending royalties (pull-payment pattern)
function claimPendingRoyalties() external;
Royalty Distribution#
Royalties are distributed automatically on secondary sales (marketplaces supporting EIP-2981):
// Default: 10% royalty to creator
// Max: 50% royalty cap
// Pull-payment for failed transfers
Integration Example#
// Issue a commercial license
const tx = await contentLicenseNFT.issueLicense(
buyerAddress,
"content_abc123",
1, // Commercial
2, // Perpetual
ethers.parseEther("0.1"),
creatorAddress,
1000 // 10% royalty
);
// Check license ownership
const owner = await contentLicenseNFT.ownerOf(tokenId);
const licenseInfo = await contentLicenseNFT.getLicense(tokenId);
CreatorRoyalties#
Registry for creator profiles, content licensing, and royalty distribution.
Creator Registration#
// Register as a creator
function registerCreator(
string memory name,
string memory bio,
string[] memory specializations,
string[] memory socialLinks
) external;
// Verify creator (admin only)
function verifyCreator(address creator) external onlyVerifier;
Content Registration#
// Register content for licensing
function registerContent(
string memory contentId,
string memory title,
string memory description,
uint256 basePrice,
address[] memory collaborators,
uint256[] memory collaboratorShares
) external;
License Purchasing#
// Purchase a license
function purchaseLicense(
string memory contentId,
LicenseType licenseType,
uint256 durationMonths
) external payable;
// Marketplace-delegated purchase
function purchaseLicenseFor(
address buyer,
string memory contentId,
LicenseType licenseType,
uint256 durationMonths
) external payable onlyAuthorizedMarketplace;
Pricing Tiers#
| License Type | Multiplier |
|---|---|
| Standard | 1x |
| Commercial | 3x |
| Exclusive | 10x |
| Educational | 0.5x |
| Open Source | Free |
| Duration | Discount |
|---|---|
| Monthly | 0% |
| Yearly | 20% |
Integration Example#
// Register as creator
await creatorRoyalties.registerCreator(
"Artist Name",
"Digital artist specializing in sacred geometry",
["meditation", "sacred_geometry"],
["https://twitter.com/artist"]
);
// Register content
await creatorRoyalties.registerContent(
"artwork_001",
"Sacred Mandala",
"AI-generated sacred geometry artwork",
ethers.parseEther("0.05"),
[collaboratorAddress],
[2000] // 20% to collaborator
);
// Purchase license
const price = await creatorRoyalties.calculateLicensePrice(
"artwork_001",
1, // Commercial
12 // 12 months
);
await creatorRoyalties.purchaseLicense("artwork_001", 1, 12, { value: price });
IdentityReputation#
Decentralized identity verification and reputation scoring.
Identity Types#
| Type | Description |
|---|---|
| Individual | Personal user |
| Organization | Company/team |
| Institution | Educational/religious |
| Validator | Verification service |
| Oracle | Data provider |
| Community | Community group |
Verification Types#
| Type | Stake | Reward |
|---|---|---|
| 0.01 ETH | 0.005 ETH | |
| Phone | 0.05 ETH | 0.025 ETH |
| Government ID | 1 ETH | 0.5 ETH |
| Educational Credential | 0.5 ETH | 0.25 ETH |
| Professional License | 0.8 ETH | 0.4 ETH |
| Social Media | 0.02 ETH | 0.01 ETH |
| Domain Ownership | 0.1 ETH | 0.05 ETH |
| Biometric | 0.5 ETH | 0.25 ETH |
| Community Vouching | 0.05 ETH | 0.025 ETH |
| Expert Endorsement | 0.2 ETH | 0.1 ETH |
Reputation Components#
struct ReputationScore {
uint256 contentQuality; // 0-2500
uint256 communityEngagement; // 0-2500
uint256 trustworthiness; // 0-2500
uint256 expertise; // 0-2500
}
// Total max: 10,000 points
Reputation Tiers#
| Tier | Score Range |
|---|---|
| Bronze | 0 - 2,499 |
| Silver | 2,500 - 4,999 |
| Gold | 5,000 - 7,499 |
| Platinum | 7,500+ |
Key Functions#
// Register identity
function registerIdentity(
IdentityType identityType,
string memory did,
string memory publicKey,
string memory metadata
) external;
// Stake and claim verification
function stakeAndClaimVerification(
address subject,
VerificationType verificationType,
bytes memory proof
) external payable;
// Challenge a verification (dispute)
function challengeVerification(
uint256 claimId,
string memory reason,
bytes memory evidence
) external payable;
// Resolve challenge (authorized resolvers)
function resolveChallenge(
uint256 challengeId,
bool challengerWins,
string memory resolution
) external onlyAuthorizedResolver;
// Update reputation
function updateReputation(
address subject,
ReputationAction action,
int256 change
) external onlyAuthorizedUpdater;
Challenge System#
- 30-day challenge window from claim issuance
- 7-day resolution period for disputes
- Stake matching - challenger must stake equal amount
- Slashing - 50% penalty for false claims/challenges
Integration Example#
// Register identity
await identityReputation.registerIdentity(
0, // Individual
"did:lilith:user123",
publicKeyBytes,
JSON.stringify({ name: "User", country: "US" })
);
// Claim email verification
await identityReputation.stakeAndClaimVerification(
userAddress,
0, // Email
emailProof,
{ value: ethers.parseEther("0.01") }
);
// Get reputation
const rep = await identityReputation.getReputationScore(userAddress);
const tier = await identityReputation.getReputationTier(userAddress);
RoyaltyLicenseManager#
Orchestrator that combines license purchase with NFT minting in a single transaction.
Key Functions#
// Purchase license and mint NFT in one transaction
function purchaseAndMintLicense(
string memory contentId,
LicenseType licenseType,
uint256 durationMonths
) external payable returns (uint256 nftTokenId);
// Claim refunds (pull-payment)
function claimRefund() external;
Integration Example#
// Single transaction: purchase + mint
const tx = await royaltyLicenseManager.purchaseAndMintLicense(
"content_abc",
1, // Commercial
12, // 12 months
{ value: ethers.parseEther("0.15") }
);
const receipt = await tx.wait();
const tokenId = receipt.logs[0].args.tokenId;
FlashLoanGuard#
Security module preventing same-block multi-action attacks.
Usage#
import "./security/FlashLoanGuard.sol";
contract MyContract is FlashLoanGuard {
function sensitiveAction() external flashLoanGuarded {
// Protected from same-block repeated calls
}
}
How It Works#
- Tracks
_lastActionBlock[address]per user - Prevents calling protected functions twice in same block
- Complements ReentrancyGuard (same-transaction protection)
Deployment#
Prerequisites#
# Install dependencies
cd contracts
npm install
# Set environment variables
cp .env.example .env
# Edit .env with your values
Environment Variables#
# RPC Endpoints
ETHEREUM_RPC_URL=https://eth-mainnet.alchemyapi.io/v2/YOUR_KEY
POLYGON_RPC_URL=https://polygon-mainnet.alchemyapi.io/v2/YOUR_KEY
ARBITRUM_RPC_URL=https://arb-mainnet.alchemyapi.io/v2/YOUR_KEY
# Private Keys (NEVER COMMIT)
DEPLOYER_PRIVATE_KEY=your_private_key
# Verification
ETHERSCAN_API_KEY=your_etherscan_key
POLYGONSCAN_API_KEY=your_polygonscan_key
# Contract Configuration
TREASURY_ADDRESS=0x...
PLATFORM_FEE_PERCENTAGE=250
Deploy to Testnet#
# Compile
npx hardhat compile
# Deploy to Sepolia
npx hardhat run scripts/deploy-testnet.ts --network sepolia
# Verify contracts
npx hardhat verify --network sepolia DEPLOYED_ADDRESS
Deploy to Mainnet#
# Run pre-mainnet checks
npx hardhat run scripts/pre-mainnet-check.ts
# Deploy (UUPS upgradeable)
npx hardhat run scripts/deploy-upgradeable.ts --network mainnet
# Verify
npx hardhat verify --network mainnet PROXY_ADDRESS
Multi-Chain Deployment#
# Deploy to multiple chains
npx hardhat run scripts/deploy-multichain.ts
# Supported networks:
# - Ethereum Mainnet (1)
# - Polygon (137)
# - Arbitrum One (42161)
# - Optimism (10)
# - Base (8453)
Upgrading Contracts#
All core contracts use the UUPS proxy pattern for upgradability.
Upgrade Process#
# 1. Deploy new implementation
npx hardhat run scripts/upgrade.ts --network mainnet
# 2. Verify new implementation
npx hardhat verify --network mainnet NEW_IMPL_ADDRESS
# 3. Test upgrade (dry run)
npx hardhat run scripts/upgrade.ts --network mainnet --dry-run
Upgrade Safety#
// Upgrade safety test
const upgraded = await upgrades.upgradeProxy(
proxyAddress,
NewImplementation,
{ call: { fn: 'reinitialize', args: [newVersion] } }
);
Security Considerations#
Access Control#
Ownable2Step: Two-step ownership transfer prevents accidental transfers- Role-based:
onlyOwner,onlyVerifier,onlyAuthorizedMarketplace - Admin functions protected with access control
Reentrancy Protection#
ReentrancyGuardon all payment functionsFlashLoanGuardfor same-block attack prevention- Checks-Effects-Interactions pattern
DoS Prevention#
- Paginated queries with
MAX_ENUMERATION_LIMIT = 100 - O(1) counters instead of array iteration
MAX_TOKEN_TYPES = 1000limit
Payment Safety#
- Pull-payment pattern for failed transfers
pendingRoyaltiesmapping for claim later- Low-level call for ETH transfers (supports smart contract wallets)
Emergency Controls#
Pausablemodifier on critical functionsemergencyWithdraw()for fund extraction- Owner-controlled pause/unpause
Testing#
Run Tests#
# All tests
npx hardhat test
# Specific contract
npx hardhat test test/AccessToken.test.ts
# With coverage
npx hardhat coverage
Fuzz Testing (Foundry)#
# Install Foundry
curl -L https://foundry.paradigm.xyz | bash
foundryup
# Run fuzz tests
forge test --fuzz-runs 100000
Gas Optimization#
| Operation | Gas Cost |
|---|---|
| purchaseToken | ~85,000 |
| issueLicense | ~120,000 |
| registerCreator | ~150,000 |
| purchaseLicense | ~180,000 |
| stakeAndClaimVerification | ~200,000 |
Optimization Tips#
- Batch operations when possible
- Use
calldatafor read-only arrays - Pack storage variables
- Use custom errors (22% gas savings)
Contract Addresses#
Testnet (Sepolia)#
| Contract | Address |
|---|---|
| AccessToken | See /deployments/sepolia.json |
| ContentLicenseNFT | See /deployments/sepolia.json |
| CreatorRoyalties | See /deployments/sepolia.json |
| IdentityReputation | See /deployments/sepolia.json |
| RoyaltyLicenseManager | See /deployments/sepolia.json |
Mainnet#
Pending deployment. Check /deployments/mainnet.json after launch.