Setting Up Consent Management for Web3 User Onboarding

Web3 consent management is the practice of obtaining and recording explicit user permission before collecting personal data or enabling specific on-chain interactions. Unlike traditional web2 models that rely on centralized databases, Web3 consent must be immutable, verifiable, and user-controlled. This is critical for compliance with regulations like GDPR and for building user trust in applications that handle sensitive data, such as decentralized identity (DID) systems or DeFi platforms requiring KYC.

The technical foundation for Web3 consent is a consent receipt, a cryptographically signed record stored on-chain or in a decentralized storage network like IPFS or Arweave. This receipt should specify the purpose of data collection, the types of data involved, and the duration of consent. Smart contracts, such as those built with OpenZeppelin's access control libraries, can enforce that certain functions (e.g., minting a credential) are only callable if a valid consent receipt exists for the user's address.

A basic implementation involves a user signing a structured message (EIP-712) with their wallet. This signature acts as proof of consent. The dApp backend or a dedicated smart contract can then verify this signature. For example, you might create a ConsentRegistry contract with a mapping like mapping(address => mapping(bytes32 => Consent)) public userConsents, where the bytes32 key is a hash of the consent terms. The W3C Verifiable Credentials data model provides a robust standard for structuring this information.

For user onboarding, integrate consent prompts directly into the wallet connection flow. After connecting with a library like WalletConnect or Web3Modal, present clear, human-readable terms. Use a service like SpruceID's did:key or Civic's Passport to bind consent to a decentralized identifier, separating consent from a single wallet address. This design ensures consent is portable and can be revoked by the user across different interfaces.

Best practices include providing an easy revocation mechanism, such as a function in your smart contract that deletes the user's consent record, and implementing event logging for all consent actions to create an audit trail. Always store the minimal data necessary on-chain; hash personal data and store the full consent document off-chain, linking to it via the on-chain hash. This balances transparency with user privacy and manages gas costs.

Before building a consent management system for Web3 onboarding, you need a foundational understanding of Web3 development. This includes proficiency with a JavaScript framework like React or Vue for the frontend, and familiarity with Ethereum tooling such as ethers.js or viem for wallet interactions. You should also be comfortable with asynchronous programming to handle blockchain RPC calls and wallet connection flows. A basic grasp of smart contract events is crucial, as they are often used to log user consent actions on-chain for auditability.

The core technical stack revolves around wallet connection libraries and on-chain data management. For wallet integration, use WalletConnect v2 or Web3Modal to support a wide range of browser extensions and mobile wallets. To store and query consent records, you'll interact with a smart contract. You can deploy your own using a framework like Hardhat or Foundry, or integrate with an existing attestation service like EAS (Ethereum Attestation Service) on Optimism or Base. For off-chain data associated with consent (like policy versions or user preferences), you'll need a database, with IPFS being a common choice for decentralized storage via platforms like Pinata or web3.storage.

Key dependencies for a typical project include wagmi for React hooks, viem as the Ethereum client, and @walletconnect/modal for connection UI. Your development environment should have Node.js v18+, npm or yarn, and access to a blockchain testnet via a provider like Alchemy or Infura. It's essential to set up environment variables for your project's RPC URLs, WalletConnect Project ID (from walletconnect.com), and any API keys for storage services. Testing should be done on Sepolia or Base Sepolia before mainnet deployment.

Understanding the user consent lifecycle is a critical non-technical prerequisite. You must design for key actions: the initial grant of consent, user access to their stored preferences, the ability to modify consent (e.g., opting out of marketing), and data deletion requests (handled via smart contract state changes or attestation revocation). Your architecture should map each of these intents to a specific transaction or signed message, creating a transparent and user-verifiable trail.

A robust consent management system for Web3 onboarding must be architected around user sovereignty and provable verification. Unlike traditional models where consent is a database flag, Web3 consent should be a verifiable, on-chain attestation linked to a user's wallet. The core components are a frontend dApp interface, a consent registry smart contract, and an off-chain verification service. The data flow begins when a user connects their wallet (e.g., MetaMask) and is presented with clear data usage terms before any transaction is signed.

The smart contract is the system's backbone. It should implement a standard like EIP-712 for structured, signable consent messages, allowing users to understand exactly what they are approving. A function like grantConsent(bytes32 consentHash, uint256 expiry) records a user's approval. The consentHash is a keccak256 hash of the consent terms, ensuring immutability. Storing only the hash on-chain minimizes gas costs and preserves privacy, while the full terms are stored off-chain (e.g., on IPFS) with the hash acting as a cryptographic proof of the agreed version.

Off-chain services handle the verification logic and data routing. After a user signs an EIP-712 message, the dApp frontend sends the signature and payload to a backend verifier. This service validates the signature against the user's wallet address, checks the consent hash against the known terms, and verifies the consent has not expired. Only upon successful verification does the service grant the user an access token (like a JWT) or forward the request to the protected API or data pipeline. This separation keeps sensitive user data off-chain while leveraging the blockchain for audit trails.

