Developer Access

Restricted internal notes and quick links for the current PB contract surface.

Restricted Entry

Enter the fixed developer password to reveal this page.

Current Contract Surface

This page maps the live mainnet contracts in the order they are easiest to reason about: presale first, core operating contracts second, and helper tooling last.

Presale

Where allocation starts and how those presale positions get converted into live protocol state.

PresaleIOU LaunchConverter

Main Operating

The contracts users actually sit inside after launch: buy flow, locks, trackers, recovery, and inheritance.

Vault PB PBc PBt PBr PBi

Helper

Support tooling around the core flow, mainly pricing and read-side coordination.

PulseXInterface

Architecture Snapshot

Buy Path

All canonical buys route through Vault.buyPBDirect(). PB blocks direct pair-to-user delivery so the Vault stays in the middle of the protocol path.

Position Stack

Liquid PB is transferable, PBc is Vault-mediated only, and each position is tracked by a non-transferable PBt NFT.

Launch Flow

Presale blocks live in PresaleIOU, then the one-time LaunchConverter batches those blocks into live Vault allocations at launch.

Succession

Recovery and inheritance are password-based dual-party flows backed by non-transferable PBr and PBi badges.

Unlock Engine

Unlocks are geometric, trigger-price based, and permissionless through executeUnlock() when price reaches the next threshold.

VLock

VLock routes voluntary PB deposits into PBc + PBt and can claim a one-time share of harvested LP fees if the position meets the threshold.

Important Live Entry Points

PresaleIOU.buyBlock() LaunchConverter.executeConversionBatch() Vault.buyPBDirect() Vault.executeUnlock() Vault.voluntaryLock() Vault.claimLPFeesFor() Vault.activateRecovery() Vault.activateInheritance()

All Functions / Getters / Helpers / Events

1. Presale

PresaleIOU.sol • Presale IOU NFT

Non-transferable presale NFT system for 555 blocks, founder reservations, treasury-controlled close, and batched FOAD distribution.

External / public

  • constructor(address usdl, address presaleTreasury, address[] memory founderRecipients, uint256[] memory founderBlocks)
  • setLaunchConverter(address launchConverter)
  • getEntryPriceAtBlock(uint256 blockNum)
  • getPBPerBlock(uint256 blockNum)
  • isFounderBlock(uint256 blockNum)
  • closeSale()
  • buyBlock(uint256 numBlocks)
  • distributeUnsoldToFOAD(uint256 batchSize)
  • markConverted(uint256 blockNum)
  • getPresaleData()
  • supportsInterface(bytes4 interfaceId)
  • balanceOf(address owner)
  • ownerOf(uint256 tokenId)
  • approve(address, uint256) (override, reverts)
  • getApproved(uint256 tokenId)
  • setApprovalForAll(address, bool) (override, reverts)
  • isApprovedForAll(address owner, address operator)
  • transferFrom(address, address, uint256) (override, reverts)
  • safeTransferFrom(address, address, uint256) (override, reverts)
  • safeTransferFrom(address, address, uint256, bytes memory) (override, reverts)
  • tokenURI(uint256 tokenId)

Getters / state surface

  • TOTAL_BLOCKS, FREE_BLOCKS, MAX_NFT_SUPPLY, PB_PER_BLOCK, MAX_BLOCKS_PER_ADDRESS, USDL_PER_BLOCK
  • name, symbol, IOU_IMAGE_URI
  • USDL, PRESALE_TREASURY, LAUNCH_CONVERTER
  • blocksPurchased, nextAvailableBlock, totalRaised, isFounder, distributionNextBlock, distributionFOADIndex, saleClosed

Events

  • Transfer(address indexed from, address indexed to, uint256 indexed tokenId)
  • Approval(address indexed owner, address indexed approved, uint256 indexed tokenId)
  • ApprovalForAll(address indexed owner, address indexed operator, bool approved)

Internal helpers

  • _mint(address to, uint256 tokenId)
  • _transfer(address from, address to, uint256 tokenId)
  • _isApprovedOrOwner(address spender, uint256 tokenId)
  • _checkOnERC721Received(address from, address to, uint256 tokenId, bytes memory data)
  • _burn(uint256 tokenId)
LaunchConverter.sol • One-time launch migration

Batched one-time presale conversion into live Vault allocations and PBt creation.

External / public

  • constructor(address _presaleIOU, address _vault)
  • executeConversionBatch()
  • setBatchSize(uint256 _batchSize)
  • getProgress()
  • getStatus()
  • getBlocksRemaining()
  • seedLP(uint256 a, uint256 b, uint256 c, uint256 d)

