PSCT Entanglement System

Overview

The PSCT (Peril-Specific Catastrophe Token) Entanglement System is a smart contract infrastructure that manages the dual-state nature of PSCT tokens in the Riskify platform. PSCTs can exist in two distinct states:

Idle (Tradable): Fungible tokens that can be freely traded on Uniswap v4
Entangled (Locked): Non-transferable tokens committed to specific building tokens and risk pools

System Architecture

Core Components

PSCT Token Contract (PSCT.sol)
- ERC-20 token with entanglement tracking
- Metadata mappings for token state
- Transfer restrictions for entangled tokens
EntanglementVault (EntanglementVault.sol)
- Manages PSCT entanglement with building tokens and pools
- Only entity allowed to set entanglement flags
- Comprehensive record keeping and event emission
PSCTUniswapHook (PSCTUniswapHook.sol)
- Uniswap v4 hook that prevents entangled token trading
- Validates swaps and liquidity provision
- Ensures compliance with entanglement rules
PSCTWrapper (PSCTWrapper.sol)
- Optional NAV-rebasing wrapper for idle PSCTs
- Enables compliant Uniswap trading
- Provides yield optimization capabilities

Token States

Idle PSCTs

Fungible: All idle PSCTs are interchangeable
Tradable: Can be freely traded on Uniswap v4
Transferable: Normal ERC-20 transfer functionality
Wrappable: Can be wrapped into wPSCT for NAV-rebasing

Entangled PSCTs

Non-transferable: Cannot be transferred or traded
Building-linked: Associated with specific building tokens
Pool-committed: Linked to specific risk pools
Contractually bound: Subject to parametric payout logic

Workflow

1. Token Creation

// Mint new PSCT tokens
psctToken.mint(
    recipient,
    amount,
    perilType,
    coverageAmount,
    triggerThreshold,
    expiryTimestamp
);

2. Entanglement Process

// Entangle PSCT with building token and pool
entanglementVault.entanglePSCT(
    psctTokenId,
    buildingTokenId,
    poolId,
    amount
);

3. Trading Restrictions

Entangled PSCTs cannot be transferred
Uniswap v4 hook prevents entangled token swaps
Only idle PSCTs can be traded or wrapped

4. Disentanglement

// Disentangle PSCT when commitment ends
entanglementVault.disentanglePSCT(psctTokenId);

Key Features

Entanglement Tracking

Metadata Mappings: Track entanglement status per token ID
Building Links: Associate tokens with specific building tokens
Pool Links: Link tokens to risk pool commitments
Timestamp Tracking: Record entanglement timing

Transfer Controls

Automatic Validation: Transfer functions check entanglement status
Hook Integration: Uniswap v4 hooks prevent entangled token trading
Vault Authority: Only EntanglementVault can modify entanglement flags

Compliance Features

Event Emission: Comprehensive event logging for off-chain indexing
Audit Trail: Complete history of entanglement operations
Role-based Access: Granular permissions for different operations

Contract Interfaces

PSCT Token

interface IPSCT {
    function isEntangled(uint256 tokenId) external view returns (bool);
    function getEntanglementInfo(uint256 tokenId) external view returns (
        bool entangled,
        uint256 buildingTokenId,
        uint256 poolId,
        uint256 timestamp
    );
    function setEntangled(uint256 tokenId, uint256 buildingTokenId, uint256 poolId) external;
    function setDisentangled(uint256 tokenId) external;
}

EntanglementVault

interface IEntanglementVault {
    function entanglePSCT(uint256 psctTokenId, uint256 buildingTokenId, uint256 poolId, uint256 amount) external;
    function disentanglePSCT(uint256 psctTokenId) external;
    function getEntanglementRecord(uint256 recordId) external view returns (EntanglementRecord memory);
    function getBuildingTokenEntanglements(uint256 buildingTokenId) external view returns (uint256[] memory);
}

Uniswap Hook

interface IPSCTUniswapHook {
    function beforeSwap(address sender, PoolKey calldata key, SwapParams calldata params, bytes calldata hookData) external returns (bytes4);
    function beforeModifyPosition(address sender, PoolKey calldata key, ModifyPositionParams calldata params, bytes calldata hookData) external returns (bytes4);
    function validatePSCTPoolCreation(PoolKey calldata key) external view returns (bool);
}

