Consent

Overview

The Consent contract manages individual user consents linked to agreements in the Permission Protocol. It enables users (data suppliers) to create, revoke, and extend consent records through cryptographically signed actions.

Contract Details

Property	Value
Solidity Version	^0.8.28
License	MIT
Inheritance	EIP712 (OpenZeppelin)
Dependencies	IAgreement interface

---

Purpose

The Consent contract provides a complete lifecycle management system for user consents:

• Create Consent: Users grant consent to an existing agreement

• Revoke Consent: Users can revoke their consent (based on agreement's revocation rules)

• Extend Validity: Users can extend the expiration of their consent

• Batch Operations: Create multiple consent records in a single transaction

All operations require EIP-712 signatures from the data supplier, enabling gasless (meta-transaction) patterns.

---

Data Structures

ConsentRecord

The primary structure for storing consent details.

struct ConsentRecord {
    uint256 agreementId;     // Reference to the parent Agreement ID
    IAgreement agreement;    // Reference to the Agreement contract
    uint64 createdAt;        // Timestamp when consent was created
    address supplier;        // Data supplier (user giving consent)
    uint64 validityEnd;      // Unix timestamp when consent expires (0 = never)
    uint16 nonce;            // Replay protection for modifications
    bool disclosed;          // Whether data is publicly disclosed
    string dataRef;          // Reference to the data (IPFS/URL)
    string revocationRef;    // Reason/reference if revoked (empty = active)
}

Field	Type	Description
agreementId	uint256	ID of the associated Agreement
agreement	IAgreement	Reference to the Agreement contract
createdAt	uint64	Timestamp when consent was created (for revoke checks)
supplier	address	Address of the data supplier
validityEnd	uint64	Expiration timestamp (0 = never expires)
nonce	uint16	Counter for replay protection on updates
disclosed	bool	If true, data is publicly accessible
dataRef	string	IPFS hash or URL pointing to the data
revocationRef	string	Revocation reason (empty if not revoked)

ConsentRecordInput

Input structure for batch consent record creation.

struct ConsentRecordInput {
    uint256 agreementId;     // The associated agreement ID
    IAgreement agreement;    // The agreement contract
    address supplier;        // The supplier address (signer)
    uint64 validityEnd;      // The validity expiration timestamp
    bool disclosed;          // Whether the data is disclosed
    string dataRef;          // Reference to the data
    bytes32 r;               // The 'r' component of the signature
    bytes32 vs;              // The 'vs' component of the signature
}

---

State Variables

Variable	Type	Visibility	Description
consentRecordCounter	uint256	public	Counter for unique consent IDs (starts at 1)
usedDigests	mapping(bytes32 => uint256)	public	Tracks used EIP-712 digests
consentRecords	mapping(uint256 => ConsentRecord)	public	Storage of consent records

---

Functions

Constructor

constructor(
    string memory name,
    string memory version
)

Initializes the contract with EIP-712 domain parameters.

Parameters:

Name	Type	Description
name	string	Domain name (e.g., "Consent")
version	string	Domain version (e.g., "1")

---

createConsentRecord

function createConsentRecord(
    uint256 agreementId,
    IAgreement agreement,
    address supplier,
    uint64 validityEnd,
    bool disclosed,
    string calldata dataRef,
    bytes32 r,
    bytes32 vs
) external returns (uint256 consentRecordId)

Creates a new consent record with supplier signature verification.

Parameters:

Name	Type	Description
agreementId	uint256	ID of the parent agreement
agreement	IAgreement	The Agreement contract reference
supplier	address	Address of the data supplier (signer)
validityEnd	uint64	Expiration timestamp (0 = never expires)
disclosed	bool	Public disclosure flag
dataRef	string	Reference to the data
r	bytes32	ECDSA signature component r
vs	bytes32	ECDSA compact signature component (v + s)

Returns:

Name	Type	Description
consentRecordId	uint256	The unique ID of the created consent

Requirements:

• Referenced agreement must exist

• Signature must be from the supplier

• Consent with same parameters cannot already exist

Effects:

• Sets createdAt to the current block timestamp

Emits: ConsentRecordCreated

---

batchCreateConsentRecords

function batchCreateConsentRecords(
    ConsentRecordInput[] calldata inputs
) external returns (uint256[] memory consentRecordIds)

Creates multiple consent records in a single transaction.

Parameters:

Name	Type	Description
inputs	ConsentRecordInput[]	Array of consent record inputs

Returns:

Name	Type	Description
consentRecordIds	uint256[]	Array of created consent record IDs

Requirements:

• Input array must not be empty

Emits: ConsentRecordCreated for each consent record

---

revokeConsentRecord

function revokeConsentRecord(
    uint256 consentRecordId,
    string calldata revocationRef,
    uint16 nonce,
    bytes32 r,
    bytes32 vs
) external

Revokes an existing consent record.

Parameters:

Name	Type	Description
consentRecordId	uint256	ID of the consent to revoke
revocationRef	string	Reason or reference for revocation
nonce	uint16	Current nonce of the consent record
r	bytes32	ECDSA signature component r
vs	bytes32	ECDSA compact signature component

Requirements:

• Agreement must allow revocation (agreement.isRevokable() returns true)

• Nonce must match current consent record nonce

• Signature must be from the original supplier

• Revocation reference cannot be empty

• Consent must not already be revoked

Emits: ConsentRecordRevoked

Effects:

• Sets revocationRef to the provided value

• Increments nonce by 1

---

extendValidity

function extendValidity(
    uint256 consentRecordId,
    uint64 newValidityEnd,
    uint16 nonce,
    bytes32 r,
    bytes32 vs
) external

Extends the validity period of a consent record.

Parameters:

Name	Type	Description
consentRecordId	uint256	ID of the consent to extend
newValidityEnd	uint64	New expiration timestamp
nonce	uint16	Current nonce of the consent record
r	bytes32	ECDSA signature component r
vs	bytes32	ECDSA compact signature component

Requirements:

• Nonce must match current consent record nonce

• New validity must be greater than current validity

• Current validity cannot be 0 (consents with no expiry cannot be extended)

• Consent must not be revoked

• Signature must be from the original supplier

Emits: ConsentRecordValidityExtended

Effects:

• Updates validityEnd to new value

• Increments nonce by 1

---

getConsentRecord

function getConsentRecord(uint256 consentRecordId) public view returns (ConsentRecord memory)

Retrieves a consent record by ID.

Parameters:

Name	Type	Description
consentRecordId	uint256	The consent record identifier

Returns: ConsentRecord struct

Reverts: ConsentRecordNotFound if record doesn't exist

---

Hash Functions

hashConsentRecord

function hashConsentRecord(
    uint256 agreementId,
    address agreement,
    address supplier,
    uint64 validityEnd,
    bool disclosed,
    string calldata dataRef
) public pure returns (bytes32)

Computes the EIP-712 struct hash for consent record creation.

getTypedDataHash

function getTypedDataHash(
    uint256 agreementId,
    address agreement,
    address supplier,
    uint64 validityEnd,
    bool disclosed,
    string calldata dataRef
) public view returns (bytes32)

Returns the complete EIP-712 typed data hash for signing.

---

Events

ConsentRecordCreated

event ConsentRecordCreated(
    uint256 consentRecordId,
    uint256 indexed agreementId,
    IAgreement indexed agreement,
    address indexed supplier,
    uint64 validityEnd,
    bool disclosed,
    string dataRef,
    bytes32 r,
    bytes32 vs
);

Emitted when a new consent record is created. Includes the agreement contract reference and signature components for verification.

ConsentRecordRevoked

event ConsentRecordRevoked(
    uint256 indexed consentRecordId,
    string revocationRef,
    uint16 nonce
);

Emitted when a consent record is revoked.

ConsentRecordValidityExtended

event ConsentRecordValidityExtended(
    uint256 indexed consentRecordId,
    uint64 newValidityEnd,
    uint16 nonce
);

Emitted when consent validity is extended.

---

Errors

Error	Description
ConsentRecordAlreadyExists(uint256)	A consent with the same parameters already exists
InvalidSignature()	The provided signature is invalid
InvalidRevocationRef()	The revocation reference is empty
InvalidNonce()	The provided nonce doesn't match
InvalidNewValidityEnd()	New validity is not greater than current
ConsentRecordNotFound()	The requested consent ID does not exist
EmptyBatchInput()	The batch input array is empty
ConsentRecordAlreadyRevoked()	The consent record has already been revoked
RevokeFailed()	Revocation not allowed by agreement's rules

---

EIP-712 Type Definitions

The contract uses multiple EIP-712 types for different operations:

ConsentRecord (for creation)

const types = {
  ConsentRecord: [
    { name: "agreementId", type: "uint256" },
    { name: "agreement", type: "address" },
    { name: "supplier", type: "address" },
    { name: "validityEnd", type: "uint64" },
    { name: "disclosed", type: "bool" },
    { name: "dataRef", type: "string" },
  ],
};

RevokeRecord (for revocation)

const types = {
  RevokeRecord: [
    { name: "consentRecordId", type: "uint256" },
    { name: "revocationRef", type: "string" },
    { name: "nonce", type: "uint16" },
  ],
};

ExtendValidityRecord (for extension)

const types = {
  ExtendValidityRecord: [
    { name: "consentRecordId", type: "uint256" },
    { name: "newValidityEnd", type: "uint64" },
    { name: "nonce", type: "uint16" },
  ],
};

---

Usage Examples

Creating a Consent Record (TypeScript/Viem)

import { parseSignature, signatureToCompactSignature } from "viem";

// Prepare consent data
const agreementContract = "0x..."; // Agreement contract address
const agreementId = 1n;
const supplier = supplierWallet.account.address;
const dataRef = "ipfs://QmXxx...";
const validityEnd = BigInt(Math.floor(Date.now() / 1000) + 30 * 24 * 3600); // 30 days
const disclosed = true;

// Create EIP-712 typed data
const typedData = {
  domain: {
    name: "Consent",
    version: "1",
    chainId: 1n,
    verifyingContract: consentContractAddress,
  },
  types: {
    ConsentRecord: [
      { name: "agreementId", type: "uint256" },
      { name: "agreement", type: "address" },
      { name: "supplier", type: "address" },
      { name: "validityEnd", type: "uint64" },
      { name: "disclosed", type: "bool" },
      { name: "dataRef", type: "string" },
    ],
  },
  primaryType: "ConsentRecord",
  message: {
    agreementId,
    agreement: agreementContract,
    supplier,
    validityEnd,
    disclosed,
    dataRef,
  },
};

// Sign with supplier wallet
const signature = await supplierWallet.signTypedData(typedData);
const parsedSig = parseSignature(signature);
const compactSig = signatureToCompactSignature(parsedSig);

// Create consent record on-chain
const consentId = await consentContract.write.createConsentRecord([
  agreementId,
  agreementContract,
  supplier,
  validityEnd,
  disclosed,
  dataRef,
  compactSig.r,
  compactSig.yParityAndS,
]);

Batch Creating Consent Records

// Prepare multiple consent record inputs
const consentInputs = [
  {
    agreementId: 1n,
    agreement: agreementContractAddress,
    supplier: supplier1Address,
    validityEnd: validityEnd1,
    disclosed: true,
    dataRef: "ipfs://QmAbc...",
    r: compactSig1.r,
    vs: compactSig1.yParityAndS,
  },
  {
    agreementId: 2n,
    agreement: agreementContractAddress,
    supplier: supplier2Address,
    validityEnd: validityEnd2,
    disclosed: false,
    dataRef: "ipfs://QmDef...",
    r: compactSig2.r,
    vs: compactSig2.yParityAndS,
  },
];

// Create all consent records in one transaction
const consentIds = await consentContract.write.batchCreateConsentRecords([consentInputs]);

Revoking a Consent Record

const consentRecordId = 1n;
const revocationRef = "User requested data deletion";
const nonce = 0; // Current nonce from getConsentRecord

const revokeTypedData = {
  domain: {
    name: "Consent",
    version: "1",
    chainId: 1n,
    verifyingContract: consentContractAddress,
  },
  types: {
    RevokeRecord: [
      { name: "consentRecordId", type: "uint256" },
      { name: "revocationRef", type: "string" },
      { name: "nonce", type: "uint16" },
    ],
  },
  primaryType: "RevokeRecord",
  message: {
    consentRecordId,
    revocationRef,
    nonce,
  },
};

const signature = await supplierWallet.signTypedData(revokeTypedData);
const parsedSig = parseSignature(signature);
const compactSig = signatureToCompactSignature(parsedSig);

// Note: This will fail if the agreement doesn't allow revocation
await consentContract.write.revokeConsentRecord([
  consentRecordId,
  revocationRef,
  nonce,
  compactSig.r,
  compactSig.yParityAndS,
]);

Extending Validity

const consentRecordId = 1n;
const newValidityEnd = BigInt(Math.floor(Date.now() / 1000) + 60 * 24 * 3600); // 60 days
const nonce = 0; // Current nonce

const extendTypedData = {
  domain: {
    name: "Consent",
    version: "1",
    chainId: 1n,
    verifyingContract: consentContractAddress,
  },
  types: {
    ExtendValidityRecord: [
      { name: "consentRecordId", type: "uint256" },
      { name: "newValidityEnd", type: "uint64" },
      { name: "nonce", type: "uint16" },
    ],
  },
  primaryType: "ExtendValidityRecord",
  message: {
    consentRecordId,
    newValidityEnd,
    nonce,
  },
};

const signature = await supplierWallet.signTypedData(extendTypedData);
const parsedSig = parseSignature(signature);
const compactSig = signatureToCompactSignature(parsedSig);

await consentContract.write.extendValidity([
  consentRecordId,
  newValidityEnd,
  nonce,
  compactSig.r,
  compactSig.yParityAndS,
]);

Checking Consent Status

const record = await consentContract.read.getConsentRecord([1n]);

// Check if revoked
const isRevoked = record.revocationRef !== "";

// Check if expired (validityEnd of 0 means never expires)
const now = BigInt(Math.floor(Date.now() / 1000));
const isExpired = record.validityEnd > 0n && now > record.validityEnd;

// Check if active
const isActive = !isRevoked && !isExpired;

// Access consent information
const agreementAddress = record.agreement;
const agreementId = record.agreementId;
const createdAt = record.createdAt;

Checking if Revocation is Allowed

// Before attempting to revoke, check if the agreement allows it
const record = await consentContract.read.getConsentRecord([consentRecordId]);
const canRevoke = await agreementContract.read.isRevokable([
  record.agreementId,
  record.createdAt,
]);

if (!canRevoke) {
  // Check the agreement's revokeEligibility to understand why
  const agreementData = await agreementContract.read.getAgreementData([record.agreementId]);
  
  if (agreementData.revokeEligibility === 0) { // UnRevokable
    console.log("This consent cannot be revoked");
  } else if (agreementData.revokeEligibility === 2) { // RevokableAfterGracePeriod
    const gracePeriodEnd = record.createdAt + agreementData.revokeGracePeriodSeconds;
    console.log(`Revocation allowed after: ${new Date(Number(gracePeriodEnd) * 1000)}`);
  }
}

---

Consent Lifecycle

┌─────────────┐
│   Created   │ ──── nonce: 0, createdAt: block.timestamp
└──────┬──────┘
       │
       ▼
┌─────────────┐     ┌─────────────┐
│   Active    │◄────│  Extended   │ ──── nonce: n+1
└──────┬──────┘     └─────────────┘
       │
       ▼ (if agreement allows)
┌─────────────┐
│   Revoked   │ ──── nonce: n+1 (permanent)
└─────────────┘

Note: Unlike previous versions, revocation is now permanent. Once a consent is revoked, it cannot be restored (undoRevocation has been removed).

---

Revocation Rules

The ability to revoke a consent record depends on the parent agreement's revokeEligibility setting:

RevokeEligibility	Can Revoke?
UnRevokable (0)	Never - revokeConsentRecord will always fail
InstantlyRevokable (1)	Always - can revoke immediately after creation
RevokableAfterGracePeriod (2)	Only after createdAt + revokeGracePeriodSeconds

The Consent contract calls agreement.isRevokable(agreementId, createdAt) to verify revocation eligibility before allowing the revoke operation.

---

Security Considerations

1. Compact Signatures: Uses EIP-2098 compact signatures (r, vs) for gas efficiency

2. Nonce Protection: Each modification increments the nonce, preventing replay attacks

3. Supplier Authorization: Only the original supplier can modify their consent

4. Agreement Validation: Consent can only be created for existing agreements (verified by calling getAgreementData)

5. Revocation Control: Revocation eligibility is enforced by the parent Agreement contract

6. Digest Tracking: Prevents duplicate consent records with identical parameters

7. Flexible Agreement Reference: Each consent stores a reference to its Agreement contract, allowing consents to reference agreements from different Agreement contract deployments

8. Timestamp Recording: createdAt is recorded for grace period calculations

---

Related Contracts

• Agreement: Parent contract that defines consent terms and revocation rules

• IAgreement: Interface for Agreement contract

• DIDRegistry: Identity management for suppliers

---

Deployment

The contract is deployed using Hardhat Ignition:

// ignition/modules/Consent.ts
import { buildModule } from "@nomicfoundation/hardhat-ignition/modules";
import Agreement from "./Agreement.js";

const DOMAIN_NAME = "Consent";
const DOMAIN_VERSION = "1";

export default buildModule("ConsentModule", (m) => {
  const { agreement } = m.useModule(Agreement);
  const consent = m.contract("Consent", [DOMAIN_NAME, DOMAIN_VERSION], { after: [agreement] });

  return { consent };
});