Getters / state surface

  • PRESALE_IOU, VAULT, deployer
  • TOTAL_BLOCKS, batchSize, nextBlockToConvert, currentBatch, totalBatches, blocksConverted
  • conversionStarted, conversionFinalized

Events

  • ConversionBatchExecuted(uint256 batchNumber, uint256 totalBatches, uint256 fromBlock, uint256 toBlock, uint256 totalConverted, bool finalized)
  • BlockConverted(uint256 indexed blockNum, address indexed buyer, uint256 pbAmount, uint256 entryPrice)
  • ConversionFinalized(uint256 timestamp, uint256 totalConverted)

Internal helpers

  • _convertBlock(IPresaleIOU.Block memory block_data)

2. Main Operating

Vault.sol • Constitutional core

Main immutable protocol core: deployment locking, LP seeding, presale allocation, live buys, unlocks, succession, and VLock / fee harvesting.

External / public deployment + init

  • constructor(address _pbToken, address _pbcToken, address _pbtToken, address _pbrToken, address _pbiToken, address _usdlToken, address _priceFeed, address _pulsexRouter)
  • receive()
  • lockImmutableReferences(address _launchConverter, address _pulsexPair)
  • seedInitialLP(uint256 usdlAmount, uint256 minPB, uint256 minUSDL, uint256 deadline)

External / public protocol entrypoints

  • allocatePresaleUser(address user, uint256 pbAmount, uint256 entryPrice)
  • executeUnlock(uint256 pbtId)
  • setRecoveryAddress(uint256 pbtId, address recoveryAddr, bytes32 passwordHash, string calldata message)
  • activateRecovery(uint256 pbtId, string calldata password)
  • setInheritanceAddress(uint256 pbtId, address inheritanceAddr, bytes32 passwordHash, string calldata message)
  • activateInheritance(uint256 pbtId, string calldata password)
  • voluntaryLock(uint256 pbAmount)
  • harvestLPRewards()
  • claimLPFeesFor(uint256 pbtId)
  • buyPBDirect(uint256 usdlAmount, uint256 minPBOut, address recipient, uint256[] calldata unlockIds)

External / public getters / quotes

  • computeNextTriggerPrice(uint256 buyPrice, uint256 unlockIndex)
  • totalOutstandingPBc()
  • totalOutstandingPB()
  • getPBtData(uint256 pbtId)
  • getUserPBtIds(address user)
  • getRecoveryData(uint256 pbtId)
  • getInheritanceData(uint256 pbtId)
  • getCurrentLPProceeds()
  • getVlockParameters()
  • getLPTokenBalance()
  • getPBQuote(uint256 usdlAmount)
  • getPositionUnlockStatus(uint256 pbtId)
  • getActivePositionCount()
  • getUserTotalValue(address user)

Internal helpers

  • _executeUnlock(uint256 pbtId, bool skipPriceCheck)
  • _movePBtOwnership(uint256 pbtId, address oldHolder, address newHolder)
  • _computeSplit(uint256 pbAmount)
  • _addVaultPB(uint256 amount)
  • _addVaultPBc(uint256 amount)
  • _deductVaultPB(uint256 amount)
  • _deductVaultPBc(uint256 amount)
  • _transferPBFromVault(address recipient, uint256 amount)
  • _transferPBcFromVault(address recipient, uint256 amount)
  • _mintPBt(address recipient, uint256 pbAmount, uint256 lockedPBc, uint256 buyPrice)
  • _sellPBtoAMM(uint256 pbAmount)
  • _checkPhaseTransition()
  • _getAmountOut(uint256 amountIn, uint256 reserveIn, uint256 reserveOut)
  • _computeUSDLForPrice(uint256 reservePB, uint256 reserveUSDL, uint256 targetPrice)
  • _sequentialNettingScan(...)
  • _settleNettedPosition(NettingScanResult memory r)
  • _directLPContribution(uint256 usdlForLP, uint256 reservePB, uint256 reserveUSDL)
  • _getPairReserves()
  • _harvestLPRewards()
  • _sqrt(uint256 x)
  • _claimLPFeesForInternal(uint256 pbtId)
  • _executeBuyOnPulseX(uint256 usdlAmount, uint256 minPBOut)

