Detailed Instructions

Begin by creating a master inventory of all illiquid asset contracts and vesting schedules. This includes token vesting contracts (e.g., Team, Advisor, Investor allocations), SAFE/SAFT agreements, and private equity holdings. For on-chain assets, you must identify the contract address, ABI (Application Binary Interface), and the specific wallet addresses holding the assets. For off-chain assets, compile all legal documents and spreadsheet-based schedules.

• Sub-step 1: Compile On-Chain Data: Use block explorers like Etherscan or Solscan to find contract addresses. For example, a common vesting contract might be 0x1234567890abcdef1234567890abcdef12345678.
• Sub-step 2: Gather Off-Chain Documents: Collect PDFs of SAFT agreements, cap tables, and legal notices that detail cliff periods, vesting start dates (vestingStart=2023-01-01T00:00:00Z), and total grant amounts.
• Sub-step 3: Establish a Source Database: Input all data into a structured database (e.g., Airtable, Google Sheets) with fields for Asset Type, Contract Address, Vesting Schedule, and Next Unlock Date.

Tip: Use a wallet explorer tool like Debank or Zapper to get an initial list of token holdings and smart contract interactions for a given address, which can reveal vesting contracts you may have forgotten.

Detailed Instructions

Programmatic data fetching is critical for accuracy and timeliness. Write scripts using web3 libraries (e.g., ethers.js, web3.py) to query smart contracts for key vesting parameters. You need to call specific view functions to get the current state of a vesting schedule for a given beneficiary address.

• Sub-step 1: Connect to a Node Provider: Use services like Infura, Alchemy, or a public RPC endpoint. Initialize your provider.

javascriptCopy
const { ethers } = require('ethers');
const provider = new ethers.providers.JsonRpcProvider('https://mainnet.infura.io/v3/YOUR_API_KEY');

• Sub-step 2: Query Vesting Contract Functions: Common functions include vestedAmount(address beneficiary), releasableAmount(address beneficiary), cliff(), duration(), and start(). Create a contract instance and call these.

javascriptCopy
const contractABI = ["function vestedAmount(address) view returns (uint256)"];
const contract = new ethers.Contract('0x1234...', contractABI, provider);
const vested = await contract.vestedAmount('0xabcd...');
console.log(`Vested Amount: ${ethers.utils.formatUnits(vested, 18)}`);

• Sub-step 3: Calculate Future Unlocks: Using the start, cliff, and duration values, calculate the linear vesting curve to project future token releases.

Tip: Schedule these scripts (e.g., via cron job) to run daily and update your database, ensuring you always have the latest vested balance.

Detailed Instructions

For assets not on a blockchain, you must build a financial model that replicates the vesting or lock-up logic. This involves defining the grant size, cliff period (e.g., 12 months), vesting duration (e.g., 48 months), and vesting interval (e.g., monthly). The model should output a schedule showing the cumulative vested amount over time.

• Sub-step 1: Parse Agreement Terms: Extract key numerical values: totalGrant=100,000 tokens, cliffDate=2024-06-01, vestingStartDate=2023-06-01, vestingPeriod=4 years.
• Sub-step 2: Build the Vesting Formula: Implement the logic. For a common linear vesting model after a cliff: Vested = (Total Grant) * min(1, (Seconds Since Start - Cliff Seconds) / Vesting Duration Seconds).
• Sub-step 3: Create a Projection Table: Generate a table or chart showing monthly unlocks. For example, after a 12-month cliff, 1/48th of the total grant might vest each month.

Tip: Use spreadsheet software like Google Sheets with formulas or a Python script with pandas to create this model. This allows for easy "what-if" analysis and ensures you can track the asset alongside your on-chain data.

Detailed Instructions

Proactive alerting and reconciliation prevent missed unlocks and ensure data integrity. Configure notifications for upcoming vesting cliff ends, large token unlocks, and contract state changes. Then, periodically verify that your tracking system's numbers match the raw on-chain data or legal documents.

• Sub-step 1: Set Up Alert Rules: Define conditions that trigger alerts, such as "Vested balance increases by more than 10,000 tokens" or "Cliff date is within 7 days." Use tools like PagerDuty, custom webhooks, or even calendar invites.
• Sub-step 2: Perform Monthly Reconciliation: Once a month, manually check a sample of assets. For on-chain, compare your script's output for vestedAmount with a direct read on Etherscan. For off-chain, check your model's vested total against any official statements from the issuing entity.
• Sub-step 3: Audit for Contract Upgrades or Migrations: Illiquid assets, especially tokens, can migrate to new contracts. Monitor project announcements and set up alerts for transactions from the old vesting contract to a new one.