For practical implementation, consider integrating with Sign-In with Ethereum (SIWE) for authentication, which naturally extends to consent. Your consent message can be an extension of the SIWE statement. Furthermore, you can use EAS (Ethereum Attestation Service) or Verax to create standardized, portable consent attestations that can be queried by other compliant applications, moving towards a user-centric data economy. Always emit events like ConsentGranted and ConsentRevoked from your smart contract for easy indexing by subgraphs or backend listeners.

Key architectural decisions involve gas optimization (using signatures over transactions), revocation mechanisms (allowing users to revoke via a similar signed message), and handling chain reorgs (using block timestamps with safe margins for expiry). The end goal is a seamless flow: User Connects Wallet → Reviews Terms → Signs Message → Verification Service Validates → Access is Granted. This creates a transparent, user-auditable trail of consent that respects Web3 principles while enabling compliant data usage.

A Web3 consent interface must clearly communicate what data is collected, why it's needed, and how it will be used. Unlike traditional web2 forms, this often includes explaining on-chain data (e.g., wallet address, transaction history) and off-chain data (e.g., email, KYC details). Use plain language, avoid legal jargon, and structure information in a scannable format. Key elements to display include: the specific data points requested, the purpose for each (e.g., "Wallet address for gas fee sponsorship"), the data storage method (on-chain, encrypted off-chain), and data retention policies.

For technical implementation, you can build a component using a frontend framework like React. The interface should capture explicit user action—a click on an "I Agree" button—only after the user has had a chance to review the terms. This action should trigger a function that records the consent proof. A common pattern is to hash the consent terms and the user's wallet address, then sign this hash with the user's wallet (e.g., using eth_signTypedData_v4) to create a verifiable, non-repudiable record. Store the signature and the consent version in your backend or on-chain via a smart contract.

Consider implementing granular consent controls where possible. Instead of a single "accept all" button, provide toggles for different categories: ESSENTIAL (required for core app function), ANALYTICS (for improving the service), and MARKETING (for communications). This aligns with principles of data minimization and user autonomy. The chosen preferences must be cryptographically linked to the user's consent record, ensuring the app's subsequent data processing is strictly scoped to what was authorized.

Always design for revocability. Users must be able to withdraw consent as easily as they gave it. Provide a clear path in the application settings to manage preferences. Upon revocation, your system must have processes to delete or anonymize the user's data where legally required, and update the consent state in your records. This cycle of clear capture, verifiable proof, and easy management forms the foundation of ethical and compliant Web3 user onboarding.

A user signature is a cryptographic proof that a specific wallet owner has agreed to your application's terms. Unlike a simple transaction signature, a consent signature is generated by signing a structured message, often following the EIP-712 standard. This standard allows wallets to present the consent data in a human-readable format before the user signs, providing clear context and enhancing security. The signed message typically includes the consent document's hash, a timestamp, and the user's address.