Events

  • PresaleAllocated(address indexed user, uint256 indexed pbtId, uint256 pbAmount, uint256 buyPrice)
  • UnlockTriggered(uint256 indexed pbtId, uint256 unlockIndex, uint256 pbUnlocked, uint256 usdlProceeds, address payoutAddress, uint256 newTriggerPrice, uint256 remainingPBcLocked)
  • PBtBurned(uint256 indexed pbtId, uint256 remainingDust)
  • PhaseTransitioned(bool wasDistribution, uint256 vaultPBBalance, uint256 totalOutstandingPBc)
  • RecoveryAddressSet(uint256 indexed pbtId, address indexed recoveryAddress)
  • RecoveryActivated(uint256 indexed pbtId, address indexed recoveryAddress)
  • InheritanceAddressSet(uint256 indexed pbtId, address indexed inheritanceAddress)
  • InheritanceActivated(uint256 indexed pbtId, address indexed inheritanceAddress)
  • LPContributed(uint256 pbAmount, uint256 usdlAmount)
  • FinalLPContribution(uint256 pbAmount, uint256 usdlAmount)
  • ImmutableReferencesLocked(address indexed launchConverter, address indexed pulsexPair)
  • UnlockNetted(uint256 indexed pbtId, uint256 unlockIndex, uint256 pbcSettled, uint256 usdlPaid, address payoutAddress, uint256 settlementPrice, uint256 newTriggerPrice, uint256 remainingPBcLocked)
  • BuyWithNetting(address indexed buyer, address indexed recipient, uint256 indexed pbtId, uint256 usdlIn, uint256 totalPBOut, uint256 nettedPB, uint256 ammPB, uint256 lpPB, uint256 lpUSDL, uint256 unlocksNetted)
  • InitialLPSeeded(uint256 usdlAmount, uint256 pbAmount, uint256 liquidity)
  • LPRewardsHarvested(uint256 usdlAmount, uint256 pbAmount)
  • VLockExecuted(address indexed user, uint256 indexed pbtId, uint256 pbAmount, uint256 usdlBonusPaid, uint256 pbBonusPaid)
  • VLockBonusPaid(address indexed user, uint256 usdlAmount, uint256 pbAmount)

Key autogenerated getters / state surface

  • vaultPBBalance, vaultPBcBalance, vaultLPTokenBalance, totalUSDLDistributed, buyCount
  • isDistributionPhase, phaseTransitionExecuted, immutableReferencesLocked, initialLPSeeded
  • pbtIdCounter, activePositionCount, pbtRegistry, userPBtIds
  • recoveryRegistry, inheritanceRegistry, isVLockPosition, vlockBonusClaimed
  • accumulatedFeesUSDL, accumulatedFeesPB, lastKPerLP
PB.sol • Liquid token

Transferable liquid token with canonical buy-path protection at the pair boundary.

External / public

  • constructor()
  • lockVault(address _vault)
  • setPairAddress(address _pair)
  • transfer(address to, uint256 amount)
  • transferFrom(address from, address to, uint256 amount)
  • approve(address spender, uint256 amount)

Getters / state surface

  • name, symbol, decimals, totalSupply
  • logoURI, website, description
  • DEPLOYER, VAULT, vaultLocked, PAIR
  • balanceOf, allowance

Events

  • Transfer(address indexed from, address indexed to, uint256 value)
  • Approval(address indexed owner, address indexed spender, uint256 value)

Protocol rule

  • Direct pair-to-user routing reverts unless the Vault is the recipient.
PBc.sol • Locked claim token

Non-transferable ERC20 claim token. Vault-mediated only.

External / public

  • constructor()
  • lockVault(address _vault)
  • transfer(address to, uint256 amount)
  • transferFrom(address from, address to, uint256 amount)
  • approve(address spender, uint256 amount)

Getters / state surface

  • name, symbol, decimals, totalSupply
  • logoURI, website, description
  • DEPLOYER, VAULT, vaultLocked
  • balanceOf, allowance

Events

  • Transfer(address indexed from, address indexed to, uint256 value)
  • Approval(address indexed owner, address indexed spender, uint256 value)
PBt.sol • Position tracker NFT

Non-transferable ERC721 tracker for each position, with unlock history and succession state.