Deployment

1. Deploy Core Contracts

forge script script/DeployPSCTSystem.s.sol --rpc-url <RPC_URL> --broadcast

2. Configure Permissions

// Grant vault role to EntanglementVault
psctToken.grantVaultRole(address(entanglementVault));

// Grant operator role to wrapper
entanglementVault.grantOperatorRole(address(wrapper));

3. Deploy Uniswap Hook

// Deploy when Uniswap v4 is available
hook = new PSCTUniswapHook(poolManager, psctToken, entanglementVault);

Usage Examples

Basic Entanglement

// 1. User owns PSCT tokens
uint256 psctBalance = psctToken.balanceOf(user);

// 2. User wants to commit tokens to a building and pool
entanglementVault.entanglePSCT(psctTokenId, buildingTokenId, poolId, amount);

// 3. Tokens are now entangled and non-transferable
bool isEntangled = psctToken.isEntangled(psctTokenId); // true

Trading Idle Tokens

// 1. User has idle PSCT tokens
uint256 idleBalance = psctToken.balanceOf(user);

// 2. User can trade on Uniswap v4 (hook validates)
// 3. User can wrap tokens for NAV-rebasing
uint256 wrapperAmount = wrapper.wrap(idleBalance);

Disentanglement

// 1. Commitment period ends
// 2. Disentangle tokens
entanglementVault.disentanglePSCT(psctTokenId);

// 3. Tokens are now idle and transferable
bool isEntangled = psctToken.isEntangled(psctTokenId); // false

Security Considerations

Access Control

Vault Role: Only EntanglementVault can modify entanglement flags
Admin Role: Limited administrative functions
Operator Role: Automated operations (wrappers, pools)

Transfer Restrictions

Entangled Check: All transfers validate entanglement status
Hook Validation: Uniswap v4 hooks prevent entangled token trading
Wrapper Protection: Wrapper checks entanglement before wrapping

Audit Trail

Event Logging: All entanglement operations emit events
Record Keeping: Complete history of entanglement records
Off-chain Indexing: Events enable comprehensive tracking

Integration Points

Risk Pools

ConcreteRiskPool: Can entangle PSCTs when users commit capital
CrossPool: Can entangle PSCTs for cross-pool commitments
PassivePools: Can entangle PSCTs for passive positions

Building Tokens

BuildingToken: ERC-721 tokens representing properties
Risk Assessment: Building tokens provide risk data for PSCTs
Parametric Triggers: Building tokens contain trigger parameters

Uniswap v4

Hook Integration: Prevents entangled token trading
Pool Validation: Ensures only valid PSCT pools are created
Compliance: Maintains regulatory compliance for trading

Future Enhancements

Advanced Features

Partial Entanglement: Allow partial token entanglement
Time-locked Entanglement: Automatic disentanglement after time periods
Multi-pool Entanglement: Single PSCT linked to multiple pools

Optimization

Gas Efficiency: Optimize entanglement operations
Batch Operations: Support for batch entanglement/disentanglement
Indexing: Enhanced off-chain indexing capabilities

Compliance

Regulatory Reporting: Enhanced reporting capabilities
Audit Integration: Integration with external audit systems
KYC/AML: Integration with compliance systems

Testing

Unit Tests

forge test --match-contract PSCT
forge test --match-contract EntanglementVault
forge test --match-contract PSCTUniswapHook
forge test --match-contract PSCTWrapper

Integration Tests

forge test --match-contract PSCTSystemIntegration

Gas Optimization

forge test --gas-report

Conclusion

The PSCT Entanglement System provides a robust foundation for managing the dual-state nature of catastrophe risk tokens. By ensuring that entangled tokens remain locked to their commitments while allowing idle tokens to be freely traded, the system maintains both contractual compliance and market liquidity.

The modular design allows for easy integration with existing risk pools, building tokens, and trading infrastructure, while the comprehensive event system enables full transparency and auditability of all operations.