To implement this, you first need to define the signature payload. This is a structured object containing the domain (your dApp's name, version, chainId), the types of data being signed, and the primary message. For consent, the message should include a unique identifier for the terms (like a content hash) and a statement of consent. Using a library like ethers.js or viem, you can then prompt the user's wallet (e.g., MetaMask) to sign this typed data. The wallet will display the formatted request, and upon approval, return the signature.

Here is a simplified example using ethers.js v6 to request a signature for consent to a privacy policy:

javascriptCopy
import { ethers } from 'ethers';

const domain = {
  name: 'MyWeb3App',
  version: '1',
  chainId: 1, // Mainnet
  verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC'
};

const types = {
  Consent: [
    { name: 'policyHash', type: 'bytes32' },
    { name: 'user', type: 'address' },
    { name: 'agreed', type: 'bool' }
  ]
};

const value = {
  policyHash: '0x1234...', // Keccak256 hash of the policy text
  user: userAddress,
  agreed: true
};

const signature = await provider.getSigner()._signTypedData(domain, types, value);

This signature, along with the original message data, forms an immutable record of consent.

After obtaining the signature, your backend must verify its validity before storing it. Verification involves recovering the signer's address from the signature and the original message data using the ecrecover function (or its library equivalent). If the recovered address matches the user's provided address, the consent is valid. This step is crucial to prevent spoofing and ensures the record is legally defensible. Store the signature, the signed message, and a timestamp in your database or on-chain in a smart contract for permanent auditability.

Best practices for consent signatures include using a nonce or timestamp to prevent signature replay attacks, clearly displaying the consent text hash in the wallet prompt, and regularly updating your signing domain when application terms change. For maximum transparency, consider emitting an on-chain event with the consent record, creating a public, verifiable log. This approach aligns with data privacy regulations like GDPR, which require demonstrable and revocable user consent.

After a user provides consent off-chain, the next step is to create an immutable on-chain record. This is achieved by generating a cryptographic hash of the consent data and storing it on a blockchain like Ethereum, Polygon, or Base. The hash acts as a unique, tamper-proof fingerprint. Common hashing algorithms include SHA-256 and Keccak-256. The core data hashed typically includes the user's wallet address, a consent policy identifier (e.g., a URI), a timestamp, and a session ID.

The resulting hash is then written to the blockchain via a transaction. This can be done by calling a dedicated recordConsent function in a smart contract. The contract stores the hash in a mapping, such as mapping(address => bytes32) public userConsentHashes;. This on-chain storage provides a public, timestamped proof that consent was given at a specific block number. The transaction's gas cost is a consideration, making layer-2 solutions attractive for this use case.

Here is a simplified Solidity example of a consent registry contract:

solidityCopy
contract ConsentRegistry {
    mapping(address => bytes32) public consentProofs;
    
    function recordConsent(bytes32 _consentHash) external {
        require(_consentHash != 0, "Invalid hash");
        consentProofs[msg.sender] = _consentHash;
        emit ConsentRecorded(msg.sender, _consentHash, block.timestamp);
    }
    
    function verifyConsent(address _user, bytes32 _claimedHash) external view returns (bool) {
        return consentProofs[_user] == _claimedHash;
    }
}

The recordConsent function allows a user's wallet to submit their consent hash, while verifyConsent lets any party validate it.

Storing only the hash, not the raw data, balances transparency with privacy. The original consent document (e.g., a JSON file) remains off-chain, but its integrity is guaranteed by the on-chain hash. To verify consent, a service recomputes the hash from the original document and checks it against the blockchain record. This pattern is aligned with the ERC-7215 standard for token-bound consent, which proposes a framework for managing consent states attached to NFTs or wallets.

This on-chain proof enables several key functionalities: non-repudiation (the user cannot deny they consented), auditability (regulators can verify compliance), and interoperability (any dApp can query the chain to check consent status). It forms the foundational layer for building compliant Web3 applications that respect user autonomy while providing clear legal evidence of permission.

A user preference dashboard is the interface that puts data control back into the user's hands. It should clearly display the types of data being collected (e.g., wallet address, transaction history, social graph), the purpose for each category, and a simple toggle to grant or revoke consent. This transparency is not just a regulatory requirement under frameworks like GDPR; it builds essential trust. Users are more likely to engage with an application when they understand and can control how their on-chain and off-chain data is used.

The dashboard's state must be persistently stored and easily retrievable. A common pattern is to store consent preferences in a decentralized storage solution like Ceramic Network or IPFS, referenced by a Decentralized Identifier (DID). Alternatively, for simpler implementations or where user anonymity is less critical, encrypted preferences can be stored in a traditional backend database, keyed to a hashed user identifier. The core requirement is that the consent record is non-repudiable and linked to the user's identity.

Here is a basic React component example using a state hook to manage preferences and a mock function to save them. This demonstrates the fundamental UI/UX pattern.

jsxCopy
import { useState } from 'react';

function ConsentDashboard({ userDid }) {
  const [preferences, setPreferences] = useState({
    analytics: true,
    marketing: false,
    shareWithPartners: false
  });

  const handleToggle = (key) => {
    setPreferences(prev => ({ ...prev, [key]: !prev[key] }));
  };

  const savePreferences = async () => {
    // Example: Store on Ceramic using the user's DID
    // await ceramicClient.storeRecord(userDid, { consent: preferences });
    console.log('Preferences saved:', preferences);
  };

  return (
    <div>
      <h2>Data Preferences</h2>
      {Object.entries(preferences).map(([key, value]) => (
        <div key={key}>
          <label>
            <input
              type="checkbox"
              checked={value}
              onChange={() => handleToggle(key)}
            />
            Allow {key} data collection
          </label>
        </div>
      ))}
      <button onClick={savePreferences}>Save Settings</button>
    </div>
  );
}

Integrating this dashboard with a sign-in with Ethereum (SIWE) flow or a wallet connection is crucial. Upon authentication, your application should fetch the user's stored consent object. If no record exists (a new user), present the dashboard with sensible defaults, requiring explicit approval before proceeding—a practice known as granular consent. This ensures compliance is baked into the onboarding sequence, not added as an afterthought.

Finally, respect these preferences throughout your application's logic. Server-side functions and smart contract interactions should check the user's consent state before logging detailed analytics, minting a soulbound token that represents a marketing opt-in, or sharing data with a partner protocol via a cross-chain message. A well-architected consent system treats the dashboard not as a static form, but as the user-controlled configuration layer for their entire interaction with your dApp.