External / public

  • constructor()
  • lockVault(address _vault)
  • mint(address to, uint256 tokenId, uint256 buyPrice, uint256 allocatedPB, uint256 allocatedPBc)
  • recordUnlock(uint256 tokenId, uint256 unlockedAmount, uint256 unlockPrice)
  • recordDust(uint256 tokenId, uint256 dustAmount)
  • burnTracker(uint256 tokenId)
  • setRecoveryAddress(uint256 tokenId, address recoveryAddress)
  • setInheritanceAddress(uint256 tokenId, address inheritanceAddress)
  • activateRecovery(uint256 tokenId)
  • activateInheritance(uint256 tokenId)
  • getMetadata(uint256 tokenId)
  • getUnlockHistory(uint256 tokenId)
  • getUserTokenIds(address user)
  • getUserTokenCount(address user)
  • exists(uint256 tokenId)
  • burn(uint256 tokenId) (override, reverts)
  • transferFrom(address, address, uint256) (override, reverts)
  • safeTransferFrom(address, address, uint256) (override, reverts)
  • safeTransferFrom(address, address, uint256, bytes memory) (override, reverts)
  • approve(address, uint256) (override, reverts)
  • setApprovalForAll(address, bool) (override, reverts)
  • tokenURI(uint256 tokenId)

Getters / state surface

  • DEPLOYER, VAULT, vaultLocked
  • pbtMetadata, userTokenIds

Events

  • PBtMinted(uint256 indexed tokenId, address indexed owner, uint256 allocatedPB, uint256 allocatedPBc, uint256 buyPrice)
  • UnlockRecorded(uint256 indexed tokenId, uint256 indexed unlockIndex, uint256 unlockedAmount, uint256 unlockPrice)
  • DustRecorded(uint256 indexed tokenId, uint256 dustAmount)
  • PBtBurned(uint256 indexed tokenId, uint256 finalDust)
  • RecoveryAddressUpdated(uint256 indexed tokenId, address indexed recoveryAddress)
  • InheritanceAddressUpdated(uint256 indexed tokenId, address indexed inheritanceAddress)
  • RecoveryActivated(uint256 indexed tokenId, address indexed newOwner)
  • InheritanceActivated(uint256 indexed tokenId, address indexed newOwner)

Internal helpers

  • _removeTokenFromUser(address user, uint256 tokenId)
  • _exists(uint256 tokenId)
  • _toString(uint256 value)
PBr.sol • Recovery badge

Non-transferable ERC1155 recovery badge for one-time recovery activation.

External / public

  • constructor()
  • lockVault(address _vault)
  • mint(address recipient, uint256 pbtId, string calldata message)
  • burn(address holder, uint256 pbtId)
  • safeTransferFrom(...) (override, reverts)
  • safeBatchTransferFrom(...) (override, reverts)
  • uri(uint256 tokenId)
  • hasRecoveryBadge(address holder, uint256 pbtId)
  • getBadgeIds(address holder)

Getters / state surface

  • DEPLOYER, VAULT, vaultLocked
  • userBadgeIds, badgeMessage

Events

  • BadgeMinted(address indexed recipient, uint256 indexed pbtId)
  • BadgeBurned(address indexed holder, uint256 indexed pbtId)

Internal helpers

  • _toString(uint256 value)
PBi.sol • Inheritance badge

Non-transferable ERC1155 inheritance badge with precedence over recovery once activated.

External / public

  • constructor()
  • lockVault(address _vault)
  • mint(address recipient, uint256 pbtId, string calldata message)
  • burn(address holder, uint256 pbtId)
  • safeTransferFrom(...) (override, reverts)
  • safeBatchTransferFrom(...) (override, reverts)
  • uri(uint256 tokenId)
  • hasInheritanceBadge(address holder, uint256 pbtId)
  • getBadgeIds(address holder)
  • inheritanceTakesPrecedence()

Getters / state surface

  • DEPLOYER, VAULT, vaultLocked
  • userBadgeIds, badgeMessage

Events

  • BadgeMinted(address indexed recipient, uint256 indexed pbtId)
  • BadgeBurned(address indexed holder, uint256 indexed pbtId)

Internal helpers

  • _toString(uint256 value)

3. Helper

PulseXInterface.sol • Price helper

Read-oriented price wrapper and updateable cumulative-price helper for the PB/USDL pair.

External / public

  • constructor(address pbUsdlPair, address pbToken, address usdlToken, address vault)
  • setVault(address _vault)
  • getCurrentPrice()
  • updatePrice()
  • getPriceHistory(uint256 timestamp)

Getters / state surface

  • DEPLOYER, PB_USDL_PAIR, PB_TOKEN, USDL_TOKEN
  • VAULT, vaultLocked
  • PERIOD, MIN_UPDATE_INTERVAL, FIXED_PRICE
  • price0CumulativeLast, price1CumulativeLast, blockTimestampLast, lastUpdateTime

Events

  • PriceUpdated(uint256 price, uint256 timestamp)
  • VaultLocked(address indexed vault, uint256 timestamp)

Internal helpers

  • _updateCumulativePrices()
  • _getCurrentCumulatives()
  • _getSpotPrice()