Tip: Create a simple dashboard that visualizes upcoming unlocks (next 30/90 days) and total illiquid portfolio value. This provides an at-a-glance view of liquidity timelines.

Detailed Instructions

Begin by defining the vesting schedule parameters in a smart contract. This contract is the single source of truth for all allocations and release logic. Key parameters include the total grant amount, the vesting start date (cliff), the vesting duration, and the release frequency (e.g., monthly, quarterly). For Ethereum-based assets, a common standard is the OpenZeppelin VestingWallet contract.

• Sub-step 1: Deploy the contract. Use a constructor to set the beneficiary address (e.g., 0x742d35Cc6634C0532925a3b844Bc9e90F1b6fBc6), start timestamp, duration, and cliff. For a 4-year vest with a 1-year cliff, set duration = 126144000 seconds.
• Sub-step 2: Fund the contract. Transfer the total grant of illiquid tokens (e.g., 10,000 PROJECT tokens) from the company treasury to the contract's address.
• Sub-step 3: Verify initialization. Query the contract's released() function to confirm it returns 0, indicating no tokens have been vested yet.

Tip: Always conduct a test deployment on a testnet (like Sepolia) first. Use cast call <contract_address> "start()" to verify the start time is correctly stored.

Detailed Instructions

Since on-chain queries can be expensive, implement a calculation script that reads the contract's immutable parameters and computes the vested amount. This script should be run regularly (e.g., daily) and can be integrated into internal dashboards. The core logic calculates the linear vesting based on elapsed time.

• Sub-step 1: Fetch contract data. Use a library like ethers.js to connect to the contract and read start(), duration(), and totalAllocation().
• Sub-step 2: Calculate vested amount. Implement the formula: vestedAmount = (elapsedTime / totalDuration) * totalAllocation, where elapsedTime is currentTimestamp - startTimestamp, capped at duration. Ensure you handle the cliff period where vested amount is 0.
• Sub-step 3: Create a reporting output. Format the result into a JSON object for APIs or a CSV for spreadsheets. Include fields for beneficiary, vestedToDate, remaining, and nextVestDate.

javascriptCopy
// Example calculation snippet using ethers.js
const elapsed = Math.min(currentTime - startTime, duration);
const vested = (elapsed * totalAllocation) / duration;
console.log(`Vested Amount: ${vested} tokens`);

Tip: Use a centralized scheduler like a cron job or AWS Lambda to run this script automatically and update a database.

Detailed Instructions

Passive calculation is not enough; you must actively monitor the blockchain for release transactions where the beneficiary claims their vested tokens. This reconciliation ensures your internal ledger matches the immutable on-chain state. Set up an event listener for the TokensReleased event emitted by the vesting contract.

• Sub-step 1: Set up an event listener. Using a provider like Alchemy or Infura, create a websocket subscription to listen for the event from the contract address. Log the amount and blockNumber of each release.
• Sub-step 2: Reconcile with calculations. When a release is detected, compare the released amount with your script's calculated "vested but unclaimed" balance. Any significant discrepancy may indicate an error in parameters or a manual admin override.
• Sub-step 3: Update internal records. Mark the corresponding tokens as liquid and transferred in your accounting system. For example, if 250 tokens are released to 0x742d35Cc6634C0532925a3b844Bc9e90F1b6fBc6, reduce their "vested but locked" balance by that amount.

Tip: For critical monitoring, set up alerts (e.g., via PagerDuty or Slack webhook) for any release event to ensure immediate awareness of team member activity.

Detailed Instructions

Transform raw vesting data into actionable financial reports. Illiquid assets often have tax implications (like 83(b) elections in the US) and must be reported on balance sheets. Create dashboards that aggregate data across all team member vesting contracts.

• Sub-step 1: Aggregate data across beneficiaries. Run your calculation script for all deployed contract addresses (e.g., 50 employee contracts) and consolidate results into a single database table. Key metrics include Total Vested Liability, Total Released, and Total Locked.
• Sub-step 2: Generate period-end reports. For quarterly closes, produce a report showing the change in vesting liability. Use a command like ./report-generator --format=csv --period=Q3-2024 to output a file for the accounting team.
• Sub-step 3: Facilitate tax documentation. For each beneficiary, provide a year-end statement detailing the fair market value of tokens that vested during the tax year, which is crucial for Form 3921 (for ISOs) or ordinary income reporting.

bashCopy
# Example command to generate a snapshot report
node scripts/generateVestingReport.js --date 2024-12-31 --output ./reports/EoY_2024.json

Tip: Integrate with data visualization tools like Tableau or Retool to create real-time dashboards for executives to monitor the company's equity dilution and vesting runway.