# Introducing Treem Finance Treem Finance is designed to make asset management and investment easier and more accessible by offering innovative solutions through tokenization. Essentially, it helps asset holders convert their assets into digital tokens, allowing them to access liquidity without going through the complex processes of traditional finance. Whether you’re an individual investor or a business, Treem Finance empowers assets with tokenization and provides a modern way to manage assets, making it simple to unlock their value. This platform also prioritizes security and compliance, it is built to meet strict global regulatory standards, ensuring that every transaction is conducted securely. This focus on regulatory adherence gives users peace of mind, knowing their investments are protected by strong risk management practices and the latest technological advancements. For investors, Treem Finance offers a straightforward experience. Once signed up, investors can manage their preferences, explore a variety of project offerings, and easily purchase tokens linked to real assets or other commodities. The platform makes it easy to sign token purchase agreements, make payments, and keep track of their investments in one place. With transparency and security at the forefront, investors can confidently engage in digital asset transactions, knowing they are part of a trusted ecosystem. Treem Finance supports asset holders and issuers by offering token issuance and distribution services. This allows issuers to easily convert their assets into tokens and distribute them to investors efficiently, while investors gain access to new investment opportunities. Similarly, Treem Finance creates a smooth bridge between asset holders and investors, using the power of blockchain to simplify access to liquidity and investment opportunities. With Treem Finance, users can confidently navigate the world of tokenized assets and fully take advantage of their benefits. # Our mission & values Treem is an investment platform giving global investors access to blue-chip commercial real estate in the world’s most prestigious cities — New York, London, Singapore, Dubai. We acquire prime professional-use properties below market value, secure them in dedicated entities, and fractionalize ownership through compliant blockchain securities. This creates transparent, tradable exposure to institutional-grade assets that were once only available to large funds. Our vision is simple: open the doors of Manhattan, London, Paris, Dubai, and other global gateways to accredited and international investors at scale. ### Mission Our mission is to democratize access to institutional-grade real estate by leveraging blockchain technology, enabling global investors to participate in blue-chip properties with transparency, liquidity, and trust.
### Vision Our vision is a world where premier commercial real estate in New York, London, Paris, Dubai, and other global gateways is no longer reserved for institutions and the ultra-wealthy — but accessible, tradable, and managed at scale through Treem’s platform.
### Values * **Access** – We believe every qualified investor, regardless of geography, should have the opportunity to participate in premium real estate markets. * **Transparency** – From property acquisition to token issuance and secondary trading, we commit to clear, verifiable processes. * **Innovation** – We harness blockchain, digital securities, and DeFi to expand liquidity and unlock new financial pathways. * **Integrity** – Compliance, governance, and investor protection stand at the core of our operations. * **Partnership** – We collaborate with fund managers, lenders, custodians, and regulators to deliver institutional-grade solutions. * **Performance** – We focus on prime, high-quality, income-generating real-world assets that combine stability with growth potential.
# What is Assets Tokenization Asset tokenization is the process of converting real-world assets into digital tokens that exist on a blockchain. This allows the assets to be easily traded, stored, and transferred in a secure and transparent digital environment. Tokenization provides a way for asset owners to unlock liquidity, allowing them to sell portions of their assets or raise funds without going through traditional, often cumbersome, financial systems.
Imagine having an asset—a piece of real estate, a work of art, or even shares in a company—that’s not just sitting idly but actively working for you, accessible from your computer or smartphone. Welcome to Treem Finance, a platform that bridges the gap between traditional finance and the digital economy. It transforms the way people view and manage their assets by converting them into digital tokens, making them as easy to interact with as any other online transaction. Let’s say you own a property but want to access some of its value without selling it outright. Traditionally, you’d be limited in options, facing either a long sales process or complex financing. But with Treem Finance, you can “**tokenize**” this asset, breaking it down into digital tokens representing shares of its value. You could even sell portions of these tokens, giving you liquidity without selling the entire asset. Investors can buy these tokens and become partial owners, benefiting from the asset's value and future appreciation. Blockchain, a technology that acts like a digital vault, securely records every transaction, backs the security of this entire process. Blockchain ensures that each token and its ownership are protected from fraud, making them nearly impossible to tamper with or duplicate. This level of security builds trust and confidence, a vital need for anyone managing valuable assets. Treem Finance doesn’t just make asset management secure and flexible; it also makes it easy. Whether you're a seasoned investor or entirely new to digital finance, Treem’s platform is designed for you. The dashboard provides a clear view of all your assets, tracks performance, and offers insights—all at your fingertips. And if you're not familiar with the world of digital finance, Treem’s onboarding guides and support make sure you’re never left in the dark. Imagine a future where your assets are not confined by traditional processes and timelines, where they can be instantly accessible, securely stored, and easily managed from wherever you are. Treem Finance offers exactly that, helping people transform their financial potential by making assets work smarter, faster, and more transparently. It’s a new era of asset management, where the tools of the digital age put you in control like never before. ## Key Points ### Digital Transformation of Assets Treem Finance specializes in transforming traditional assets—such as real estate, art, and commodities—into digital tokens. This transformation makes assets more versatile, allowing holders to manage and transact with them through digital channels. By leveraging blockchain technology, Treem Finance streamlines asset ownership, enhancing flexibility and accessibility for investors. Tokenization also paves the way for fractional ownership, where users can own and trade smaller shares of high-value assets, democratizing access to investment opportunities that were previously reserved for large institutions. ### Enhanced Liquidity and Accessibility One of the key advantages of tokenizing assets with Treem Finance is improved liquidity. Traditionally, assets like real estate or artwork require lengthy and costly processes to be sold or leveraged. With digital tokens, these assets can be bought, sold, or traded more efficiently. By opening up new markets and enabling faster transactions, Treem Finance allows asset holders to access their capital more quickly and with fewer barriers. Additionally, this enhanced liquidity appeals to a broader range of investors, as digital tokens can be more easily bought and sold than traditional assets. ### Blockchain-Powered Security Security is a top priority at Treem Finance. The platform uses blockchain technology to create a transparent, tamper-proof ledger of all transactions, ensuring that ownership and transaction data are secure and immutable. Each digital token represents a secure and verifiable record of ownership, backed by the blockchain’s inherent encryption. This setup reduces the risks of fraud, duplication, or unauthorized transfers, providing users with the peace of mind that their assets are protected. Treem Finance’s commitment to security helps build trust among users and fosters a reliable environment for digital asset management. ### Comprehensive Asset Management Solutions Treem Finance offers a suite of services that cover every aspect of digital asset management, from token issuance to distribution and ongoing asset management. This comprehensive approach allows asset holders to conduct all necessary operations within a single platform, simplifying management tasks and enhancing efficiency. With built-in tools for performance monitoring, compliance, and data analytics, Treem Finance supports both individual investors and institutional clients, enabling them to manage their assets strategically and efficiently. This all-in-one solution also allows users to avoid the complexities and costs associated with managing assets across multiple platforms. ### User-Friendly and Inclusive Treem Finance is designed with user experience in mind, ensuring that individuals and institutions, regardless of technical expertise, can navigate the platform with ease. The intuitive interface guides users through each step of tokenization and asset management, while customer support and educational resources are readily available for additional guidance. Treem Finance’s user-friendly platform enables a broad spectrum of participants, from seasoned investors to newcomers, to engage with digital finance confidently. The inclusivity of the platform not only broadens access to digital asset management but also fosters a welcoming environment for all users. ### Commitment to Innovation At the core of Treem Finance is a dedication to innovation and staying ahead of trends in digital finance. By continuously updating its technology and expanding its service offerings, Treem Finance ensures that it remains at the cutting edge of digital finance. Whether through developing new tokenization methods, improving platform security, or enhancing user experiences, Treem Finance is committed to evolving alongside the needs of the digital economy. This forward-thinking approach positions Treem Finance as a pioneer in the industry, providing clients with innovative tools to meet the demands of a fast-changing financial landscape. ## How Asset Tokenization Works on Treem Finance Treem Finance makes asset tokenization straightforward and accessible, handling every step from verifying real-world assets to enabling the trading of tokens on global markets. ### Real-World Assets (RWA) The tokenization journey begins with the registration and vetting of real-world assets. It ensures that the asset owners are verified, the assets are properly screened, and everything complies with regulatory standards. For example, suppose someone wants to tokenize a property. In that case, Treem Finance ensures that the ownership is legitimate, the asset is properly evaluated, and that storage and insurance are in place, providing security to both asset holders and investors. ### Token Issuance and Management Once the real-world asset has been registered, Treem Finance moves on to the tokenization stage. This involves pre-tokenization activities like gathering subscriptions and verifying all necessary details. Then, the actual token minting happens, which means that digital tokens are created on the blockchain to represent the real asset. After the tokens are issued, Treem Finance continues supporting the asset holders by managing them, ensuring they remain secure, compliant, and operational over time. ### Token Distribution and Trading After tokens are minted, they need to be made available for trading. Treem Finance offers several ways for token holders to distribute and trade their tokens. Tokens can be listed on centralized exchanges (CEXs), which work similarly to traditional stock markets, or decentralized exchanges (DEXs), which operate more openly and peer-to-peer. Additionally, tokens can be traded through P2P transactions or used in decentralized finance (DeFi) ecosystems, where users can engage in activities like lending or borrowing tokens, thus creating more financial opportunities. ## Benefits of Tokenization with Treem Finance One of the major benefits of tokenization is that it allows asset holders to access liquidity that would otherwise be locked up in their assets. For example, instead of waiting years to sell an entire property, an asset holder can tokenize a fraction of the property and sell that fraction as digital tokens, making money sooner while still retaining ownership of the rest of the property. For investors, tokenization provides access to a broader range of investment opportunities. Instead of needing large amounts of capital to invest in a full asset, they can buy tokens representing a fraction of it. This opens up new ways to diversify portfolios and participate in markets that may have been out of reach before. # Why Choose Treem Finance for Tokenization Treem Finance stands out as your trusted partner for asset tokenization. Treem Finance provides advice, with added capabilities in accessing and securing capital. Services include advice for issuers, distribution of tokens, sharing the risks of the issue, and stabilization of the aftermarket. Treem Finance also "certifies" the issue by putting its reputation behind the tokens, ensuring trustworthiness and legitimacy. Treem Finance offers a comprehensive tokenization platform to support token issuance and distribution. Treem Finance platform is the best choice for tokenizing your assets because it offers a secure, transparent, and user-friendly way to unlock the value of real-world assets. One of the key reasons to choose Treem Finance is security. The platform is built with advanced technologies that ensure your assets and transactions are protected at every step. From verifying asset ownership to securely managing and trading tokens, Treem Finance prioritizes the safety of its users. This means that whether you're issuing tokens or purchasing them, you can trust that your assets and data are safeguarded.
Another important factor is compliance. Treem Finance follows strict global regulatory standards, which ensures that all tokenization processes meet the necessary legal requirements. This commitment to compliance not only protects asset holders and investors but also builds trust in the platform. You can engage with Treem Finance knowing that your transactions are transparent and fully compliant with applicable laws. This platform also makes tokenization easy and accessible. The platform’s intuitive interface guides users through each stage of the tokenization process. Whether you’re registering assets, issuing tokens, or trading them on exchanges, Treem Finance simplifies the experience, so you don’t need to be a blockchain expert to participate. The platform’s user-friendly design ensures that both beginners and experienced investors can use it with ease. The reason to choose Treem Finance is the broad market access it provides. After your assets are tokenized, Treem Finance offers various options for trading, including centralized exchanges (CEXs), decentralized exchanges (DEXs), and peer-to-peer (P2P) transactions. This flexibility ensures that you have multiple avenues to access liquidity and investment opportunities, expanding your reach to global markets. Lastly, Treem Finance’s commitment to transparency is central to its platform. All transactions, token movements, and asset details are visible on the blockchain, allowing users to track their activities in real-time. This transparency fosters trust between asset holders, investors, and the platform, creating a fair and open ecosystem for everyone involved. # Introduction To get started, welcome to **Treem**, a state-of-the-art, all-encompassing digital solution designed for investors seeking to navigate the world of tokenized assets. This platform is crafted to provide external investors with simplified access to a broad range of investment opportunities in tokenized assets while ensuring a secure, transparent, and user-friendly experience. With Treem, investors can access project listings, purchase tokens, sign token purchase agreements, manage payments, and personalize their investment preferences–all from a single, centralized dashboard. ## Platform Architecture & Design The Treem platform is built on a robust and secure architecture that integrates seamlessly with blockchain technology. Designed with scalability and security at its core, the platform supports essential investor functions such as wallet management, transaction processing, and secure storage of digital assets. By utilizing blockchain, Treem enables transparent and verifiable transactions, ensuring that investors can trust the integrity of their investments. The platform’s structure includes several interconnected components: * **User Interface (UI)**: A highly intuitive dashboard that allows investors to manage portfolios, view accessible offerings, track transaction requests, and monitor investment metrics. The UI is organized for easy navigation, with key features accessible from the main dashboard. * **Wallet Integration**: Treem supports secure wallet integration, enabling investors to manage their digital assets and monitor their portfolio’s value directly within the platform. * **Backend and Security Layer**: Treem’s backend infrastructure employs advanced encryption and security measures to protect user data and transactions. Compliance with regulatory standards is embedded within the architecture, offering a secure environment for all investment activities. * **Blockchain Integration**: Treem Finance utilizes blockchain smart contracts to manage token transactions and whitelisting. All wallet addresses must be verified and whitelisted to ensure compliance and security. ## Core Functions & Features The Treem platform offers a suite of functions customized to meet the needs of modern investors in the digital finance space: 1. **Account Management**: New users can easily sign up and existing users can log in securely. The account management system is designed to provide secure access and compliance with regulatory requirements. 2. **Dashboard Overview**: The main dashboard provides a snapshot of essential investment details, including the total amount invested, portfolio value, total distributions received, and owed balances. This comprehensive view helps investors stay updated on their portfolio performance at a glance. 3. **Access to Offerings and Projects**: Treem provides investors with access to a curated list of projects and offerings, each representing a tokenized real-world asset. These accessible offerings allow users to review project details, investment requirements, and expected returns before committing to an investment. 4. **Transaction Requests and Approvals**: The platform simplifies the process of making and managing transaction requests. Investors can initiate purchases, view transaction statuses, and receive notifications once transactions are approved by the administrator. 5. **Portfolio Management**: Investors can actively manage their portfolios by viewing holdings, monitoring share types, and checking payment status. The platform supports various asset classes, allowing investors to diversify their portfolios with ease. 6. **Corporate Actions and Document Management**: Treem facilitates corporate actions and document management, allowing investors to stay informed on any updates or changes related to their holdings. Essential documents are easily accessible within the platform. 7. **Payments and Token Purchase Agreements**: Treem’s integrated payment system allows investors to securely process payments, sign token purchase agreements, and track payment statuses. This feature ensures that all transactions are transparent and compliant. 8. **Communication and Notifications**: Investors can receive updates and communications through the platform’s messaging system, keeping them informed about their investments, new offerings, and platform updates. 9. **Multilingual Support**: The platform includes support for multiple languages, allowing investors from various regions to access it in their preferred language, and enhancing accessibility. ## Future Vision The future vision of Treem is to democratize access to digital asset investment by making the process straightforward, secure, and accessible for a wide range of investors. Treem Finance aims to bridge the gap between traditional finance and blockchain technology, empowering investors to take part in a new era of asset-backed token investments. **Key Objectives Include**: * **Enhancing Accessibility to Tokenized Assets**: By providing a user-friendly interface and comprehensive tools, Treem enables investors to explore and invest in tokenized real-world assets with ease. * **Ensuring Security and Compliance**: Treem places a high priority on data security and regulatory compliance, implementing industry-standard protocols to protect investors and their assets. * **Empowering Investors**: The platform provides investors with all the tools and information they need to make informed decisions and manage their portfolios, from investment opportunities to transaction records and updates. * **Building Transparency and Trust**: Through blockchain technology and a transparent investment process, Treem fosters trust within its user community, ensuring that all transactions and investment activities are verifiable and transparent. ## Why Choose Treem Finance for Investing? Treem is ideal for those who want to explore digital assets backed by real-world value. With features designed specifically for investor needs, Treem Finance offers a platform that prioritizes security, ease of use, and transparency. The commitment to regulatory compliance and a clear user interface makes it suitable for both new investors and experienced ones looking to diversify their portfolios. By providing a unified view of tokenized investments, access to exclusive projects, and easy wallet management, Treem Finance enables investors to confidently take full advantage of the growing world of digital finance. The platform ensures that investors have everything they need to make secure and informed investments, helping them grow and manage their portfolios effectively. In summary, the Treem platform is more than just an investment platform; it’s a gateway to the future of digital assets. Through a secure and transparent environment, it empowers investors to participate in a modern investment landscape, combining the best of traditional finance with the innovation of blockchain technology. # Overview #### 1.1 Platform Overview Treem is a comprehensive Real-World Asset (RWA) tokenization platform that connects issuers with investors through blockchain-based digital securities. The platform enables organizations to tokenize physical assets (such as real estate, infrastructure, or commodities) and offer them as investment opportunities to accredited investors. **Key Features:** * Multi-organization issuer management * Complete project lifecycle management * Investor discovery and onboarding * Regulatory compliance tracking * Token class configuration * Document management * Audit trails and security monitoring #### 1.2 Key Concepts & Terminology | Term | Definition | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Organization** | A legal entity (company) that issues tokenized assets. Organizations are managed by issuer admins. | | **Issuer Admin** | A user who manages one or more organizations and creates/manages projects on behalf of those organizations. | | **Platform Admin** | A super-user who manages the entire platform, approves organizations and projects, and assigns issuer admins. | | **Project** | A specific tokenized asset offering (e.g., a real estate property, infrastructure project) created by an organization. | | **Token Class** | A specific type of security token within a project, with defined pricing, rights, and characteristics. | | **RWA** | Real-World Asset - a physical asset that is tokenized on the blockchain. | | **Investor Profile** | A comprehensive profile created through the investor discovery process that includes financial information, risk tolerance, and investment objectives. | #### 1.3 User Roles Summary * **Platform Admin**: Full platform control, organization approval, project approval * **Issuer Admin**: Organization management, project creation/management, investor relations * **Investor**: Browse projects, complete discovery process, invest in tokenized assets # Organizations #### 2.1 What is an Organization? An **Organization** represents a legal entity (registered or unregistered) that wishes to tokenize real-world assets and offer them to investors. Each organization must be approved by platform administrators before it can create and publish projects. **Key Attributes:** * Company Name (platform-locked after approval) * Legal Structure (LLC, Corporation, etc.) * Registration Number * Legal Jurisdiction * Contact Information * Company Address (platform-locked after approval) * KYC Status #### 2.2 Organization Lifecycle The organization lifecycle consists of the following stages: ``` Application → Review → Approved → Active → (Optional) Change Requests ``` **Stages Explained:** 1. **Application**: A user submits an issuer application through the platform 2. **Review**: Platform admins review the application and supporting documents 3. **Approved**: The application is approved, and an organization is created 4. **Active**: The organization can create and manage projects 5. **Change Requests**: Locked fields (company name, address) can only be changed through formal change requests with supporting documentation #### 2.3 Creating Organizations Organizations are **not created directly by users**. Instead, they are created through an approval process: **Step 1: Submit Issuer Application** 1. Navigate to the issuer sign-up page 2. Complete the issuer application form with: * Company name * Legal structure * Registration number * Legal jurisdiction * Representative information * Company website * Project type and asset class **Step 2: Platform Admin Review** 1. Platform admin reviews the application in the Admin Dashboard 2. Admin verifies company information and legal documentation 3. Admin approves or rejects the application **Step 3: Organization Creation** * Upon approval, the system automatically creates an organization * The organization inherits data from the approved application * Certain fields (company name, address) are automatically locked for legal compliance #### 2.4 Managing Organizations Once created, organizations can be managed by: * **Platform Admins**: Full access to all organization settings * **Issuer Admins**: Assigned by platform admins, can manage organization projects and team **Accessing Organization Management:** * Issuer Admins: Navigate to Settings → Organization * Platform Admins: Navigate to Admin → Organizations tab **Editable Fields:** * Contact email * Phone number * Website URL * Company description * Logo * Legal structure details **Locked Fields (require change request):** * Company name * Company address #### 2.5 Organization Change Requests When an organization needs to update locked fields (company name or address), they must submit a formal change request. **How to Submit a Change Request:** 1. Navigate to **Settings → Organization** (as Issuer Admin) 2. Click the **"Request Change"** button next to a locked field 3. Fill out the change request form: * Field to change (Company Name or Company Address) * Current value (auto-filled) * Requested new value * Supporting documentation (required - upload legal documents, certificates, etc.) 4. Submit the request **Change Request Review Process:** 1. **Submission**: Issuer admin submits request with supporting documentation 2. **Pending Review**: Platform admin is notified 3. **Admin Review**: Platform admin reviews the request and documentation 4. **Decision**: Admin approves or rejects with notes 5. **Implementation**: If approved, the system automatically updates the locked field **Important Notes:** * Change requests require legal documentation (corporate resolution, certificate of incorporation, etc.) * Both company name and address changes require platform admin approval * All change requests are logged in the audit trail * Rejected requests include admin notes explaining the reason # User Roles & Responsibilities #### 3.1 Platform Admin Role **Access Level**: Highest level of system access **Key Responsibilities:** * Review and approve issuer applications * Create and manage organizations * Assign issuer admins to organizations * Review and approve projects submitted by issuers * Review and approve organization change requests * Monitor platform security and audit logs * Manage platform-wide settings * Access all projects, organizations, and user data **Platform Admin Capabilities:** * Full CRUD access to organizations * Ability to lock/unlock organization fields * Project approval workflow management * User role assignment and management * System audit log access * Security monitoring #### 3.2 Issuer Admin Role **Access Level**: Organization-level access **Key Responsibilities:** * Manage one or more assigned organizations * Create and manage projects for their organizations * Submit projects for platform admin approval * Manage project documentation and media * Configure token classes and financial terms * Manage investor relations for their projects * Submit change requests for locked organization fields * View organization-specific analytics **Issuer Admin Capabilities:** * Create new projects * Edit draft projects * Submit projects for approval * Revoke submitted projects (to make edits) * Upload project documents and images * Configure token classes * View investors in their projects * Submit organization change requests **Multi-Organization Support:** * A single user can be an issuer admin for multiple organizations * Use the organization switcher in the sidebar to switch between organizations * Each organization's projects and data are kept separate #### 3.3 Investor Role **Access Level**: Limited, investor-facing access **Key Responsibilities:** * Complete investor discovery process * Build comprehensive investor profile * Browse approved projects * View project details and documentation * Make investment commitments * Manage personal portfolio * Complete KYC/AML requirements **Investor Capabilities:** * View all approved (published) projects * Access project financial details and documents * Complete investor discovery questionnaire * Save investment preferences * Track personal investments * Access investor dashboard #### 3.4 Role Permissions Matrix | Feature | Platform Admin | Issuer Admin | Investor | | --------------------------- | -------------- | ------------ | -------- | | View all organizations | ✅ | ❌ | ❌ | | Create organizations | ✅ | ❌ | ❌ | | Approve issuer applications | ✅ | ❌ | ❌ | | Assign issuer admins | ✅ | ❌ | ❌ | | Approve projects | ✅ | ❌ | ❌ | | Create projects | ✅ | ✅ (own org) | ❌ | | Edit own projects | ✅ | ✅ | ❌ | | View draft projects | ✅ | ✅ (own org) | ❌ | | View approved projects | ✅ | ✅ | ✅ | | Submit change requests | ✅ | ✅ (own org) | ❌ | | Approve change requests | ✅ | ❌ | ❌ | | Access audit logs | ✅ | ❌ | ❌ | | Complete investor discovery | ❌ | ❌ | ✅ | | Make investments | ❌ | ❌ | ✅ | *** # Projects #### 4.1 What is a Project? A **Project** represents a specific tokenized asset offering created by an organization. Each project corresponds to a real-world asset (such as a property, infrastructure project, or commodity) that is being tokenized and offered to investors. **Example Projects:** * A commercial office building in downtown Manhattan * A solar farm infrastructure project * A portfolio of residential rental properties * A luxury hotel development #### 4.2 Types of Real-World Assets (RWA) The platform supports various asset classes: | Asset Class | Description | Examples | | ---------------------- | -------------------------- | ------------------------------------------------------ | | **Real Estate** | Physical properties | Office buildings, residential complexes, retail spaces | | **Infrastructure** | Large-scale infrastructure | Solar farms, wind farms, toll roads, bridges | | **Commodities** | Physical commodities | Precious metals, agricultural products | | **Equipment** | High-value equipment | Aircraft, shipping containers, machinery | | **Art & Collectibles** | Valuable collectibles | Fine art, rare wines, luxury watches | #### 4.3 Project Lifecycle & Statuses Projects move through a defined lifecycle with the following statuses: ``` Draft → Submitted → Under Review → Approved/Rejected/Revision Requested ↓ Active (Live) ``` **Status Definitions:** | Status | Description | Actions Available | | ---------------------- | ----------------------------------------------- | ----------------------------------------- | | **Draft** | Project is being created/edited by issuer admin | Edit, Delete, Submit for Approval | | **Submitted** | Project submitted for platform admin review | Revoke (issuer), Review (admin) | | **Under Review** | Platform admin is actively reviewing | Approve, Reject, Request Revision (admin) | | **Revision Requested** | Admin requested changes before approval | Edit, Re-submit (issuer) | | **Approved** | Project approved and live on platform | View only (no edits without revoke) | | **Rejected** | Project rejected by platform admin | View admin notes, Create new project | #### 4.4 Internal vs Public Information Projects contain both internal (admin-only) and public (investor-facing) information: **Internal Information (Admin/Issuer Only):** * Admin notes and feedback * Approval workflow history * Internal compliance tracking * Platform locked fields * System metadata **Public Information (Visible to Investors):** * Project name and description * Location and property details * Financial metrics (IRR, cap rate, yields) * Token class information * Gallery images and videos * Public documents (offering memorandum, etc.) * Key highlights and features * Exit strategy **Access Control:** * Draft projects: Only visible to issuer admins and platform admins * Submitted projects: Only visible to issuer admins and platform admins * Approved projects: Visible to all investors *** # Project Creation & Management (Issuer Admin) #### 5.1 Creating a New Project **Prerequisites:** * You must be an issuer admin for an organization * Your organization must be approved by platform admin * You must have selected an organization (use the organization switcher if you manage multiple) **Steps to Create a Project:** **Step 1: Navigate to Project Creation** 1. Log in as an issuer admin 2. Ensure the correct organization is selected (check sidebar) 3. Navigate to **Projects → Create New Project** **Step 2: Complete Basic Information** **Required Fields:** * **Project Name**: A clear, descriptive name for the asset * **Tagline**: A short, compelling description (1 sentence) * **Description**: Detailed overview of the asset and investment opportunity * **Property Type**: Select from dropdown (Office, Retail, Residential, etc.) * **Asset Class**: Real Estate, Infrastructure, Commodities, etc. **Location Information:** * **Address**: Full street address * **Coordinates**: Latitude/longitude (auto-filled if available) **Step 3: Financial Details** **Asset Valuation:** * **Purchase Price**: Original acquisition cost * **Appraised Value**: Current appraised value * **Expected Exit Value**: Projected value at exit **Performance Metrics:** * **NOI (Net Operating Income)**: Annual net operating income * **Cap Rate**: Capitalization rate (%) * **Target IRR**: Internal rate of return target (%) * **Target Annual Return**: Expected annual return (%) **Investment Terms:** * **Target Amount**: Total fundraising goal * **Currency**: USD, EUR, etc. * **Investment Term**: Duration in months * **Start Date**: Fundraising start date * **End Date**: Fundraising end date **Step 4: Use of Funds** Define how the raised capital will be used: ```json { "property_acquisition": 60, "renovations": 20, "operating_capital": 10, "legal_fees": 5, "platform_fees": 5 } ``` * Each category with percentage allocation * Must total 100% **Step 5: Token Class Configuration** Create at least one token class for the project: **Token Class Fields:** * **Class Name**: e.g., "Class A Preferred" * **Token Symbol**: e.g., "PROP-A" * **Price Per Token**: Price in USD (or selected currency) * **Minimum Investment**: Minimum investment amount * **Maximum Investment**: Maximum investment amount (optional) * **Voting Rights**: Yes/No * **Transferable**: Yes/No * **Lockup Period**: Months before tokens can be transferred * **Distribution Frequency**: Quarterly, Annual, etc. * **Projected Yield**: Expected annual yield (%) * **Asset Backing**: Description of asset backing **Multiple Token Classes:** * Projects can have multiple token classes (e.g., Class A, Class B) * Each class can have different rights, pricing, and terms * Useful for creating tiered investment opportunities **Step 6: Media & Gallery** **Hero Image:** * Upload a primary hero image for the project * Recommended: High-quality, professional photo (1920x1080px) **Gallery Images:** * Upload multiple images showcasing the asset * Supports: Property photos, renderings, floor plans * Drag and drop to reorder images * Add captions/descriptions for each image **Video:** * Add a video URL (YouTube, Vimeo) * Optional but recommended for major projects **Blueprint/Floor Plan:** * Upload technical drawings or floor plans * PDF format recommended **Step 7: Legal & Compliance** **Offering Type:** * Reg D 506(b) * Reg D 506(c) * Reg A+ * Reg CF **Jurisdiction:** * Primary legal jurisdiction * Securities law compliance region **Issuer Entity:** * Legal entity name issuing the tokens * May differ from organization name **Legal Disclaimers:** * Required disclosure text * Risk factors * Investment suitability warnings **KYC/AML Status:** * Current compliance status * Required for all projects **Step 8: Blockchain Details** **Smart Contract:** * Smart contract address (if already deployed) * Blockchain network (Ethereum, Polygon, etc.) **Service Providers:** * Escrow provider name * Transfer agent name #### 5.2 Saving as Draft vs. Submitting **Save as Draft:** * Saves all progress without submitting for review * Project remains in "draft" status * Only visible to you and platform admins * Can be edited at any time * No approval required **Submit for Approval:** * Submits project to platform admin for review * Changes project status to "submitted" * Can no longer be edited without revoking * Enters the approval workflow * Platform admin receives notification **Best Practice:** * Save as draft frequently while working * Only submit when project is complete and ready for review * Ensure all required fields are filled * Upload all necessary documents and images * Double-check financial calculations #### 5.3 Required vs. Optional Fields **Required Fields (Must be completed before submission):** * Project name * Description * Property type * Asset class * Location address * Target amount * At least one token class * Legal offering type * Jurisdiction **Optional Fields (Recommended but not required):** * Tagline * Hero image * Gallery images * Video URL * Blueprint * Purchase price * Appraised value * NOI, Cap rate, IRR * Smart contract address * Escrow/transfer agent details #### 5.4 Form Validation & Error Handling The system validates your input in real-time: **Validation Rules:** * Currency values must be positive numbers * Percentages must be between 0-100 * Dates must be in valid format * Token prices must be positive * Min investment ≤ Max investment * Use of funds must total 100% **Error Messages:** * Red text appears below invalid fields * Submit button is disabled until errors are resolved * Hover over error icons for detailed explanations *** # Project Editing & Revision Workflow #### 6.1 Editing Draft Projects Projects in "draft" status can be freely edited: **To Edit a Draft Project:** 1. Navigate to **Projects** (issuer dashboard) 2. Find the project with "Draft" status 3. Click **Edit** button 4. Make your changes 5. Click **Save Draft** or **Submit for Approval** **What Can Be Edited:** * All fields and sections * Media and documents * Token classes * Financial information #### 6.2 The Revoke & Re-Submit Process Once a project is submitted or approved, it cannot be directly edited. To make changes, you must use the **Revoke** feature: **When to Use Revoke:** * Project is in "submitted" status and you need to make changes * Project is "approved" but requires updates * You received "revision requested" feedback from admin **How to Revoke a Project:** 1. Navigate to **Projects** (issuer dashboard) 2. Find the submitted/approved project 3. Click **Revoke** button 4. Confirm the revocation 5. Project status changes back to "draft" 6. Project is removed from public view (if it was approved) 7. Edit the project as needed 8. Re-submit for approval **Important Notes:** * Revoking an approved project removes it from investor view immediately * All revoke actions are logged in the audit trail * You can provide a reason for revoking (optional) * Platform admins are notified of revocations **The Re-Submission Process:** After revoking and editing: 1. Complete all necessary changes 2. Review the entire project for accuracy 3. Click **Submit for Approval** 4. Add submission notes (optional but recommended) 5. Project re-enters the approval queue 6. Platform admin reviews the updated version #### 6.3 Handling "Revision Requested" Status When a platform admin requests revisions: **You Will Receive:** * Email notification (if enabled) * In-app notification * Admin notes visible on project detail page **Steps to Address:** 1. Read the admin notes carefully 2. The project automatically returns to "draft" status 3. Make the requested changes 4. Address all admin feedback points 5. Re-submit with notes indicating changes made **Example Response:** ``` Changes made per admin feedback: - Updated NOI calculations to reflect actual historical data - Added supporting documentation for property appraisal - Corrected token class voting rights description - Uploaded additional property images as requested ``` #### 6.4 Version Control & Change History All project changes are tracked: **Audit Trail Includes:** * Date/time of each change * User who made the change * Status transitions * Submission/revocation events * Admin review actions **Accessing Change History:** * Platform admins can view full history in Admin → Project Detail * Issuer admins can view their own submission history * Change log is permanent and cannot be deleted #### 6.5 Best Practices for Project Management **Before Submitting:** * ✅ Review all financial calculations with your finance team * ✅ Have legal counsel review compliance sections * ✅ Ensure all images are high-quality and properly licensed * ✅ Double-check token class terms and conditions * ✅ Upload all required documents * ✅ Test all external links (videos, websites) **When Revising:** * ✅ Clearly document what changes were made * ✅ Address all admin feedback points * ✅ Re-check related sections that may be affected * ✅ Update the submission date if relevant **Ongoing Management:** * ✅ Monitor project status regularly * ✅ Respond promptly to admin requests * ✅ Keep investor documents up-to-date * ✅ Update financial metrics if conditions change significantly *** # Platform Admin Functions #### 7.1 Overview of Platform Admin Responsibilities Platform admins are the gatekeepers and managers of the entire Treem platform. They ensure regulatory compliance, verify organization legitimacy, and approve projects before they go live to investors. **Core Functions:** * Issuer application review and approval * Organization creation and management * Issuer admin assignment * Project review and approval * Organization change request review * Platform security monitoring * Audit log access * System settings management #### 7.2 Managing Issuer Applications **Accessing Applications** 1. Log in as platform admin 2. Navigate to **Admin → Organizations** 3. Click on **Applications** tab **Application List View** The applications table shows: * Company name * Representative name and email * Application status (Pending, Approved, Rejected) * Submission date * Action buttons **Reviewing an Application** **Step-by-Step Review Process:** 1. **Click on an application** to view details 2. **Review the information provided:** * Company legal information * Representative credentials * Business description * Intended asset classes * Legal documentation (if uploaded) 3. **Verify legitimacy:** * Cross-reference company registration number * Verify representative identity * Check legal jurisdiction validity * Review website and business presence 4. **Make a decision:** **To Approve:** * Click **Approve** button * Add admin notes (optional but recommended) * System automatically creates organization * Applicant receives approval notification **To Reject:** * Click **Reject** button * Add admin notes explaining rejection reason (required) * Applicant receives rejection notification * Application cannot be re-opened (must submit new) **What Happens After Approval:** * A new organization is automatically created * Organization inherits data from application * Company name and address are automatically locked * Application status changes to "Approved" * Applicant can now log in and access issuer console * No issuer admin is assigned yet (must be done separately) **Admin Notes Best Practices:** **For Approvals:** ``` Application approved. Company verified through [source]. Registration number confirmed with [jurisdiction authority]. Cleared for real estate tokenization projects. ``` **For Rejections:** ``` Application rejected. Reasons: 1. Unable to verify company registration number 2. Representative email domain does not match company website 3. Insufficient information about intended projects Applicant may reapply with corrected information. ``` #### 7.3 Creating & Managing Organizations **Creating Organizations Manually** While most organizations are created through application approval, admins can create organizations directly: 1. Navigate to **Admin → Organizations** 2. Click **Organizations** tab 3. Click **Create Organization** button 4. Fill in required information: * Company name * Legal structure * Registration number * Legal jurisdiction * Contact email * Phone number 5. Click **Create** **When to Create Manually:** * Onboarding enterprise clients * Migrating existing issuers to platform * Testing purposes * Special partnerships **Viewing All Organizations** The Organizations tab displays: * Company name * Contact information * Number of assigned admins * Creation date * Status (Active, Suspended) * Action buttons **Editing Organizations** **Platform admins can edit any field**, including locked fields: 1. Click on an organization in the list 2. Click **Edit** button 3. Modify any field as needed 4. Click **Save** **Editable Fields (including locked):** * Company name\* * Company address\* * Contact information * Legal details * Logo * Description * Platform locked fields configuration \*Note: Direct edits by platform admin do not require change requests. Only issuer admins must submit change requests for locked fields. **Suspending Organizations** If an organization violates terms or requires investigation: 1. Navigate to organization detail 2. Click **Suspend** button 3. Provide suspension reason 4. Confirm suspension **Effects of Suspension:** * Issuer admins cannot log in * All projects become unavailable to investors * Existing investments are frozen * Organization appears in "Suspended" status **To Reactivate:** * Click **Reactivate** button * Provide reactivation notes * All projects resume normal status #### 7.4 Assigning Issuer Admins Organizations require at least one issuer admin to operate. Platform admins assign users as issuer admins. **How to Assign an Issuer Admin:** 1. Navigate to **Admin → Organizations** 2. Click on an organization 3. Click **Assign Admin** button (or navigate to admin assignment section) 4. **Search for user** by email 5. **Select user** from results 6. Add optional notes about the assignment 7. Click **Assign** **Prerequisites:** * User must already exist in the system * User must have verified email * User should not be another organization's admin (unless multi-org) **Managing Existing Admins:** View assigned admins: * Issuer admin name and email * Assignment date * Assigned by (which platform admin) * Status (Active, Revoked) **To Revoke an Admin:** 1. Find the admin in the list 2. Click **Revoke** button 3. Provide revocation reason 4. Confirm revocation 5. User loses access to organization immediately **Audit Trail:** * All admin assignments are logged * Revocations are tracked with reasons * Assignment history is permanent #### 7.5 Project Review & Approval **Accessing Submitted Projects** 1. Navigate to **Admin → Projects** 2. Filter by status: **Submitted** or **Under Review** 3. Click on a project to view details **Project Review Checklist** When reviewing a project, verify: **Legal & Compliance:** * [ ] Offering type is appropriate for jurisdiction * [ ] Legal disclaimers are complete * [ ] KYC/AML procedures are in place * [ ] Jurisdiction is clearly stated * [ ] Issuer entity is properly formed **Financial Information:** * [ ] All calculations are accurate * [ ] Target amount is reasonable * [ ] Token pricing makes sense * [ ] Projected returns are realistic (not exaggerated) * [ ] Use of funds totals 100% * [ ] Financial metrics (IRR, cap rate) are credible **Project Details:** * [ ] Description is clear and comprehensive * [ ] Property/asset actually exists * [ ] Location is accurate * [ ] Key highlights are factual * [ ] Exit strategy is reasonable **Media & Documentation:** * [ ] Hero image is professional quality * [ ] Gallery images are relevant * [ ] Documents are uploaded (offering memo, etc.) * [ ] No copyrighted content without permission **Token Classes:** * [ ] Token terms are clear * [ ] Pricing is appropriate * [ ] Min/max investment ranges are logical * [ ] Rights and restrictions are well-defined **Making a Decision** **Option 1: Approve the Project** 1. Click **Approve** button 2. Add approval notes (optional) 3. Confirm approval **Result:** * Project status changes to "approved" * Project becomes visible to all investors * Issuer receives approval notification * Project appears in marketplace **Option 2: Request Revisions** 1. Click **Request Revisions** button 2. **Provide detailed feedback** (required): ``` Please address the following items before resubmission: 1. Financial Metrics: The projected IRR of 45% seems unrealistic for this asset class. Please provide supporting analysis or adjust to industry standards (8-12% for similar properties). 2. Documentation: Please upload the independent property appraisal report mentioned in the description. 3. Token Class: Class A voting rights description is unclear. Please specify exactly what decisions token holders can vote on. 4. Images: Gallery image #3 appears to be from a different property. Please replace with actual project photos. ``` 3. Confirm request **Result:** * Project status changes to "revision\_requested" * Project returns to issuer as draft * Issuer can make changes and resubmit * Your feedback is visible to issuer **Option 3: Reject the Project** 1. Click **Reject** button 2. Provide detailed rejection reasons: ``` Project rejected for the following reasons: 1. The property does not meet platform standards for institutional-quality assets. 2. Financial projections appear to be misleading or unsubstantiated. 3. Legal structure does not comply with Reg D requirements. Issuer may submit a different project or reapply with significant changes to this offering. ``` 3. Confirm rejection **Result:** * Project status changes to "rejected" * Project cannot be edited or resubmitted * Issuer can view rejection reason * Issuer must create new project if desired **Review Timeline Best Practices** * **Acknowledge receipt**: Within 1 business day * **Initial review**: Within 3 business days * **Final decision**: Within 7 business days * **Expedited review**: Available for pre-vetted issuers #### 7.6 Organization Change Request Review **Accessing Change Requests** 1. Navigate to **Admin → Organizations** 2. Click **Change Requests** tab 3. View pending requests **Change Request Details** Each request shows: * Organization name * Field to be changed (Company Name or Company Address) * Current value * Requested new value * Supporting documentation link * Requested by (issuer admin name) * Request date **Reviewing a Change Request** **Step 1: Review Documentation** * Click on supporting document link * Verify legitimacy of documentation * Common documents include: * Certificate of Amendment * Board Resolution * Updated Articles of Incorporation * Government registration documents * Legal opinion letter **Step 2: Verify the Change** * Cross-reference with government databases * Verify signatures and notarization * Ensure documentation is recent * Check consistency across documents **Step 3: Make a Decision** **To Approve:** 1. Click **Approve** button 2. Add admin notes (optional): ``` Change approved. Certificate of Amendment verified with [State] Secretary of State. File number: [123456]. Company name officially changed on [date]. ``` 3. Confirm approval **Result:** * Organization field is automatically updated * Change request status: "approved" * Issuer receives approval notification * Change is logged in audit trail **To Reject:** 1. Click **Reject** button 2. Add admin notes (required): ``` Change request rejected. Reasons: 1. Submitted Certificate of Amendment appears to be incomplete (missing page 2). 2. Document is not notarized as required by [State] law. 3. Company name requested is already in use by another entity in our system. Please resubmit with complete, notarized documentation. ``` 3. Confirm rejection **Result:** * Organization field remains unchanged * Change request status: "rejected" * Issuer can view rejection reason * Issuer may submit a new change request **Change Request Best Practices** **For Company Name Changes:** * Verify with state/country business registry * Check for trademark conflicts * Ensure consistency across all legal documents * Update all related project materials **For Address Changes:** * Verify new address is legitimate business location * Confirm address with utility or lease documentation * Update any regulatory filings * Ensure compliance with jurisdiction requirements #### 7.7 Platform Security Monitoring **Accessing Security Dashboard** 1. Navigate to **Admin → Security** 2. View security monitoring panels **Key Metrics Displayed:** * Failed login attempts * Suspicious activity alerts * API rate limit violations * Unusual access patterns * Data export events **Audit Log Access** View comprehensive audit logs: 1. Navigate to **Admin → Audit Logs** 2. Filter by: * Date range * User * Event type * Entity type * Action **Logged Events Include:** * User authentication events * Role assignments * Project submissions/approvals * Organization changes * Change request actions * Admin actions * Data access (sensitive information) **Audit Log Details:** * Timestamp * User who performed action * Action type * Entity affected * IP address * User agent * Event details (JSON) **Responding to Security Incidents** If suspicious activity is detected: 1. **Investigate**: Review audit logs for the user/entity 2. **Assess**: Determine severity and scope 3. **Act**: Suspend account if necessary 4. **Document**: Record incident details 5. **Notify**: Contact affected parties if needed #### 7.8 Platform Settings Management Platform admins can configure global platform settings: 1. Navigate to **Admin → Settings** 2. Modify settings as needed **Configurable Settings:** * Minimum investment thresholds * KYC/AML requirements * Investor accreditation requirements * Document retention policies * Fee structures * Email notification templates * Platform branding * Feature flags *** # Issuer Admin Functions #### 8.1 Issuer Dashboard Overview After logging in as an issuer admin, you'll see your personalized dashboard: **Dashboard Components:** * **Organization Selector** (if managing multiple organizations) * **Projects Overview** (draft, submitted, approved counts) * **Recent Activity Feed** * **Quick Actions** (Create Project, Upload Documents) * **Analytics Widgets** (total raised, investor count, etc.) * **Notifications Center** #### 8.2 Organization Selection & Switching If you're an admin for multiple organizations, you'll see an organization switcher in the sidebar: **How to Switch Organizations:** 1. Look for the organization dropdown in the sidebar 2. Current organization is displayed with a building icon 3. Click to expand dropdown 4. Select the organization you want to manage 5. Dashboard and all views update to show selected organization's data **Important Notes:** * You can only view projects for the currently selected organization * Switching organizations refreshes all data * Your selection is remembered across sessions * Each organization has separate data and permissions #### 8.3 Project Management Dashboard Navigate to **Projects** to view all your organization's projects: **Project List Features:** * **Tabbed View**: All, Draft, Submitted, Approved, Rejected * **Search**: Search by project name * **Filters**: Filter by asset class, status, date range * **Sort**: Sort by date, name, status, raised amount **Project Cards Display:** * Project name and tagline * Hero image * Status badge * Funding progress bar * Key metrics (target amount, raised amount) * Action buttons (View, Edit, Revoke, Submit, Delete) **Available Actions by Status:** | Status | Available Actions | | ------------------ | --------------------------------- | | Draft | Edit, Delete, Submit for Approval | | Submitted | View, Revoke | | Approved | View, Revoke | | Revision Requested | Edit, Re-submit | | Rejected | View (read-only), Delete | #### 8.4 Investor Management View and manage investors in your projects: 1. Navigate to **Investors** in issuer dashboard 2. View list of all investors across your projects **Investor Information Displayed:** * Investor name and email * Projects invested in * Total investment amount * Investment date * KYC status * Token allocation **Investor Management Actions:** * View detailed investor profile * Filter by project * Export investor list * View transaction history * Check KYC/AML compliance status **Communication with Investors:** * Send project updates (via email integration) * Share important documents * Notify of distributions * Respond to investor inquiries #### 8.5 Document Management Manage project-related documents: 1. Navigate to project detail page 2. Click **Documents** tab **Document Types:** * Offering Memorandum * Subscription Agreement * Operating Agreement * Financial Reports * Property Appraisals * Legal Opinions * Compliance Certificates **Uploading Documents:** 1. Click **Upload Document** button 2. Select document type from dropdown 3. Add title and description 4. Choose file from computer 5. Set visibility level: * **Admin Only**: Only visible to issuer admins and platform admins * **Investors Only**: Visible to investors in this project * **Public**: Visible to all users browsing the project 6. Click **Upload** **Document Versioning:** * Upload new versions of existing documents * Version number automatically increments * Previous versions remain accessible * Change log tracks who uploaded what when **Best Practices:** * Upload documents before submitting project for approval * Keep documents up to date * Use clear, descriptive titles * Set appropriate visibility levels * Version important documents rather than replacing #### 8.6 Analytics & Reporting Access detailed analytics for your organization: 1. Navigate to **Analytics** in issuer dashboard **Available Reports:** * **Fundraising Progress**: Visual charts of capital raised * **Investor Demographics**: Breakdown by location, investment size * **Project Performance**: Compare performance across projects * **Token Distribution**: Track token allocation and distribution * **Transaction History**: All investment transactions * **Revenue Projections**: Based on current commitments **Export Options:** * Export to CSV * Export to PDF * Schedule automated reports (email delivery) #### 8.7 Organization Settings Management Manage your organization's profile and settings: 1. Navigate to **Settings → Organization** **Editable Fields:** * Contact email * Phone number * Website URL * Company description * Logo (upload new) * Social media links * Legal structure details **Locked Fields (Require Change Request):** * Company name → Click "Request Change" button * Company address → Click "Request Change" button **Team Management:** * View all team members (if multi-user support enabled) * Invite additional team members * Manage team member permissions #### 8.8 Notifications Management Configure how you receive notifications: 1. Navigate to **Settings → Notifications** **Notification Types:** * Project status changes (approved, rejected, revision requested) * New investor commitments * Document uploads by investors * Platform admin messages * Compliance deadlines * System announcements **Delivery Channels:** * Email notifications * In-app notifications * SMS (if enabled) **Frequency Settings:** * Real-time (immediate) * Daily digest * Weekly summary *** # Investor Portal #### 9.1 Investor Dashboard The investor dashboard provides a comprehensive view of your investment activity: **Dashboard Widgets:** * **Portfolio Summary**: Total invested, current value, returns * **Active Investments**: List of projects you've invested in * **Recommended Projects**: Personalized project recommendations based on your investor profile * **Recent Activity**: Transaction history and project updates * **Upcoming Distributions**: Scheduled dividend/distribution payments #### 9.2 Browsing Projects **Accessing the Marketplace:** 1. Navigate to **Marketplace** or **Projects** 2. View all approved (live) projects **Project Listing Features:** * **Grid or List View**: Toggle between visual grid and detailed list * **Search Bar**: Search by project name, location, asset type * **Filters**: * Asset class (Real Estate, Infrastructure, etc.) * Property type (Office, Retail, Residential, etc.) * Minimum investment range * Target IRR range * Location/jurisdiction * Investment term * **Sort Options**: * Newest first * Ending soon * Highest IRR * Lowest minimum investment * Alphabetical **Project Preview Cards Show:** * Hero image * Project name and location * Target IRR and annual return * Funding progress (% funded) * Minimum investment * Days remaining * Quick stats (property type, investment term) #### 9.3 Viewing Project Details Click on any project to view comprehensive details: **Overview Tab** * Full project description * Location with map * Key highlights (bullet points) * Investment highlights * Exit strategy * Property/asset features **Financials Tab** * Purchase price * Appraised value * Expected exit value * NOI (Net Operating Income) * Cap rate * Target IRR * Target annual return * Investment term * Use of funds breakdown (visual chart) * Projected yield breakdown * Historical performance (if applicable) **Token Classes Tab** * Available token classes (e.g., Class A, Class B) * Price per token * Minimum and maximum investment * Voting rights * Transferability * Lockup period * Distribution frequency * Projected yield * Asset backing details * Secondary markets (if available) **Documents Tab** * Offering Memorandum * Subscription Agreement * Financial Reports * Property Appraisals * Legal Opinions * Other supporting documents * Download or view in-browser **Gallery Tab** * High-resolution property images * Virtual tour (if available) * Floor plans * Renderings * Video walkthrough **Location Tab** * Interactive map * Nearby amenities * Neighborhood information * Transportation access #### 9.4 Understanding Investment Metrics **Key Metrics Explained:** **IRR (Internal Rate of Return):** * The annualized return rate considering all cash flows * Higher IRR indicates better projected performance * Industry standard: 8-15% for real estate **Cap Rate (Capitalization Rate):** * NOI divided by property value * Indicates annual return based on income * Higher cap rate = higher income relative to price **NOI (Net Operating Income):** * Annual rental income minus operating expenses * Does NOT include debt service or capital expenses * Key indicator of property profitability **Target Annual Return:** * Expected return per year * May include income distributions + appreciation * Check if this is gross or net return **Investment Term:** * How long your capital is committed * Typical terms: 3-7 years for real estate * Consider your liquidity needs **Lockup Period:** * Period when tokens cannot be transferred/sold * Protects against early redemptions * Typical: 6-24 months #### 9.5 Making Investment Commitments **Prerequisites Before Investing:** * ✅ Complete investor discovery process * ✅ Have investor profile approved * ✅ Pass accredited investor verification (if required) * ✅ Complete KYC/AML verification * ✅ Link a wallet address **Investment Process:** **Step 1: Review Project Thoroughly** * Read offering memorandum * Review all financial projections * Understand risks * Consult with financial advisor (recommended) **Step 2: Select Token Class** * Choose which token class to invest in * Review terms specific to that class **Step 3: Specify Investment Amount** * Enter desired investment amount * System validates against min/max limits * Calculate number of tokens you'll receive * Review fees and total cost **Step 4: Review Legal Documents** * Read subscription agreement * Acknowledge risk disclosures * Sign electronically **Step 5: Make Payment** * Choose payment method * Transfer funds (bank wire, crypto, etc.) * Wait for payment confirmation **Step 6: Receive Confirmation** * Investment recorded on blockchain * Tokens allocated to your wallet * Confirmation email sent * Investment appears in portfolio #### 9.6 Managing Your Portfolio **Portfolio Dashboard Shows:** * All your active investments * Total invested capital * Current portfolio value * Realized and unrealized returns * Upcoming distribution schedule * Historical transactions **Per-Investment Details:** * Project name and image * Amount invested * Tokens held * Current value * Total return (%) * Distributions received * Next distribution date **Portfolio Actions:** * View transaction history * Download tax documents * Track distributions * Access project updates from issuers * Transfer tokens (if allowed and lockup expired) #### 9.7 Receiving Distributions **Distribution Types:** * **Income Distributions**: Regular cash flow from asset operations (rent, tolls, etc.) * **Capital Distributions**: Return of capital from asset sales or refinancing * **Liquidation Proceeds**: Final distribution at project exit **Distribution Process:** 1. Issuer declares distribution 2. You receive notification 3. Distribution is calculated based on your token holdings 4. Funds are transferred to your linked account 5. Transaction is recorded in your portfolio **Tax Reporting:** * Annual tax documents (1099, K-1, etc.) * Distribution breakdown by type * Downloadable from portfolio *** # Investor Registration & Onboarding This onboarding section will guide you through the sign-up and sign-in processes for accessing your Treem Finance account. The steps are straightforward, and by the end, you'll be ready to start using the platform. ### 10.1 Creating an Investor Account **Step 1**: Visit the Treem platform at or follow the link provided and click the ‘**Sign Up**’ button to create a new account.
**Step 2**: Enter the required details in the ‘**Registration**’ Form.
FieldsDescription
FieldsDescription
First NameEnter your legal given name as it appears in your photo ID document
Last NameProvide your legal family name or surname as it appears in your photo ID document
Email AddressEnter a valid email address that will be used for communication, notifications, and Treem account verification
Phone NumberInput a contact number, including the country code if applicable, to receive updates or verification messages
PasswordCreate a strong and secure password for your account, adhering to any specified requirements (e.g., minimum length, use of special characters)
Re-type PasswordConfirm your password by re-entering it to ensure accuracy and match with the original entry
Review and Tick the **Terms of Service** and **Privacy Policy** checkbox to confirm your agreement with the Treem.
**Step 3**: Click the ‘**Sign Up**’ button to proceed.
Your Treem Finance account has been successfully created. ## Sign In **Step 1**: Visit the Treem platform's login screen and enter your **Email Address** and **Password** in the appropriate fields.

**Step 2**: Click the ‘**Login**’ button to access the platform.
**Step 3**: After logging into the platform you will be redirected to Treem’s **dashboard** page.
#### 10.2 Investor Discovery Questionnaire After creating your account, you'll be prompted to complete the **Investor Discovery** process. This comprehensive questionnaire helps: * Assess your investment profile * Determine suitability for tokenized assets * Personalize project recommendations * Ensure regulatory compliance **The questionnaire consists of 9 steps:** **Step 1: Welcome & Introduction** * Overview of the discovery process * Explanation of why this information is needed * Estimated time to complete (15-20 minutes) * Option to save progress and return later **Step 2: Personal Profile** * **Full Name**: Legal name as it appears on government ID * **Date of Birth**: Must be 18+ to invest * **Marital Status**: Single, Married, Divorced, Widowed * **Number of Dependents**: Financial obligation consideration * **Employment Status**: * Employed full-time * Employed part-time * Self-employed * Retired * Unemployed * Student **Step 3: Financial Snapshot** * **Annual Income**: Gross annual income in USD * Less than $50,000 * $50,000 - $100,000 * $100,000 - $200,000 * $200,000 - $500,000 * $500,000+ * **Monthly Expenses**: Average monthly expenses * **Total Assets**: Sum of all assets (real estate, investments, cash, etc.) * **Total Liabilities**: Sum of all debts (mortgage, loans, credit cards, etc.) * **Net Worth**: Automatically calculated (Assets - Liabilities) **Step 4: Investment Experience** * **Years of Investment Experience**: * None (new investor) * 1-3 years * 3-5 years * 5-10 years * 10+ years * **Familiar Asset Classes**: Select all that apply * Stocks/Equities * Bonds/Fixed Income * Real Estate * Cryptocurrencies * Commodities * Private Equity * Venture Capital * **Past Investments**: Types of investments you've made * Public stocks * Real estate (direct ownership) * REITs * Crowdfunding * Angel investing * Cryptocurrencies * None yet **Step 5: Investment Objectives** * **Primary Investment Goal**: * Capital preservation * Income generation * Balanced growth * Aggressive growth * Speculation * **Target Investment Amount**: How much you plan to invest in tokenized assets * $5,000 - $25,000 * $25,000 - $100,000 * $100,000 - $500,000 * $500,000+ * **Target Timeframe**: By when do you plan to invest this amount? * Within 3 months * 3-6 months * 6-12 months * 12+ months **Step 6: Risk Tolerance Assessment** Interactive questionnaire with 5-7 scenario-based questions: **Example Questions:** 1. "If your investment declined 20% in value in the first year, you would:" * Sell immediately to prevent further losses * Sell some to reduce exposure * Hold and wait for recovery * Buy more at the lower price 2. "Which statement best describes your risk tolerance?" * I cannot accept any loss of principal * I can accept minimal losses for stable returns * I can accept moderate losses for better returns * I can accept significant losses for high growth potential **Risk Score Calculation:** * Based on your answers, a risk score is calculated (1-10) * Score determines suitable investment types * 1-3: Conservative (low-risk assets) * 4-6: Moderate (balanced risk/reward) * 7-10: Aggressive (high-risk, high-reward) **Step 7: Liquidity & Time Horizon** * **Preferred Liquidity**: * Highly liquid (can sell anytime) * Moderately liquid (can sell within weeks) * Low liquidity acceptable (locked for months) * Illiquid acceptable (locked for years) * **Investment Horizon**: How long can you keep funds invested? * Short-term (< 1 year) * Medium-term (1-3 years) * Long-term (3-5 years) * Very long-term (5+ years) * **Emergency Fund**: Do you have 3-6 months of expenses saved separately? * Yes, fully funded * Partially funded * No emergency fund **Step 8: Tax & Compliance** * **Tax Residency**: Country of tax residence * **Are you a U.S. Person?**: Yes/No (for FATCA compliance) * **Accredited Investor Status**: * Yes, I qualify as accredited * No, I do not qualify * Unsure (will verify later) **Accredited Investor Criteria (U.S.):** * Income: $200K+ individual or $300K+ joint for last 2 years * Net Worth: $1M+ excluding primary residence * Professional Certifications: Series 7, 65, or 82 licenses **Step 9: Summary & Confirmation** * Review all your answers * Edit any section if needed * Confirm information accuracy * Submit investor profile **After Submission:** * Profile is saved to your account * You receive a risk profile summary * Projects are recommended based on your profile * You can browse all projects but may see suitability warnings #### 10.3 Editing Your Investor Profile You can update your investor profile at any time: 1. Navigate to **Settings → Investor Profile** 2. Click **Edit Profile** 3. Update any section 4. Click **Save Changes** **When to Update:** * Significant change in financial situation * Change in investment objectives * Change in employment status * Annual review (recommended) #### 10.4 KYC (Know Your Customer) Requirements To invest in projects, you must complete KYC verification: **Required Documents:** * **Government-issued Photo ID**: * Passport, or * Driver's license, or * National ID card * **Proof of Address** (issued within last 3 months): * Utility bill * Bank statement * Tax document * Lease agreement **KYC Verification Process:** 1. Navigate to **Settings → Verification** 2. Click **Start KYC Verification** 3. Upload required documents 4. Submit for review 5. Wait for verification (typically 1-3 business days) 6. Receive approval or request for additional documentation **KYC Status Levels:** * **Unverified**: Cannot invest * **Pending**: Under review, cannot invest yet * **Verified**: Can invest up to certain limits * **Fully Verified**: Can invest without restrictions #### 10.5 Accredited Investor Verification Some projects are only available to accredited investors. To verify: **Option 1: Income Verification** * Upload last 2 years of tax returns * Provide W-2s or 1099s * Submit through secure portal **Option 2: Net Worth Verification** * Provide recent bank statements * Real estate appraisals * Investment account statements * Debt documentation * Third-party verification service **Option 3: Professional Certification** * Upload FINRA license (Series 7, 65, or 82) * Professional verification **Verification Timeline:** * Manual review: 3-5 business days * Third-party service: 1-2 business days #### 10.6 Linking Your Wallet To receive tokens, link a compatible cryptocurrency wallet: **Supported Wallets:** * MetaMask * WalletConnect * Coinbase Wallet * Ledger (hardware wallet) * Trust Wallet **How to Link:** 1. Navigate to **Settings → Wallets** 2. Click **Connect Wallet** 3. Choose your wallet provider 4. Approve connection in wallet app 5. Wallet address is saved to your profile **Security Best Practices:** * Use a hardware wallet for large investments * Never share your private keys * Keep backup of recovery phrase * Enable 2FA on wallet if available # Security & Compliance #### 11.1 Data Protection & Privacy **How Your Data is Protected:** * **Encryption**: All data encrypted in transit (TLS 1.3) and at rest (AES-256) * **Access Controls**: Role-based access control (RBAC) limits data access * **Audit Logging**: All data access is logged and monitored * **Regular Backups**: Daily encrypted backups with disaster recovery plan * **GDPR Compliance**: Right to access, rectify, and delete personal data **Personal Information Collected:** * Identity information (name, date of birth) * Contact information (email, phone) * Financial information (income, assets, net worth) * Investment history and preferences * Government ID documents (for KYC) * Wallet addresses **How Your Information is Used:** * Verify your identity (KYC/AML) * Assess investment suitability * Process transactions * Send project updates and notifications * Comply with regulatory requirements * Improve platform services **Your Privacy Rights:** * Access your personal data * Correct inaccurate data * Request data deletion (subject to legal retention) * Export your data * Opt-out of marketing communications #### 11.2 Access Controls & Permissions **User Authentication:** * Password requirements: 12+ characters, uppercase, lowercase, number, special character * Multi-factor authentication (MFA) available * Session timeout after 30 minutes of inactivity * Failed login attempt lockout after 5 attempts **Role-Based Access Control:** | Data Type | Platform Admin | Issuer Admin | Investor | | ---------------------- | -------------- | ------------ | ------------- | | All organizations | Full access | Own org only | No access | | All projects | Full access | Own org only | Approved only | | User PII | Full access | No access | Own only | | Financial transactions | Full access | Own org only | Own only | | Audit logs | Full access | No access | No access | | KYC documents | Full access | No access | Own only | #### 11.3 Audit Trails & Logging **All actions are logged, including:** * User authentication (login, logout, failed attempts) * Role assignments and changes * Project creation, submission, approval/rejection * Organization changes and change requests * Document uploads and downloads * Investment transactions * Data exports * Admin actions **Log Retention:** * Security logs: 7 years * Transaction logs: 10 years (regulatory requirement) * Access logs: 3 years * Session logs: 1 year **Audit Log Access:** * Platform admins: Full access to all logs * Issuer admins: Access to own organization's logs * Investors: Access to own activity logs * Available via **Settings → Security → Activity Log** #### 11.4 Regulatory Compliance **Securities Regulations:** * **Reg D (506b, 506c)**: Private placement exemptions * **Reg A+**: Mini-IPO for up to $75M * **Reg CF**: Crowdfunding exemption up to $5M * All offerings comply with applicable securities laws **KYC/AML Compliance:** * Know Your Customer (KYC) verification required for all investors * Anti-Money Laundering (AML) screening * Politically Exposed Persons (PEP) checks * Sanctions list screening (OFAC, EU, UN) * Ongoing transaction monitoring **Accredited Investor Verification:** * Income verification ($200K+ individual, $300K+ joint) * Net worth verification ($1M+ excluding primary residence) * Professional certification (Series 7, 65, 82) * Third-party verification services integrated **Data Privacy Regulations:** * **GDPR** (EU General Data Protection Regulation) * **CCPA** (California Consumer Privacy Act) * **PIPEDA** (Canadian privacy law) * Data protection officer appointed * Privacy by design principles **Investor Suitability:** * Risk tolerance assessment required * Investment profile matching * Suitability warnings for high-risk investments * Accreditation requirements enforced #### 11.5 Smart Contract Security **Blockchain & Smart Contracts:** * Smart contracts audited by third-party security firms * Multi-signature wallets for issuer funds * Time-locked token transfers * Emergency pause functionality * Transparent on-chain transactions **Supported Blockchains:** * Ethereum (ERC-20, ERC-1400 security tokens) * Polygon (lower gas fees) * Other EVM-compatible chains **Token Standards:** * ERC-1400: Security token standard with compliance features * Transfer restrictions based on investor accreditation * Automated compliance checks * Dividend distribution automation #### 11.6 Incident Response **Security Incident Response Plan:** 1. **Detection**: Automated monitoring alerts on suspicious activity 2. **Assessment**: Security team evaluates severity and scope 3. **Containment**: Immediate action to prevent further damage 4. **Eradication**: Remove threat and vulnerabilities 5. **Recovery**: Restore normal operations 6. **Notification**: Inform affected users within 72 hours (if required) 7. **Post-Incident Review**: Document lessons learned and improve processes **How to Report Security Issues:** * Email: * In-app: Settings → Security → Report Issue * Bug bounty program for responsible disclosure #### 11.7 Best Practices for Users **For All Users:** * ✅ Use strong, unique passwords * ✅ Enable multi-factor authentication (MFA) * ✅ Never share your login credentials * ✅ Log out when using shared computers * ✅ Keep your email account secure * ✅ Beware of phishing emails * ✅ Verify URLs before entering credentials * ✅ Review your activity log regularly **For Issuer Admins:** * ✅ Limit team member access to necessary functions only * ✅ Review and approve all project submissions carefully * ✅ Keep organization information up to date * ✅ Secure all uploaded documents * ✅ Monitor investor activity for anomalies **For Investors:** * ✅ Use hardware wallets for large holdings * ✅ Keep wallet recovery phrases offline and secure * ✅ Verify token contract addresses before transactions * ✅ Be cautious of too-good-to-be-true returns * ✅ Review all legal documents before investing * ✅ Never send funds to unverified addresses # Additional Features #### 12.1 Search Functionality **Global Search:** * Search bar available in header (platform admins) * Search across projects, organizations, users * Auto-complete suggestions * Recent searches saved **Project Search (Investors):** * Search by project name, location, or keywords * Filters and search work together * Results update in real-time #### 12.2 Notifications System **Notification Types:** * System announcements * Project status changes * Investment confirmations * Distribution payments * Document uploads * KYC status updates * Security alerts **Notification Delivery:** * In-app notification center (bell icon) * Email notifications * SMS (optional, for critical alerts) * Push notifications (if mobile app enabled) **Managing Notifications:** 1. Navigate to **Settings → Notifications** 2. Toggle notification types on/off 3. Choose delivery channels 4. Set frequency (real-time, daily digest, weekly) #### 12.3 Document Upload & Management **Supported File Types:** * PDF (recommended for legal documents) * DOCX, DOC (Microsoft Word) * XLSX, XLS (Microsoft Excel) * JPG, PNG (images) * ZIP (for multiple files) **File Size Limits:** * Maximum per file: 50 MB * Maximum total per project: 500 MB **Document Organization:** * Documents organized by project * Categorized by type (legal, financial, property, etc.) * Version control for updated documents * Search and filter by document name #### 12.4 Multi-Organization Support **For Issuer Admins Managing Multiple Organizations:** **Organization Switcher:** * Located in sidebar * Shows current organization with building icon * Click to view list of all organizations * Select to switch context **Data Isolation:** * Each organization's data is completely separate * Projects cannot be moved between organizations * Team members are organization-specific * Analytics and reports are per-organization **Benefits:** * Single login for multiple organizations * Easy switching between organizations * Consistent interface across organizations * Centralized notification management #### 12.5 Responsive Design & Mobile Access **Mobile Optimization:** * Fully responsive design works on all devices * Mobile-friendly navigation (hamburger menu) * Touch-optimized buttons and controls * Optimized images for mobile data usage **Tablet Support:** * Optimized layout for tablet screens * Touch gestures supported * Portrait and landscape orientation **Browser Compatibility:** * Chrome (recommended) * Firefox * Safari * Edge * Minimum browser versions: released within last 2 years #### 12.6 Data Export & Reporting **Export Options:** **For Issuer Admins:** * Export investor lists (CSV, Excel) * Export financial reports (PDF, Excel) * Export project data (JSON, CSV) * Export transaction history (CSV) **For Investors:** * Export portfolio data (CSV, Excel) * Export transaction history (CSV, PDF) * Export tax documents (PDF) * Export distribution history (CSV) **For Platform Admins:** * Export all data types * Bulk data exports * Scheduled automated exports * API access for custom integrations #### 12.7 Support & Help Center **Getting Help:** **Help Center:** * Navigate to **Support** or **Help** in main menu * Browse FAQ articles * Search knowledge base * Watch tutorial videos **Submitting a Support Ticket:** 1. Navigate to **Support → Contact Us** 2. Select issue category 3. Describe your issue 4. Attach screenshots (if relevant) 5. Submit ticket 6. Receive ticket number and email confirmation **Live Chat:** * Available during business hours * Click chat icon in bottom right * Connect with support agent * Chat history saved to your account **Email Support:** * General inquiries: * Technical issues: * Security issues: * Investment questions: **Response Times:** * Critical issues (security, transactions): 1 hour * High priority (account access, KYC): 4 hours * Normal priority (general questions): 24 hours * Low priority (feature requests): 3-5 business days #### 12.8 Platform Updates & Changelog **Staying Informed:** * Platform updates announced via email * Changelog available at **Help → What's New** * Major features highlighted in dashboard notifications * Maintenance windows announced 48 hours in advance **Release Schedule:** * Major releases: Quarterly * Minor updates: Monthly * Security patches: As needed * Maintenance: Sundays 2-4 AM EST # Glossary # FAQs # Introduction ## Governance Module Documentation Welcome to the Treem DAO Governance Module documentation. This comprehensive guide covers everything you need to know about participating in Treem DAO governance, from basic concepts to advanced smart contract interactions. ### Quick Navigation * 📖 Overview - Introduction to Treem DAO governance * 👤 User Guide - How to participate in governance * 📋 Proposals - Creating and managing proposals * 🔒 Staking System - Token staking and voting power * ⚙️ Admin Guide - Administrative governance controls * 🔧 Smart Contracts - Contract reference and deployment * 💻 Technical Integration - Developer resources * ❓ FAQ & Troubleshooting - Common questions and solutions ### Getting Started If you're new to Treem DAO governance, start with the Overview to understand the basic concepts, then follow the User Guide to begin participating. For developers and administrators, check out the Technical Integration and Admin Guide sections. ### Latest Updates * **Enhanced Staking System**: New 6-month and 12-month staking tiers * **Grant Proposals**: Special proposal type for funding requests * **Voting Rewards**: Earn TREEM tokens for active participation * **Smart Contract Deployment**: Production-ready governance contracts ### Support For additional support, please refer to our FAQ section or contact the Treem DAO community through our official channels. # Onboarding This onboarding section will guide you through the sign-up and sign-in processes for accessing your Treem Finance account. The steps are straightforward, and by the end, you'll be ready to start using the platform. ## Sign Up **Step 1**: Visit the Treem platform at or follow the link provided and click the ‘**Sign Up**’ button to create a new account.
**Step 2**: Enter the required details in the ‘**Registration**’ Form.
FieldsDescription
FieldsDescription
First NameEnter your legal given name as it appears in your photo ID document
Last NameProvide your legal family name or surname as it appears in your photo ID document
Email AddressEnter a valid email address that will be used for communication, notifications, and Treem account verification
Phone NumberInput a contact number, including the country code if applicable, to receive updates or verification messages
PasswordCreate a strong and secure password for your account, adhering to any specified requirements (e.g., minimum length, use of special characters)
Re-type PasswordConfirm your password by re-entering it to ensure accuracy and match with the original entry
Review and Tick the **Terms of Service** and **Privacy Policy** checkbox to confirm your agreement with the Treem.
**Step 3**: Click the ‘**Sign Up**’ button to proceed.
Your Treem Finance account has been successfully created. ## Sign In **Step 1**: Visit the Treem platform's login screen and enter your **Email Address** and **Password** in the appropriate fields.

**Step 2**: Click the ‘**Login**’ button to access the platform.
**Step 3**: After logging into the platform you will be redirected to Treem’s **dashboard** page.
# Dashboard # Governance ## Governance Module Documentation Welcome to the Treem DAO Governance Module documentation. This comprehensive guide covers everything you need to know about participating in Treem DAO governance, from basic concepts to advanced smart contract interactions. ### Quick Navigation * 📖 [Overview](/treem-dao/governance/governance-overview) - Introduction to Treem DAO governance * 👤 [User Guide](/treem-dao/governance/user-guide) - How to participate in governance * 📋 [Proposals](/treem-dao/governance/proposals) - Creating and managing proposals * 🔒 [Staking System](/treem-dao/governance/staking-system) - Token staking and voting power * ⚙️ [Admin Guide](/treem-dao/governance/admin-guide) - Administrative governance controls * 🔧 [Smart Contracts](/treem-dao/governance/smart-contracts) - Contract reference and deployment * 💻 Technical Integration - Developer resources * ❓ [FAQ & Troubleshooting](/treem-dao/governance/faq-and-troubleshooting) - Common questions and solutions ### Getting Started If you're new to Treem DAO governance, start with the Overview to understand the basic concepts, then follow the User Guide to begin participating. For developers and administrators, check out the Technical Integration and Admin Guide sections. ### Latest Updates * **Enhanced Staking System**: New 6-month and 12-month staking tiers * **Grant Proposals**: Special proposal type for funding requests * **Voting Rewards**: Earn TREEM tokens for active participation * **Smart Contract Deployment**: Production-ready governance contracts ### Support For additional support, please refer to our FAQ section or contact the Treem DAO community through our official channels. # Governance Overview ### Introduction Treem DAO operates as a decentralized autonomous organization where TREEM token holders can participate in governance decisions. The governance system is built on Ethereum using OpenZeppelin's Governor contracts and includes an enhanced staking mechanism for increased participation and security. ### Core Concepts #### TREEM Governance Token * **Symbol**: TREEM * **Total Supply**: 1,000,000,000 TREEM * **Standard**: ERC-20 with ERC-20Votes extension * **Network**: Ethereum #### Token Distribution | Allocation | Percentage | Amount | Purpose | | ------------------- | ---------- | ----------------- | -------------------------- | | Foundation Treasury | 40% | 400,000,000 TREEM | Operations and development | | Community Grants | 30% | 300,000,000 TREEM | Community funding | | Reserve Future Use | 15% | 150,000,000 TREEM | Strategic reserves | | Founders and Team | 15% | 150,000,000 TREEM | Team allocation | #### Governance Parameters * **Proposal Threshold**: 0.5% of total supply (5,000,000 TREEM) * **Voting Period**: 7 days (50,400 blocks) * **Voting Delay**: 1 day (7,200 blocks) * **Quorum**: 4% of total supply * **Execution Delay**: 2 days (timelock) ### Staking System #### Staking Tiers The governance system includes a tiered staking mechanism that determines voting rights and proposal creation privileges: **6-Month Staking Tier** * **Lock Period**: 180 days * **Benefits**: * Vote on general proposals * Vote on grant proposals * Earn voting rewards * **Requirements**: Minimum stake amount (configurable) **12-Month Staking Tier** * **Lock Period**: 365 days * **Benefits**: * All 6-month tier benefits * Create grant proposals * Higher voting reward multipliers * **Requirements**: Minimum stake amount (configurable) #### Voting Power Voting power is determined by: 1. **Staked Token Amount**: Direct correlation to staked TREEM tokens 2. **Delegation**: Users can delegate their voting power to other addresses 3. **Snapshot**: Voting power is calculated at proposal creation time ### Proposal Types #### General Proposals * **Purpose**: Protocol changes, parameter updates, general governance decisions * **Creation Requirements**: All stakers (6+ months) * **Voting Requirements**: All stakers (6+ months) * **Examples**: Protocol upgrades, treasury allocations, governance parameter changes #### Grant Proposals * **Purpose**: Funding requests for community projects * **Creation Requirements**: 12-month stakers only * **Voting Requirements**: All stakers (6+ months) * **Features**: Specified grant amount, recipient, and funding criteria ### Voting Rewards Active participation in governance is incentivized through a reward system: * **Base Reward**: 100 TREEM tokens per vote participation * **Source**: Treasury allocation * **Distribution**: Manual claim after voting * **Reset**: Vote count resets after claiming rewards * **Annual Cap**: Configurable per user to prevent abuse (50,000 TREEM tokens as of 01/05/2025) ### Smart Contract Architecture The governance system consists of several interconnected smart contracts: 1. **TreemGovernanceToken**: ERC-20 token with voting capabilities 2. **TreemGovernor**: Main governance contract for proposals and voting 3. **TreemStaking**: Staking contract with lock periods and tiers 4. **TimelockController**: Execution delay for approved proposals 5. **TreemVoteRewardTracker:** – manages per‑vote rewards and tracks participation. ### Security Features * **Timelock Protection**: 2-day delay for proposal execution * **Quorum Requirements**: Minimum participation for proposal validity * **Snapshot Voting**: Prevents vote manipulation through token transfers * **Access Controls**: Role-based permissions for administrative functions * **Reentrancy Protection**: Secure against common smart contract vulnerabilities ### Getting Started 1. **Acquire TREEM Tokens**: Purchase through the DAO's token sale or exchanges 2. **Connect Wallet**: Use MetaMask or compatible Ethereum wallet 3. **Stake Tokens**: Choose 6-month or 12-month staking period 4. **Participate**: Vote on proposals and earn rewards 5. **Create Proposals**: Submit your own proposals (12-month stakers only) ### Next Steps * Read the User Guide for step-by-step instructions * Learn about Staking to maximize your participation * Explore Proposals to understand the proposal lifecycle # User Guide This guide walks you through participating in Treem DAO governance as a regular user. ### Prerequisites * Ethereum wallet (MetaMask recommended) * TREEM tokens * ETH for transaction fees ### Step 1: Connect Your Wallet 1. Visit the Treem DAO platform 2. Click "Connect Wallet" in the top right 3. Select MetaMask or your preferred wallet 4. Approve the connection request 5. Ensure you're on the correct network (Ethereum Mainnet) ### Step 2: Stake Your Tokens Staking tokens is required to participate in governance: #### Choose Your Staking Tier **6-Month Staking:** * Stake for 180 days * Vote on all proposals * Earn voting rewards **12-Month Staking:** * Stake for 365 days * Vote on all proposals * Create grant proposals * Higher reward multipliers #### Staking Process 1. Navigate to the "Staking" section 2. Enter the amount of TREEM tokens to stake 3. Select your preferred lock period (6 or 12 months) 4. Click "Stake Tokens" 5. Confirm the transaction in your wallet 6. Wait for transaction confirmation #### Important Notes * Tokens are locked for the entire staking period * You cannot unstake before the lock period expires * Staking automatically delegates voting power to yourself * You can delegate to another address if desired ### Step 3: Participate in Voting #### Finding Active Proposals 1. Go to the "Governance" section 2. Browse active proposals in the "Active Voting" tab 3. Click on any proposal to view details #### Voting Process 1. Read the proposal title, summary, and full description 2. Review any attached resources or documentation 3. Consider the potential impact on the DAO 4. Choose your vote: * **For**: Support the proposal * **Against**: Oppose the proposal * **Abstain**: Neutral position (not implemented in current version) 5. Optionally add a comment explaining your reasoning 6. Click "Cast Vote" 7. Confirm the transaction in your wallet #### Voting Power Your voting power equals your staked token amount at the time the proposal was created. You can check your voting power in the governance dashboard. ### Step 4: Claim Voting Rewards Earn TREEM tokens for participating in governance: #### Reward System * **Base Reward**: 5 TREEM per vote cast * **Annual Cap**: 500 TREEM per user per year * **Source**: Foundation treasury #### Claiming Process 1. Navigate to the "Rewards" section 2. View your accumulated voting rewards 3. Click "Claim Rewards" 4. Confirm the transaction 5. Rewards are transferred to your wallet #### Reward Tracking * Participation counter tracks votes cast * Counter resets to zero after claiming * Annual cap prevents excessive rewards * Claim anytime after voting ### Step 5: Create Proposals (12-Month Stakers Only) If you have 12-month staked tokens, you can create grant proposals: #### Grant Proposal Creation 1. Go to "Governance" → "Create Proposal" 2. Select "Grant Proposal" type 3. Fill in required information: * **Title**: Clear, descriptive title * **Summary**: Brief overview of the request * **Description**: Detailed explanation * **Grant Amount**: Requested TREEM amount * **Recipient**: Recipient name or organization 4. Review your proposal 5. Submit the proposal 6. Confirm the transaction #### Proposal Guidelines * Be specific about funding use * Include timeline and milestones * Provide background information * Specify expected outcomes * Follow community guidelines ### Step 6: Monitor Your Activity #### Dashboard Overview Your governance dashboard shows: * Current staking status * Active stake locks * Time remaining until unlock * Voting power * Participation history * Accumulated rewards #### Stake Management * View all active stakes * Monitor unlock timers * Unstake when lock period expires * Track staking rewards #### Transaction History * Review all governance-related transactions * Track proposal votes * Monitor reward claims * View staking activities ### Best Practices #### Informed Voting * Read proposals thoroughly * Research the impact of decisions * Participate in community discussions * Consider long-term effects on the DAO #### Security * Keep your wallet secure * Verify transaction details before signing * Don't share private keys * Use hardware wallets for large amounts #### Community Engagement * Join Discord/Telegram discussions * Follow official announcements * Provide feedback on proposals * Share your expertise ### Common Issues and Solutions #### Transaction Failures **Problem**: Transaction fails or gets stuck**Solution**: * Check gas fees and increase if necessary * Ensure sufficient ETH balance * Try again during lower network congestion #### Voting Power Issues **Problem**: Voting power shows as zero**Solution**: * Verify tokens are staked * Check if delegation is set correctly * Ensure stake was active when proposal was created #### Reward Claiming **Problem**: Cannot claim rewards**Solution**: * Verify you have voted on proposals * Check if annual cap is reached * Ensure treasury has sufficient balance ### Next Steps * Learn about Staking in detail * Understand Proposals lifecycle * Explore Technical Integration for developers # Proposals Proposals are the core mechanism for making decisions in Treem DAO. This guide covers the proposal lifecycle, types, creation process, and voting procedures. ### Proposal Types #### General Proposals **Purpose**: Protocol changes, parameter updates, general governance decisions **Examples**: * Updating governance parameters (voting period, quorum) * Protocol upgrades and improvements * Treasury allocation strategies * Partnership approvals * Community guidelines changes **Requirements**: * **Creation**: Must hold proposal threshold (5,000,000 TREEM) * **Voting**: All stakers (6+ months) can vote * **Execution**: Requires majority approval and quorum #### Grant Proposals **Purpose**: Funding requests for community projects and initiatives **Examples**: * Development grants for new features * Community event funding * Research project funding * Marketing and outreach initiatives * Infrastructure improvements **Requirements**: * **Creation**: 12-month stakers only * **Voting**: All stakers (6+ months) can vote * **Special Fields**: Grant amount, recipient, detailed budget ### Proposal Lifecycle #### 1. Creation Phase **Duration**: Instant **Activities**: * Proposal submitted to blockchain * Proposal ID generated * Initial state: "Pending" #### 2. Voting Delay **Duration**: 1 day (7,200 blocks) **Purpose**: * Allow community to review proposal * Prevent last-minute vote manipulation * Enable stake adjustments before voting #### 3. Active Voting **Duration**: 7 days (50,400 blocks) **Activities**: * Community members cast votes * Voting power calculated at proposal creation time * Vote tallies updated in real-time #### 4. Voting Results **Outcomes**: * **Succeeded**: Majority approval + quorum met * **Defeated**: Majority rejection or quorum not met * **Queued**: Successful proposal queued for execution #### 5. Execution Delay (Timelock) **Duration**: 2 days (for successful proposals) **Purpose**: * Security measure against malicious proposals * Allow time for emergency interventions * Transparent execution timeline #### 6. Execution **Final States**: * **Executed**: Proposal actions performed * **Expired**: Execution window missed * **Cancelled**: Emergency cancellation (rare) ### Creating Proposals #### Prerequisites **For General Proposals**: * Hold at least 5,000,000 TREEM tokens * Tokens must be available at proposal creation time **For Grant Proposals**: * Active 12-month stake * Tokens locked for at least 365 days #### Proposal Creation Process 1. **Navigate to Creation Interface** * Go to Governance → Create Proposal * Select proposal type (General or Grant) 2. **Fill Proposal Details** **Required Fields**: * **Title**: Clear, descriptive title (max 100 characters) * **Summary**: Brief overview (max 500 characters) * **Description**: Detailed explanation (no limit) **Grant-Specific Fields**: * **Grant Amount**: Requested TREEM tokens * **Recipient**: Individual or organization name * **Budget Breakdown**: Detailed fund allocation 3. **Add Supporting Materials** * **Resources**: Links to relevant documents * **Actions**: Smart contract calls (advanced) * **Timeline**: Project milestones and deadlines 4. **Review and Submit** * Verify all information * Estimate gas costs * Submit proposal transaction * Confirm in wallet #### Best Practices for Proposal Creation **Title Guidelines** * Be specific and clear * Include proposal type * Keep under 100 characters * Example: "Grant Proposal: Community Education Platform Development" **Summary Guidelines** * Explain the core proposal in 1-2 sentences * Include key metrics (amounts, timelines) * Make it scannable for quick understanding **Description Guidelines** * **Background**: Explain the problem or opportunity * **Solution**: Describe your proposed approach * **Impact**: Explain expected outcomes * **Timeline**: Provide clear milestones * **Budget**: Justify requested amounts (for grants) * **Team**: Introduce key contributors **Grant Proposal Template** ```markdown # Grant Proposal: [Project Name] ## Summary Brief 1-2 sentence description of the project and funding request. ## Background - Current situation/problem - Why this project is needed - Alignment with DAO goals ## Proposed Solution - Detailed project description - Technical approach - Deliverables and milestones ## Team - Team member backgrounds - Relevant experience - Past contributions to DAO ## Budget Breakdown | Item | Amount (TREEM) | Justification | |------|---------------|---------------| | Development | X,XXX | Description | | Marketing | X,XXX | Description | | Operations | X,XXX | Description | | **Total** | **X,XXX** | | ## Timeline - Month 1-2: Initial development - Month 3-4: Testing and refinement - Month 5-6: Launch and promotion ## Success Metrics - Specific, measurable outcomes - Timeline for evaluation - Reporting commitments ## Risk Assessment - Potential challenges - Mitigation strategies - Contingency plans ``` ### Voting Process #### Voting Mechanism **Vote Types**: * **For**: Support the proposal * **Against**: Oppose the proposal * **Abstain**: Neutral position (not implemented in current version) **Voting Power**: * Equal to staked TREEM tokens * Calculated at proposal creation time * Cannot be changed during voting period #### Casting Votes 1. **Navigate to Proposal** * Go to Governance → Active Proposals * Click on proposal to view details 2. **Review Proposal** * Read title, summary, and full description * Check supporting resources * Consider community discussions 3. **Cast Vote** * Select vote type (For/Against) * Optionally add reasoning comment * Click "Cast Vote" * Confirm transaction in wallet 4. **Verify Vote** * Check vote appears in proposal * Verify voting power counted correctly * Track in personal voting history #### Voting Strategy **Research Phase**: * Read proposal thoroughly * Check creator's background * Review community feedback * Consider long-term implications **Decision Framework**: * Alignment with DAO mission * Financial impact assessment * Technical feasibility * Community benefit analysis ### Proposal States #### State Definitions | State | Description | Duration | | ------------- | ---------------------------------------- | -------- | | **Pending** | Proposal created, voting not yet active | 1 day | | **Active** | Voting period in progress | 7 days | | **Succeeded** | Majority approval + quorum met | - | | **Defeated** | Majority rejection or quorum not met | - | | **Queued** | Successful proposal queued for execution | 2 days | | **Executed** | Proposal actions completed | - | | **Cancelled** | Proposal cancelled (emergency only) | - | | **Expired** | Execution window missed | - | #### State Transitions ``` Created → Pending → Active → [Succeeded/Defeated] ↓ Succeeded → Queued → Executed ``` ### Quorum and Approval Requirements #### Quorum Calculation ``` Quorum = 4% of Total TREEM Supply Current Quorum = 40,000,000 TREEM (4% of 1B total supply) ``` #### Approval Threshold ``` Approval = For Votes > Against Votes Minimum Participation = Total Votes ≥ Quorum ``` #### Example Scenarios **Scenario 1 - Successful Proposal**: * For: 45,000,000 TREEM * Against: 15,000,000 TREEM * Total: 60,000,000 TREEM * Result: ✅ Succeeds (majority + quorum met) **Scenario 2 - Failed Quorum**: * For: 25,000,000 TREEM * Against: 10,000,000 TREEM * Total: 35,000,000 TREEM * Result: ❌ Defeated (quorum not met) **Scenario 3 - Majority Rejection**: * For: 20,000,000 TREEM * Against: 30,000,000 TREEM * Total: 50,000,000 TREEM * Result: ❌ Defeated (majority against) ### Advanced Features #### Proposal Actions Proposals can include executable actions: ```typescript interface ProposalAction { target: string; // Contract address value: bigint; // ETH value to send calldata: string; // Function call data } ``` **Example Actions**: * Update governance parameters * Transfer treasury funds * Upgrade smart contracts * Grant administrative roles #### Emergency Procedures **Emergency Cancellation**: * Multi-sig wallet can cancel malicious proposals * Used only for security threats * Requires transparent justification * Community review after cancellation ### Analytics and Tracking #### Proposal Metrics **Participation Metrics**: * Total votes cast * Unique voters * Voting power distribution * Participation rate by stake tier **Outcome Analysis**: * Proposal success rate * Average voting period * Quorum achievement rate * Execution success rate #### Individual Tracking **User Dashboard**: * Proposals created * Votes cast * Voting history * Reward earnings * Participation statistics ### Integration Points #### Database Schema ```sql -- Proposals table CREATE TABLE proposals ( id UUID PRIMARY KEY, title TEXT NOT NULL, summary TEXT, body TEXT, proposal_type TEXT DEFAULT 'general', grant_amount INTEGER, grant_recipient TEXT, status TEXT DEFAULT 'active', votes_for INTEGER DEFAULT 0, votes_against INTEGER DEFAULT 0, creator_id UUID NOT NULL, created_at TIMESTAMP DEFAULT NOW() ); -- Proposal votes table CREATE TABLE proposal_votes ( id UUID PRIMARY KEY, proposal_id UUID NOT NULL, user_id UUID NOT NULL, vote_type TEXT NOT NULL, voting_power INTEGER NOT NULL, created_at TIMESTAMP DEFAULT NOW() ); ``` #### Smart Contract Events ```solidity event ProposalCreated( uint256 proposalId, address proposer, address[] targets, uint256[] values, string[] signatures, bytes[] calldatas, uint256 startBlock, uint256 endBlock, string description ); event VoteCast( address indexed voter, uint256 proposalId, uint8 support, uint256 weight, string reason ); ``` ### Troubleshooting #### Common Issues **Cannot Create Proposal**: * Check TREEM balance meets threshold * Verify wallet connection * Ensure sufficient gas * Check for existing pending proposals **Voting Power Shows Zero**: * Verify tokens were staked before proposal creation * Check delegation settings * Confirm stake is active * Wait for blockchain confirmation **Transaction Fails**: * Increase gas limit * Check network congestion * Verify wallet balance * Try during off-peak hours #### Error Messages | Error | Cause | Solution | | --------------------------- | ------------------------------- | ------------------------------- | | "Below proposal threshold" | Insufficient TREEM balance | Acquire more tokens or delegate | | "Proposal not active" | Voting period not started/ended | Wait or check proposal status | | "Already voted" | Vote already cast | Cannot change vote once cast | | "Insufficient voting power" | No staked tokens | Stake tokens before voting | This comprehensive proposals documentation covers all aspects of creating, managing, and voting on proposals in Treem DAO. # Staking System The Treem DAO staking system allows token holders to lock their TREEM tokens for specified periods to gain voting rights and earn rewards. ### Overview Staking is mandatory for governance participation. By staking tokens, users demonstrate long-term commitment to the DAO and gain the right to vote on proposals and earn rewards. ### Staking Tiers #### 6-Month Staking Tier **Lock Period**: 180 days **Benefits**: * Vote on general proposals * Vote on grant proposals * Earn base voting rewards * Participate in governance discussions **Use Cases**: * Regular governance participation * Community members seeking voting rights * Users wanting moderate commitment #### 12-Month Staking Tier **Lock Period**: 365 days **Benefits**: * All 6-month tier benefits * Create grant proposals * Higher voting reward multipliers * Priority in certain governance features **Use Cases**: * Long-term DAO contributors * Project creators seeking funding * Core community members ### Staking Process #### Prerequisites * TREEM tokens in your wallet * Connected Ethereum wallet * Sufficient ETH for gas fees #### Step-by-Step Staking 1. **Navigate to Staking Interface** * Go to Dashboard → Token Staking * Or use the dedicated Staking page 2. **Choose Staking Parameters** * Enter amount of TREEM to stake * Select lock period (6 or 12 months) * Review staking benefits summary 3. **Approve Token Transfer** * Click "Stake Tokens" * Approve TREEM token spending (if first time) * Confirm staking transaction 4. **Confirm Staking** * Transaction processes on blockchain * Stake appears in your dashboard * Voting power is automatically updated #### Multiple Stakes Users can create multiple separate stakes: * Each stake has its own lock period * Voting power cumulates across all stakes * Unstaking is done individually per stake ### Voting Power Calculation #### Base Voting Power ``` Voting Power = Sum of All Staked Token Amounts ``` #### Delegation * Default: Voting power delegated to yourself * Option: Delegate to another address * Delegation can be changed anytime * Delegated voting power appears instantly #### Snapshot Mechanism * Voting power calculated at proposal creation time * Prevents vote manipulation through token transfers * Historical voting power preserved for active proposals ### Lock Periods and Unlocking #### Lock Period Rules 1. **Fixed Duration**: Cannot be changed after staking 2. **No Early Exit**: Tokens locked for entire period 3. **Automatic Unlock**: Tokens become unstakable after period expires #### Tracking Lock Progress **Dashboard Display**: * Time remaining until unlock * Progress bar showing completion percentage * Exact unlock date and time **Calculation**: ``` Progress = (Current Time - Start Time) / Lock Period Time Remaining = Unlock Time - Current Time ``` #### Unstaking Process 1. **Wait for Unlock**: Lock period must be completed 2. **Navigate to Stakes**: View your active stakes 3. **Unstake Tokens**: Click "Unstake" on expired stakes 4. **Confirm Transaction**: Approve unstaking transaction 5. **Receive Tokens**: Tokens returned to wallet ### Rewards System #### Voting Rewards **Base Reward**: 100 TREEM per vote cast **Earning Mechanism**: * Vote on any proposal (general or grant) * Rewards accumulate in your account * Claim manually when ready **Annual Limits**: * Maximum 50,000 TREEM per user per year * Prevents reward farming * Resets annually #### Reward Calculation ``` Total Rewards = Votes Cast × Base Reward (100 TREEM) Claimable = min(Total Rewards, Annual Cap - Already Claimed) ``` #### Claiming Rewards 1. **Navigate to Rewards**: Go to Rewards section 2. **View Accumulated**: See unclaimed reward amount 3. **Claim Rewards**: Click "Claim Rewards" button 4. **Confirm Transaction**: Approve claim transaction 5. **Receive Tokens**: Rewards transferred to wallet ### Smart Contract Integration #### TreemStaking Contract **Key Functions**: * `stake(uint256 amount, StakeTier tier)`: Create new stake * `unstake()`: Remove expired stake * `claimBonus()`: Claim voting rewards * `canProposeGrants(address user)`: Check grant proposal rights **Events**: * `Staked(address user, uint256 amount, StakeTier tier)` * `Unstaked(address user, uint256 amount)` * `BonusClaimed(address user, uint256 bonusAmount)` #### Staking Tiers Enum ```solidity enum StakeTier { NONE, // 0 - No active stake SIX_MONTHS, // 1 - 6-month lock period TWELVE_MONTHS // 2 - 12-month lock period } ``` ### Frontend Integration #### React Hooks **useStaking Hook**: ```typescript const { stakes, // Array of user's stakes loading, // Loading state createStake, // Function to create stake unstakeTokens, // Function to unstake getTimeRemaining // Function to calculate time left } = useStaking(); ``` #### Key Components * **EnhancedTokenStaking**: Main staking interface * **StakingDashboard**: Comprehensive staking overview * **VotingRewardsDashboard**: Reward tracking and claiming ### Security Considerations #### Smart Contract Security * **Reentrancy Protection**: Prevents recursive calls * **Access Controls**: Owner-only administrative functions * **Time Validation**: Prevents manipulation of lock periods * **Balance Checks**: Ensures sufficient tokens for operations #### User Security * **Wallet Security**: Keep private keys secure * **Transaction Verification**: Always verify transaction details * **Phishing Protection**: Only use official DAO interfaces * **Gas Management**: Monitor network congestion and fees ### Troubleshooting #### Common Issues **Staking Transaction Fails**: * Check TREEM token balance * Verify token approval * Ensure sufficient ETH for gas * Try increasing gas limit **Cannot Unstake**: * Verify lock period is complete * Check stake status in dashboard * Ensure stake is active * Try refreshing the interface **Voting Power Not Updated**: * Wait for blockchain confirmation * Check if delegation is correct * Verify stake transaction succeeded * Contact support if persistent #### Error Messages | Error | Meaning | Solution | | ---------------------- | ------------------------------ | ------------------------------------ | | "Invalid tier" | Wrong staking tier selected | Use SIX\_MONTHS or TWELVE\_MONTHS | | "Already staked" | User has existing active stake | Unstake previous stake first | | "Lock period not over" | Attempting early unstake | Wait for lock period completion | | "Insufficient balance" | Not enough TREEM tokens | Acquire more tokens or reduce amount | ### Advanced Features #### Delegation Management **Self Delegation** (Default): ```typescript // Automatic on staking votesToken.delegate(msg.sender); ``` **Delegate to Others**: ```typescript // Delegate voting power to another address await treemToken.delegate(delegateeAddress); ``` #### Batch Operations **Multiple Stakes**: * Create separate stakes for different time periods * Manage risk across different lock periods * Optimize for various governance scenarios **Batch Unstaking**: * Unstake multiple expired stakes * Claim multiple reward periods * Optimize gas costs ### Best Practices #### Staking Strategy 1. **Diversify Lock Periods**: Mix 6-month and 12-month stakes 2. **Consider Gas Costs**: Batch operations when possible 3. **Monitor Unlock Dates**: Plan for token liquidity needs 4. **Active Participation**: Vote regularly to maximize rewards #### Risk Management 1. **Start Small**: Begin with smaller amounts to learn system 2. **Understand Locks**: Fully comprehend lock period implications 3. **Stay Informed**: Follow DAO announcements and updates 4. **Community Engagement**: Participate in discussions before voting ### Migration and Upgrades #### Contract Upgrades The staking system may be upgraded in the future: * User stakes will be preserved * Migration paths will be provided * Community governance will decide upgrades * Advance notice will be given #### Database Integration **Stake Tracking**: ```sql -- stake_locks table structure CREATE TABLE stake_locks ( id UUID PRIMARY KEY, user_id UUID NOT NULL, amount INTEGER NOT NULL, lock_period INTEGER NOT NULL, stake_tier TEXT NOT NULL, start_time TIMESTAMP NOT NULL, unlock_time TIMESTAMP NOT NULL, is_active BOOLEAN DEFAULT TRUE ); ``` ### API Reference #### REST Endpoints **Get User Stakes**: ``` GET /api/staking/user/{userId}/stakes ``` **Create Stake**: ``` POST /api/staking/stake Body: { amount: number, lockPeriod: 6|12 } ``` **Unstake Tokens**: ``` POST /api/staking/unstake/{stakeId} ``` **Get Rewards**: ``` GET /api/rewards/user/{userId} ``` This comprehensive staking documentation covers all aspects of the Treem DAO staking system, from basic concepts to advanced integration details. # Admin Guide This guide covers administrative functions and governance management for Treem DAO administrators and authorized personnel. ### Admin Overview #### Administrative Roles **Super Admin**: * Full system access * Smart contract ownership * Parameter management * Emergency functions **Governance Admin**: * Proposal management * Voting oversight * Community moderation * Analytics access **Treasury Admin**: * Fund management * Payment processing * Reward distribution * Financial reporting #### Admin Dashboard Access 1. **Navigate to Admin Panel** * Go to `/admin` or `/dashboard/governance-module` * Requires admin authentication * Multi-factor authentication recommended 2. **Admin Dashboard Sections** * Governance Analytics * Proposal Management * User Management * Smart Contract Controls * Treasury Operations ### Governance Management #### Proposal Administration **Proposal Oversight** **Active Monitoring**: * Review new proposals for compliance * Monitor voting patterns * Track participation rates * Identify suspicious activity **Content Moderation**: * Ensure proposals meet guidelines * Remove inappropriate content * Handle community reports * Maintain proposal quality standards **Emergency Proposal Actions** **Proposal Cancellation**: ```typescript // Emergency cancel malicious proposal await governorContract.cancel( targets, values, calldatas, descriptionHash ); ``` **Use Cases**: * Security vulnerabilities discovered * Malicious or fraudulent proposals * Technical errors in proposal actions * Community safety concerns #### Voting System Management **Vote Participation Tracking** **Recording Participation**: ```typescript // Record user vote participation for rewards await stakingContract.recordVoteParticipation(voterAddress); ``` **Batch Processing**: * Process multiple voters simultaneously * Optimize gas costs for reward distribution * Maintain accurate participation records **Voting Integrity** **Monitoring Activities**: * Unusual voting patterns * Large vote swings * Potential vote buying * Coordinated voting attacks **Investigative Tools**: * Voting power analysis * Transaction pattern review * Address clustering analysis * Temporal voting analysis ### Smart Contract Administration #### Staking Contract Management **Parameter Updates** **Bonus Per Vote**: ```solidity // Update voting reward amount function setBonusPerVote(uint256 newBonus) external onlyOwner { bonusPerVote = newBonus; } ``` **Treasury Address**: ```solidity // Update treasury for reward distribution function setTreasury(address newTreasury) external onlyOwner { require(newTreasury != address(0), "Zero address"); treasury = newTreasury; } ``` **Monitoring Functions** **Stake Verification**: ```solidity // Check user staking status function stakes(address user) external view returns (StakeInfo memory) { return stakes[user]; } // Verify grant proposal permissions function canProposeGrants(address user) external view returns (bool) { return stakes[user].tier == StakeTier.TWELVE_MONTHS; } ``` #### Governor Contract Administration **Governance Parameters** **Voting Delay**: ```solidity // Update voting delay period function setVotingDelay(uint256 newVotingDelay) external onlyOwner { _setVotingDelay(newVotingDelay); } ``` **Voting Period**: ```solidity // Update voting period duration function setVotingPeriod(uint256 newVotingPeriod) external onlyOwner { _setVotingPeriod(newVotingPeriod); } ``` **Proposal Threshold**: ```solidity // Update proposal creation threshold function setProposalThreshold(uint256 newProposalThreshold) external onlyOwner { _setProposalThreshold(newProposalThreshold); } ``` #### Treasury Management **Fund Administration** **Token Distribution**: * Monitor treasury balance * Approve large fund transfers * Manage reward distribution * Handle grant payments **Financial Controls**: * Multi-signature approvals * Spending limits * Audit trail maintenance * Compliance reporting ### Analytics and Reporting #### Governance Analytics Dashboard **Key Metrics** **Participation Metrics**: * Total active proposals * Voting participation rates * Unique voter counts * Stake distribution analysis **Financial Metrics**: * Treasury balance tracking * Reward distribution amounts * Grant funding allocated * Token circulation analysis **Analytics Queries** **User Participation**: ```sql -- Get voting participation by user SELECT u.display_name, COUNT(pv.id) as votes_cast, SUM(pv.voting_power) as total_voting_power, u.stake_tier FROM profiles u LEFT JOIN proposal_votes pv ON u.id = pv.user_id WHERE pv.created_at >= NOW() - INTERVAL '30 days' GROUP BY u.id, u.display_name, u.stake_tier ORDER BY votes_cast DESC; ``` **Proposal Success Rates**: ```sql -- Get proposal outcomes by type SELECT proposal_type, status, COUNT(*) as count, AVG(votes_for + votes_against) as avg_participation FROM proposals WHERE created_at >= NOW() - INTERVAL '90 days' GROUP BY proposal_type, status ORDER BY proposal_type, status; ``` #### Report Generation **Automated Reports** **Daily Reports**: * New proposals created * Voting activity summary * Stake changes * Reward distributions **Weekly Reports**: * Governance participation trends * Treasury balance changes * Community growth metrics * Security incident summary **Monthly Reports**: * Comprehensive governance analysis * Financial statement summary * Strategic recommendations * Performance benchmarks ### User Management #### Member Administration **User Status Management** **Stake Tier Verification**: ```sql -- Update user stake tier UPDATE profiles SET stake_tier = 'TWELVE_MONTHS', voting_power = staked_tokens WHERE id = $1; ``` **Role Management**: ```sql -- Grant admin access to user INSERT INTO user_roles (user_id, role) VALUES ($1, 'admin') ON CONFLICT (user_id, role) DO NOTHING; ``` **Account Recovery** **Wallet Migration**: * Assist with wallet address changes * Verify ownership through multiple channels * Update database records * Maintain audit trail **Access Recovery**: * Reset authentication tokens * Verify identity through KYC * Restore account permissions * Document recovery process #### Community Moderation **Content Management** **Proposal Content**: * Review for appropriate content * Handle community reports * Enforce content guidelines * Remove policy violations **User Communications**: * Monitor forum discussions * Address community concerns * Facilitate dispute resolution * Maintain respectful environment ### Security Administration #### Security Monitoring **Threat Detection** **Unusual Activity Patterns**: * Large stake movements * Coordinated voting behavior * Rapid account creation * Suspicious transaction patterns **Automated Alerts**: * Smart contract anomalies * Treasury threshold breaches * Failed transaction spikes * Access pattern irregularities **Incident Response** **Security Incident Workflow**: 1. **Detection**: Automated alerts or manual reports 2. **Assessment**: Evaluate threat severity 3. **Containment**: Implement protective measures 4. **Investigation**: Analyze attack vectors 5. **Recovery**: Restore normal operations 6. **Documentation**: Record lessons learned #### Emergency Procedures **Emergency Pause** **Smart Contract Pause**: ```solidity // Emergency pause staking operations function pause() external onlyOwner { _pause(); } // Resume operations function unpause() external onlyOwner { _unpause(); } ``` **Use Cases**: * Security vulnerability discovered * Smart contract bug detected * Network attack in progress * Regulatory compliance issues **Multi-Signature Operations** **Critical Functions**: * Contract upgrades * Large fund transfers * Parameter changes * Emergency actions **Multi-Sig Process**: 1. Proposal creation by authorized admin 2. Review by additional administrators 3. Multi-signature approval 4. Execution with transparent logging 5. Community notification ### Maintenance Operations #### Regular Maintenance Tasks **Daily Tasks** **System Health Checks**: * Smart contract status verification * Database consistency checks * API endpoint testing * Network connectivity validation **Data Management**: * Backup verification * Log rotation * Cache optimization * Performance monitoring **Weekly Tasks** **Analytics Review**: * Governance participation analysis * Treasury balance reconciliation * User activity assessment * Security audit review **System Updates**: * Dependency updates * Security patches * Performance optimizations * Feature deployments #### Database Administration **Data Integrity** **Consistency Checks**: ```sql -- Verify voting power consistency SELECT p.id, p.display_name, p.voting_power, COALESCE(SUM(sl.amount), 0) as total_staked FROM profiles p LEFT JOIN stake_locks sl ON p.id = sl.user_id AND sl.is_active = true GROUP BY p.id, p.display_name, p.voting_power HAVING p.voting_power != COALESCE(SUM(sl.amount), 0); ``` **Data Cleanup**: ```sql -- Clean up expired transactions UPDATE governance_token_purchases SET status = 'expired', payment_details = jsonb_set( COALESCE(payment_details, '{}'), '{cleanup_reason}', '"automated_cleanup"' ) WHERE status = 'pending' AND created_at < NOW() - INTERVAL '24 hours'; ``` ### API Administration #### Admin API Endpoints **Governance Management** **Proposal Administration**: ``` POST /api/admin/proposals/{id}/moderate PUT /api/admin/proposals/{id}/status GET /api/admin/proposals/flagged ``` **User Management**: ``` GET /api/admin/users PUT /api/admin/users/{id}/role POST /api/admin/users/{id}/verify ``` **Analytics**: ``` GET /api/admin/analytics/governance GET /api/admin/analytics/participation GET /api/admin/reports/monthly ``` **Smart Contract Administration** **Parameter Management**: ``` PUT /api/admin/contracts/staking/bonus-per-vote PUT /api/admin/contracts/governor/voting-delay GET /api/admin/contracts/status ``` #### Rate Limiting and Access Control **Admin API Protection**: * IP allowlisting for sensitive operations * Rate limiting for bulk operations * Audit logging for all admin actions * Multi-factor authentication required ### Best Practices #### Administrative Guidelines **Decision Making** **Consensus Building**: * Consult with other administrators * Document decision rationale * Communicate changes transparently * Monitor community feedback **Risk Assessment**: * Evaluate potential impacts * Consider alternative approaches * Plan rollback procedures * Test in staging environment **Communication** **Community Updates**: * Regular transparency reports * Advance notice of changes * Clear explanation of decisions * Open feedback channels **Documentation**: * Maintain detailed procedures * Update guides regularly * Share knowledge across team * Archive historical decisions #### Security Best Practices **Access Management** **Principle of Least Privilege**: * Grant minimal necessary permissions * Regular access reviews * Time-limited emergency access * Separation of duties **Authentication**: * Multi-factor authentication required * Hardware security keys recommended * Regular password updates * Session timeout enforcement This comprehensive admin guide provides all necessary information for effectively managing Treem DAO governance operations. # Smart Contracts This section provides comprehensive documentation for the smart contracts powering Treem DAO governance. ### Contract Architecture #### Overview The Treem DAO governance system consists of four main smart contracts working together to provide secure, transparent, and efficient governance: ```mermaid graph TD A[TreemGovernanceToken] --> B[TreemGovernor] A --> C[TreemStaking] B --> D[TimelockController] C --> A C --> B ``` #### Contract Relationships * **TreemGovernanceToken**: Provides voting power and token transfers * **TreemStaking**: Manages token locks and voting eligibility * **TreemGovernor**: Handles proposal creation and voting * **TimelockController**: Enforces execution delays for security ### TreemGovernanceToken Contract #### Contract Overview **Purpose**: ERC-20 governance token with voting capabilities **Standard**: ERC-20, ERC-20Permit, ERC-20Votes **Features**: Voting power delegation, permit signatures, governance integration #### Token Specifications ```solidity contract TreemGovernanceToken is ERC20, ERC20Permit, ERC20Votes, Ownable { uint256 public constant TOTAL_SUPPLY = 1_000_000_000 * 10**18; // 1B tokens string public constant AGREEMENT_IPFS = "bafybeiatjzzgloq7dfmytaeuxwnktquinjdxzasw555lfwey6mpnihbpta"; } ``` #### Distribution Allocation | Recipient | Amount | Percentage | Purpose | | ------------------- | ----------------- | ---------- | ------------------------ | | Foundation Treasury | 400,000,000 TREEM | 40% | Operations & Development | | Community Grants | 300,000,000 TREEM | 30% | Community Funding | | Reserve Future | 150,000,000 TREEM | 15% | Strategic Reserves | | Founders & Team | 150,000,000 TREEM | 15% | Team Allocation | #### Key Functions **Token Information** ```solidity function name() external pure returns (string memory) { return "Treem Governance Token"; } function symbol() external pure returns (string memory) { return "TREEM"; } function decimals() external pure returns (uint8) { return 18; } function totalSupply() external pure returns (uint256) { return TOTAL_SUPPLY; } ``` **Voting Functions** ```solidity function delegate(address delegatee) external { // Delegate voting power to another address } function getVotes(address account) external view returns (uint256) { // Get current voting power of account } function getPastVotes(address account, uint256 blockNumber) external view returns (uint256) { // Get historical voting power at specific block } ``` **Agreement Access** ```solidity function getAgreementIPFS() external pure returns (string memory) { return AGREEMENT_IPFS; } function getAgreementURL() external pure returns (string memory) { return "https://ipfs.io/ipfs/bafybeiatjzzgloq7dfmytaeuxwnktquinjdxzasw555lfwey6mpnihbpta"; } ``` #### Events ```solidity event Transfer(address indexed from, address indexed to, uint256 value); event Approval(address indexed owner, address indexed spender, uint256 value); event DelegateChanged(address indexed delegator, address indexed fromDelegate, address indexed toDelegate); event DelegateVotesChanged(address indexed delegate, uint256 previousBalance, uint256 newBalance); ``` ### TreemStaking Contract #### Contract Overview **Purpose**: Manage token staking with lock periods and voting eligibility **Features**: Tiered staking, voting rewards, grant proposal permissions #### Staking Tiers ```solidity enum StakeTier { NONE, // No active stake SIX_MONTHS, // 6-month lock period TWELVE_MONTHS // 12-month lock period } struct StakeInfo { uint256 amount; // Staked token amount uint256 startTime; // Stake creation timestamp StakeTier tier; // Staking tier } ``` #### Constructor ```solidity constructor( address _treemToken, // TREEM token address address _votesToken, // Same as TREEM token (IVotes interface) address _treasury // Treasury for bonus payments ) { treemToken = IERC20(_treemToken); votesToken = IVotes(_votesToken); treasury = _treasury; bonusPerVote = 100 * 1e18; // 100 TREEM per vote } ``` #### Core Functions **Staking Operations** ```solidity function stake(uint256 amount, StakeTier tier) external { require(tier == StakeTier.SIX_MONTHS || tier == StakeTier.TWELVE_MONTHS, "Invalid tier"); require(amount > 0, "Amount must be > 0"); require(stakes[msg.sender].amount == 0, "Already staked"); treemToken.transferFrom(msg.sender, address(this), amount); stakes[msg.sender] = StakeInfo(amount, block.timestamp, tier); votesToken.delegate(msg.sender); // Auto-delegate to self emit Staked(msg.sender, amount, tier); } function unstake() external { StakeInfo storage info = stakes[msg.sender]; require(info.amount > 0, "Nothing to unstake"); uint256 requiredTime = info.tier == StakeTier.SIX_MONTHS ? 180 days : 365 days; require(block.timestamp >= info.startTime + requiredTime, "Lock period not over"); uint256 amount = info.amount; delete stakes[msg.sender]; treemToken.transfer(msg.sender, amount); emit Unstaked(msg.sender, amount); } ``` **Reward Management** ```solidity function recordVoteParticipation(address voter) external onlyOwner { votesParticipated[voter] += 1; } function claimBonus() external { uint256 participation = votesParticipated[msg.sender]; require(participation > 0, "No participation recorded"); require(stakes[msg.sender].amount > 0, "Must be staked"); uint256 bonus = bonusPerVote * participation; votesParticipated[msg.sender] = 0; treemToken.transferFrom(treasury, msg.sender, bonus); emit BonusClaimed(msg.sender, bonus); } ``` **Permission Checks** ```solidity function canProposeGrants(address user) external view returns (bool) { return stakes[user].tier == StakeTier.TWELVE_MONTHS; } function canVoteOnGrants(address user) external view returns (bool) { return stakes[user].tier == StakeTier.TWELVE_MONTHS; } function canVoteOnGeneral(address user) external view returns (bool) { return stakes[user].tier != StakeTier.NONE; } ``` #### Administrative Functions ```solidity function setBonusPerVote(uint256 newBonus) external onlyOwner { bonusPerVote = newBonus; } function setTreasury(address newTreasury) external onlyOwner { require(newTreasury != address(0), "Zero address"); treasury = newTreasury; } ``` #### Events ```solidity event Staked(address indexed user, uint256 amount, StakeTier tier); event Unstaked(address indexed user, uint256 amount); event BonusClaimed(address indexed user, uint256 bonusAmount); ``` ### TreemGovernor Contract #### Contract Overview **Purpose**: Main governance contract for proposals and voting **Standard**: OpenZeppelin Governor with extensions **Features**: Proposal creation, voting, execution with timelock #### Governance Parameters ```solidity constructor(IVotes _token, TimelockController _timelock) Governor("TreemGovernor") GovernorSettings( 7200, // 1 day voting delay 50400, // 7 days voting period 5_000_000e18 // 0.5% proposal threshold ) GovernorVotes(_token) GovernorVotesQuorumFraction(4) // 4% quorum GovernorTimelockControl(_timelock) {} ``` #### Core Functions **Proposal Creation** ```solidity function propose( address[] memory targets, uint256[] memory values, bytes[] memory calldatas, string memory description ) public override returns (uint256) { require(getVotes(msg.sender, block.number - 1) >= proposalThreshold(), "Below threshold"); return super.propose(targets, values, calldatas, description); } ``` **Voting Functions** ```solidity function castVote(uint256 proposalId, uint8 support) public override returns (uint256) { return super.castVote(proposalId, support); } function castVoteWithReason( uint256 proposalId, uint8 support, string memory reason ) public override returns (uint256) { return super.castVoteWithReason(proposalId, support, reason); } ``` **State Management** ```solidity enum ProposalState { Pending, // Proposal created, voting not started Active, // Voting in progress Canceled, // Proposal cancelled Defeated, // Voting failed (no majority or quorum) Succeeded, // Voting succeeded Queued, // Successful proposal queued for execution Expired, // Execution window expired Executed // Proposal executed } function state(uint256 proposalId) public view override returns (ProposalState) { return super.state(proposalId); } ``` #### Proposal Execution ```solidity function execute( address[] memory targets, uint256[] memory values, bytes[] memory calldatas, bytes32 descriptionHash ) public payable override returns (uint256) { return super.execute(targets, values, calldatas, descriptionHash); } ``` #### Events ```solidity event ProposalCreated( uint256 proposalId, address proposer, address[] targets, uint256[] values, string[] signatures, bytes[] calldatas, uint256 startBlock, uint256 endBlock, string description ); event VoteCast( address indexed voter, uint256 proposalId, uint8 support, uint256 weight, string reason ); event ProposalExecuted(uint256 proposalId); ``` ### TimelockController Contract #### Overview **Purpose**: Add execution delay for security **Standard**: OpenZeppelin TimelockController **Features**: Multi-signature support, role-based access #### Configuration ```solidity constructor( uint256 minDelay, // 2 days minimum delay address[] proposers, // Governor contract address[] executors // Governor contract + admin ) TimelockController(minDelay, proposers, executors) {} ``` #### Key Functions ```solidity function schedule( address target, uint256 value, bytes calldata data, bytes32 predecessor, bytes32 salt, uint256 delay ) external onlyRole(PROPOSER_ROLE); function execute( address target, uint256 value, bytes calldata data, bytes32 predecessor, bytes32 salt ) external payable onlyRoleOrOpenRole(EXECUTOR_ROLE); ``` ### Deployment Guide #### Prerequisites * Hardhat development environment * Ethereum wallet with ETH for deployment * Access to Ethereum node (Infura, Alchemy, etc.) #### Deployment Sequence **1. Deploy TreemGovernanceToken** ```typescript const TreemGovernanceToken = await ethers.getContractFactory("TreemGovernanceToken"); const token = await TreemGovernanceToken.deploy( foundationTreasury, // Foundation treasury address foundersTeam, // Founders team address communityGrants, // Community grants address reserveFuture, // Reserve future address initialOwner // Initial owner (deployer) ); await token.deployed(); ``` **2. Deploy TimelockController** ```typescript const TimelockController = await ethers.getContractFactory("TimelockController"); const timelock = await TimelockController.deploy( 172800, // 2 days in seconds [], // Proposers (will be set to governor) [] // Executors (will be set to governor + admin) ); await timelock.deployed(); ``` **3. Deploy TreemStaking** ```typescript const TreemStaking = await ethers.getContractFactory("TreemStaking"); const staking = await TreemStaking.deploy( token.address, // TREEM token address token.address, // Votes token (same as TREEM) treasury // Treasury address for rewards ); await staking.deployed(); ``` **4. Deploy TreemGovernor** ```typescript const TreemGovernor = await ethers.getContractFactory("TreemGovernor"); const governor = await TreemGovernor.deploy( token.address, // Votes token timelock.address // Timelock controller ); await governor.deployed(); ``` **5. Configure Contracts** ```typescript // Grant governor roles in timelock await timelock.grantRole(await timelock.PROPOSER_ROLE(), governor.address); await timelock.grantRole(await timelock.EXECUTOR_ROLE(), governor.address); // Renounce admin role from deployer await timelock.revokeRole(await timelock.TIMELOCK_ADMIN_ROLE(), deployer.address); ``` #### Gas Estimates | Contract | Deployment Gas | Mainnet Cost (50 gwei) | | -------------------- | --------------- | ---------------------- | | TreemGovernanceToken | \~2,500,000 | \~0.125 ETH | | TreemStaking | \~1,200,000 | \~0.060 ETH | | TreemGovernor | \~3,000,000 | \~0.150 ETH | | TimelockController | \~1,500,000 | \~0.075 ETH | | **Total** | **\~8,200,000** | **\~0.410 ETH** | ### Security Considerations #### Access Controls **Critical Functions Protected**: * Contract ownership transfer * Parameter updates * Emergency functions * Treasury management **Role-Based Security**: ```solidity modifier onlyOwner() { require(msg.sender == owner(), "Not the owner"); _; } modifier onlyRole(bytes32 role) { require(hasRole(role, msg.sender), "Access denied"); _; } ``` #### Reentrancy Protection ```solidity import "@openzeppelin/contracts/security/ReentrancyGuard.sol"; contract TreemStaking is ReentrancyGuard { function stake(uint256 amount, StakeTier tier) external nonReentrant { // Protected against reentrancy } } ``` #### Time-Based Security **Block Timestamp Usage**: * Lock period calculations use `block.timestamp` * Resistant to minor manipulation * Suitable for periods measured in days **Snapshot Mechanism**: * Voting power calculated at proposal creation * Prevents vote manipulation * Historical data preserved ### Integration Examples #### Frontend Integration **Contract Instance Creation** ```typescript import { ethers } from 'ethers'; // Contract addresses const CONTRACTS = { TREEM_TOKEN: '0x...', STAKING: '0x...', GOVERNOR: '0x...', TIMELOCK: '0x...' }; // Create contract instances const provider = new ethers.providers.Web3Provider(window.ethereum); const signer = provider.getSigner(); const treemToken = new ethers.Contract( CONTRACTS.TREEM_TOKEN, TreemTokenABI, signer ); const stakingContract = new ethers.Contract( CONTRACTS.STAKING, TreemStakingABI, signer ); ``` **Common Operations** ```typescript // Stake tokens async function stakeTokens(amount: string, tier: number) { const tx = await stakingContract.stake( ethers.utils.parseEther(amount), tier // 1 for SIX_MONTHS, 2 for TWELVE_MONTHS ); await tx.wait(); } // Check staking status async function getStakeInfo(address: string) { const stakeInfo = await stakingContract.stakes(address); return { amount: ethers.utils.formatEther(stakeInfo.amount), startTime: new Date(stakeInfo.startTime.toNumber() * 1000), tier: stakeInfo.tier }; } // Create proposal async function createProposal(description: string) { const tx = await governorContract.propose( [], // targets [], // values [], // calldatas description ); await tx.wait(); } ``` #### Event Listening ```typescript // Listen for staking events stakingContract.on('Staked', (user, amount, tier, event) => { console.log(`User ${user} staked ${ethers.utils.formatEther(amount)} TREEM`); }); // Listen for voting events governorContract.on('VoteCast', (voter, proposalId, support, weight, reason, event) => { console.log(`Vote cast: ${voter} voted ${support} with weight ${weight}`); }); ``` ### Troubleshooting #### Common Deployment Issues **Insufficient Gas**: ``` Error: Transaction ran out of gas Solution: Increase gas limit to 3,000,000+ ``` **Constructor Arguments**: ``` Error: Invalid constructor arguments Solution: Verify all addresses are valid and checksummed ``` **Network Configuration**: ``` Error: Network mismatch Solution: Ensure correct network configuration in hardhat.config.js ``` #### Runtime Issues **Staking Failures**: * Check token approval * Verify sufficient balance * Ensure not already staked **Voting Issues**: * Confirm tokens are staked * Check proposal is in active state * Verify voting power > 0 **Proposal Creation**: * Meet proposal threshold * Provide valid description * Check governor contract state This comprehensive smart contracts documentation provides all necessary information for understanding, deploying, and interacting with the Treem DAO governance contracts. # FAQ & Troubleshooting This section answers frequently asked questions and provides solutions to common issues with Treem DAO governance. ### General Questions #### What is Treem DAO? **Q: What is Treem DAO and how does it work?** A: Treem DAO is a decentralized autonomous organization that allows TREEM token holders to participate in governance decisions. The DAO uses smart contracts on Ethereum to manage proposals, voting, and treasury operations. Members can stake tokens to gain voting rights and participate in funding decisions for community projects. **Q: How do I join Treem DAO?** A: To join Treem DAO: 1. Acquire TREEM tokens through the official token sale or exchanges 2. Connect your Ethereum wallet to the DAO platform 3. Stake your tokens for 6 or 12 months to gain voting rights 4. Start participating in proposals and governance decisions #### TREEM Token **Q: What is the TREEM token?** A: TREEM is an ERC-20 governance token with the following specifications: * **Total Supply**: 1,000,000,000 TREEM * **Symbol**: TREEM * **Decimals**: 18 * **Features**: Voting power, delegation, permit signatures **Q: How is the TREEM token distributed?** A: Token distribution: * 40% (400M) - Foundation Treasury * 30% (300M) - Community Grants * 15% (150M) - Reserve Future Use * 15% (150M) - Founders and Team **Q: Where can I buy TREEM tokens?** A: TREEM tokens can be acquired through: * Official DAO token sale portal * Supported decentralized exchanges * Authorized partners and distributors * Community grant programs ### Staking Questions #### Staking Basics **Q: Why do I need to stake tokens?** A: Staking demonstrates your commitment to the DAO and provides several benefits: * **Voting Rights**: Only staked token holders can vote on proposals * **Proposal Creation**: 12-month stakers can create grant proposals * **Rewards**: Earn TREEM tokens for voting participation * **Community Standing**: Show long-term commitment to DAO success **Q: What are the different staking tiers?** A: There are two staking tiers: **6-Month Staking**: * Lock period: 180 days * Vote on all proposals * Earn voting rewards * Cannot create grant proposals **12-Month Staking**: * Lock period: 365 days * Vote on all proposals * Create grant proposals * Higher reward multipliers * Enhanced governance privileges **Q: Can I unstake my tokens early?** A: No, tokens are locked for the entire staking period. Early unstaking is not permitted to ensure governance stability and prevent manipulation. You can only unstake after the lock period expires. **Q: Can I stake multiple times?** A: Currently, each address can only have one active stake at a time. If you want to change your staking amount or period, you must wait for your current stake to expire, unstake, and then create a new stake. #### Staking Process **Q: How do I stake my tokens?** A: To stake tokens: 1. Go to the Staking section in your dashboard 2. Enter the amount of TREEM tokens to stake 3. Select lock period (6 or 12 months) 4. Click "Stake Tokens" and confirm the transaction 5. Wait for blockchain confirmation **Q: What happens when I stake tokens?** A: When you stake: * Tokens are transferred to the staking contract * Your voting power is automatically activated * Voting power is delegated to yourself by default * Your stake tier is updated in the system * You become eligible for voting rewards **Q: How do I know when I can unstake?** A: Your dashboard shows: * Exact unlock date and time * Time remaining countdown * Progress bar showing completion percentage * "Unstake" button appears when lock period expires ### Voting Questions #### Voting Process **Q: How do I vote on proposals?** A: To vote on proposals: 1. Navigate to the Governance section 2. Browse active proposals 3. Click on a proposal to read details 4. Select "For" or "Against" 5. Optionally add a comment 6. Click "Cast Vote" and confirm transaction **Q: How is voting power calculated?** A: Voting power equals your staked token amount at the time the proposal was created. For example: * You stake 1,000 TREEM tokens * A proposal is created → Your voting power = 1,000 * You cannot increase voting power for that specific proposal **Q: Can I change my vote?** A: No, votes are final and cannot be changed once cast. This ensures voting integrity and prevents manipulation. Consider your decision carefully before voting. **Q: When do voting periods start and end?** A: Voting timeline: * **Voting Delay**: 1 day after proposal creation * **Voting Period**: 7 days of active voting * **Total**: Proposals are votable for 7 days, starting 1 day after creation #### Voting Power **Q: Why does my voting power show as zero?** A: Common reasons: * Tokens are not staked * Stake was created after the proposal * Delegation is not set correctly * Stake transaction hasn't been confirmed **Q: Can I delegate my voting power to someone else?** A: Yes, you can delegate your voting power: 1. Go to your wallet's delegation section 2. Enter the address to delegate to 3. Confirm the delegation transaction 4. Your voting power will be used by the delegate **Q: How does delegation work?** A: Delegation transfers your voting power to another address: * You keep ownership of your tokens * The delegate can vote with your power * You can change delegation anytime * Delegation is separate from staking ### Proposals #### Creating Proposals **Q: Who can create proposals?** A: Proposal creation requirements: * **General Proposals**: Must hold 5,000,000 TREEM tokens (proposal threshold) * **Grant Proposals**: Must have 12-month staked tokens **Q: What types of proposals can I create?** A: Two main types: * **General Proposals**: Protocol changes, parameter updates, governance decisions * **Grant Proposals**: Funding requests for community projects with specific amounts and recipients **Q: How much does it cost to create a proposal?** A: Creating proposals only costs Ethereum gas fees (usually $10-50 depending on network congestion). There are no additional fees from the DAO. **Q: What should I include in my proposal?** A: Effective proposals include: * Clear, descriptive title * Executive summary * Detailed description and rationale * Implementation plan and timeline * Budget breakdown (for grants) * Expected outcomes and success metrics #### Proposal Lifecycle **Q: What happens after I create a proposal?** A: Proposal lifecycle: 1. **Pending** (1 day): Voting delay period 2. **Active** (7 days): Community voting period 3. **Succeeded/Defeated**: Based on votes and quorum 4. **Queued** (2 days): Execution delay for successful proposals 5. **Executed**: Proposal actions are performed **Q: What is quorum and why is it needed?** A: Quorum is the minimum participation required for valid governance: * **Current Quorum**: 4% of total supply (40,000,000 TREEM) * **Purpose**: Ensures sufficient community participation * **Effect**: Proposals fail if quorum is not met, regardless of vote ratio **Q: Can proposals be cancelled?** A: Proposals can be cancelled in emergency situations: * Security vulnerabilities discovered * Technical errors in proposal actions * Fraudulent or malicious proposals * Only administrators can cancel proposals ### Rewards #### Earning Rewards **Q: How do I earn voting rewards?** A: Voting rewards are earned by: 1. Having staked tokens (any tier) 2. Voting on any active proposal 3. Each vote earns 100 TREEM tokens 4. Rewards accumulate until claimed **Q: How much can I earn in rewards?** A: Reward structure: * **Base Reward**: 100 TREEM per vote * **Annual Cap**: 50,000 TREEM per user per year * **Maximum Votes**: 500 votes per year to reach cap **Q: How do I claim my rewards?** A: To claim rewards: 1. Navigate to the Rewards section 2. View your accumulated rewards 3. Click "Claim Rewards" 4. Confirm the transaction 5. Rewards are transferred to your wallet **Q: Do rewards expire?** A: Rewards do not expire, but: * Annual cap resets each year * Unclaimed rewards carry over * Vote count resets to zero after claiming * Treasury must have sufficient balance #### Reward Issues **Q: Why can't I claim my rewards?** A: Common issues: * No votes cast yet * Tokens not staked when voting * Annual reward cap reached * Treasury insufficient balance * Transaction gas fees too low **Q: When do rewards get distributed?** A: Rewards are not automatically distributed: * Manual claiming required * Claim anytime after voting * Multiple votes can be claimed together * Gas optimization through batching ### Technical Issues #### Wallet and Connection **Q: My wallet won't connect. What should I do?** A: Troubleshooting steps: 1. Ensure wallet extension is installed and updated 2. Check you're on the correct network (Ethereum Mainnet) 3. Clear browser cache and refresh page 4. Try a different browser or incognito mode 5. Restart wallet extension **Q: Transactions keep failing. How do I fix this?** A: Common solutions: 1. **Increase gas limit**: Set to 300,000+ for complex transactions 2. **Check gas price**: Use current network rates 3. **Verify balance**: Ensure sufficient ETH for fees 4. **Wait for confirmation**: Don't submit duplicate transactions 5. **Try during off-peak hours**: Lower network congestion **Q: Why is my transaction stuck?** A: Transaction troubleshooting: * **Low gas price**: Increase gas and resubmit * **Network congestion**: Wait or increase gas significantly * **Nonce issues**: Clear pending transactions in wallet * **Speed up**: Use wallet's "speed up" feature #### Smart Contract Issues **Q: Contract interactions are failing. What's wrong?** A: Debugging steps: 1. Check contract addresses are correct 2. Verify you're on the right network 3. Ensure sufficient token allowances 4. Check if contracts are paused 5. Review error messages in console **Q: How do I verify my transactions?** A: Transaction verification: 1. Copy transaction hash from wallet 2. Visit Etherscan.io 3. Paste hash in search box 4. Check transaction status and details 5. Review event logs for success confirmation #### Data and Display Issues **Q: My staking information isn't updating. Why?** A: Common causes: * **Blockchain lag**: Wait 1-2 minutes for confirmation * **Browser cache**: Clear cache and refresh * **Network sync**: Check your connection * **Database lag**: Backend may need time to update **Q: Voting power shows incorrectly. How to fix?** A: Troubleshooting: 1. Verify tokens are actually staked 2. Check stake transaction was confirmed 3. Ensure delegation is set correctly 4. Wait for blockchain confirmation 5. Contact support if persists ### Security and Safety #### Account Security **Q: How do I keep my wallet secure?** A: Security best practices: * **Use hardware wallets** for large amounts * **Never share private keys** with anyone * **Enable 2FA** where available * **Verify URLs** before connecting wallet * **Keep software updated** wallet and browser **Q: What if I lose access to my wallet?** A: Recovery options: * **Seed phrase recovery**: Use your backup words * **Hardware wallet recovery**: Follow device instructions * **Contact wallet support**: For technical issues * **No DAO-level recovery**: We cannot recover lost wallets **Q: How do I verify I'm on the real website?** A: Security verification: * **Check URL**: Ensure correct domain name * **Look for HTTPS**: Green lock icon in browser * **Verify smart contracts**: Match addresses with official documentation * **Be wary of links**: Type URLs manually #### Smart Contract Security **Q: Are the smart contracts safe?** A: Security measures: * **OpenZeppelin standards**: Based on battle-tested code * **Professional audits**: Contracts undergo security review * **Timelock protection**: 2-day delay for critical changes * **Multi-signature**: Important functions require multiple approvals **Q: What happens if there's a bug in the contracts?** A: Emergency procedures: * **Pause functionality**: Contracts can be paused if needed * **Admin intervention**: Multi-sig can handle emergencies * **Community notification**: Transparent communication about issues * **Upgrade path**: Governance can approve fixes ### Getting Help #### Support Channels **Q: Where can I get help?** A: Support resources: * **Documentation**: Comprehensive guides at docs.treem.io * **Discord Community**: Real-time chat with community * **Support Tickets**: Submit detailed issue reports * **FAQ Section**: Search common questions and answers **Q: How do I report a bug?** A: Bug reporting: 1. **Describe the issue**: What went wrong? 2. **Steps to reproduce**: How did it happen? 3. **Include details**: Browser, wallet, transaction hash 4. **Screenshots**: Visual evidence helps 5. **Submit ticket**: Use official support channels **Q: Who can I contact for technical support?** A: Contact options: * **Community Discord**: Fastest response for general issues * **Technical Support**: For complex problems * **Security Issues**: Use secure contact methods * **Admin Team**: For governance-related questions #### Emergency Contacts **Q: What if there's an emergency?** A: Emergency procedures: * **Immediate Issues**: Contact admin team directly * **Security Concerns**: Use emergency contact methods * **Smart Contract Issues**: Follow incident response protocol * **Community Safety**: Report to moderators immediately *** This FAQ covers the most common questions and issues. For additional support, please refer to our community channels or submit a support ticket through the official platform. # Email System ## Email System Documentation The Treem DAO platform includes a comprehensive email management system that allows administrators to configure email templates, manage SMTP settings, send bulk emails, and track email analytics. ### Overview The email system provides: * **Template Management**: Create and manage reusable email templates * **SMTP Configuration**: Configure custom email providers or use the default Resend service * **Bulk Email Sending**: Send emails to multiple users or user groups * **Email Analytics**: Track delivery rates, opens, and performance metrics * **User Preferences**: Allow users to control their email subscription preferences ### System Architecture The email system consists of: * **Frontend Components**: Admin interface for email management * **Edge Function**: `enhanced-email-service` for processing and sending emails * **Database Tables**: Storage for templates, configurations, logs, and preferences * **Default Provider**: Resend service integration for reliable email delivery ### Quick Start #### For Administrators 1. Navigate to **Admin Dashboard → Settings → Email System** 2. Start with the **Templates** tab to create your first email template 3. Optionally configure custom SMTP in the **Configuration** tab 4. Use **Bulk Send** to send emails to users 5. Monitor performance in **Analytics** and **Recent** tabs #### For Users 1. Go to **Profile → Email Preferences** 2. Configure which types of emails you want to receive 3. Toggle notifications for governance, transactions, security, etc. ### Table of Contents * Template Management * SMTP Configuration * Bulk Email Sending * Email Analytics * User Preferences * API Reference * Troubleshooting ### Default Email Provider The system uses **Resend** as the default email service provider, which offers: * High delivery rates * Built-in spam protection * Reliable infrastructure * Easy integration When no custom SMTP configuration is active, all emails are sent through Resend. ### Security Features * **Row Level Security (RLS)**: All email data is protected with proper access controls * **Admin-only Access**: Email management features are restricted to administrators * **User Privacy**: Users can control their email preferences independently * **Secure Storage**: SMTP credentials are securely stored in Supabase ### Getting Help If you encounter issues with the email system: 1. Check the Troubleshooting Guide 2. Review email logs in the **Recent** tab 3. Verify your SMTP configuration if using custom providers 4. Ensure your Resend API key is properly configured # Email Template ## Email Template Management Email templates allow you to create reusable email content with dynamic variables that can be customized for each recipient. ### Overview The template system supports: * **HTML and Text Content**: Rich HTML emails with optional plain text fallbacks * **Dynamic Variables**: Personalize emails with user-specific data * **Template Types**: Organize templates by purpose (welcome, password\_reset, etc.) * **Active/Inactive Status**: Control which templates are available for use ### Creating Templates #### Step 1: Access Template Manager 1. Navigate to **Admin Dashboard → Settings → Email System** 2. Click on the **Templates** tab 3. Click **"New Template"** button #### Step 2: Configure Template Details **Template Type**: A unique identifier for the template (e.g., `welcome_email`, `password_reset`) * Use lowercase with underscores * Must be unique across all templates * Used when calling the email service API **Subject**: The email subject line * Can include variables using `{{variable_name}}` syntax * Example: `Welcome to {{dao_name}}, {{user_name}}!` #### Step 3: Create Email Content **HTML Content**: The main email body with rich formatting ```html

Welcome to Treem DAO, {{user_name}}!

Thank you for joining our community. Your account has been successfully created.

You can now access your dashboard at: {{dashboard_url}}

Best regards,
The Treem DAO Team

``` **Text Content** (Optional): Plain text version for email clients that don't support HTML ``` Welcome to Treem DAO, {{user_name}}! Thank you for joining our community. Your account has been successfully created. You can now access your dashboard at: {{dashboard_url}} Best regards, The Treem DAO Team ``` #### Step 4: Define Variables **Variables**: Comma-separated list of variables used in the template * Example: `user_name, dao_name, dashboard_url` * Variables are automatically detected from your content * Used for validation when sending emails #### Step 5: Set Status **Active**: Enable or disable the template * Only active templates can be used for sending emails * Inactive templates are preserved but not available for selection ### Template Variables #### Common Variables | Variable | Description | Example | | --------------- | ----------------------- | -------------------------------------------- | | `user_name` | User's display name | John Doe | | `user_email` | User's email address | | | `dao_name` | DAO organization name | Treem DAO | | `dashboard_url` | Link to user dashboard | | | `confirm_url` | Email confirmation link | ... | | `reset_url` | Password reset link | ... | #### Custom Variables You can define custom variables for specific use cases: * `proposal_title` - For governance notifications * `transaction_amount` - For payment confirmations * `event_date` - For event reminders * `stake_amount` - For staking notifications ### Template Types #### System Templates **welcome\_email**: Sent when users first join the DAO * Variables: `user_name`, `dao_name`, `dashboard_url` **password\_reset**: Sent when users request password reset * Variables: `user_name`, `reset_url`, `expiry_time` **email\_confirmation**: Sent to verify email addresses * Variables: `user_name`, `confirm_url` #### Governance Templates **new\_proposal**: Notify users about new proposals * Variables: `user_name`, `proposal_title`, `proposal_url`, `voting_deadline` **voting\_reminder**: Remind users to vote on active proposals * Variables: `user_name`, `proposal_title`, `days_remaining`, `vote_url` #### Transaction Templates **purchase\_confirmation**: Confirm token purchases * Variables: `user_name`, `token_amount`, `total_cost`, `transaction_id` **staking\_confirmation**: Confirm staking transactions * Variables: `user_name`, `stake_amount`, `lock_period`, `unlock_date` ### Managing Templates #### Editing Templates 1. Click the **Edit** icon on any template 2. Modify the template content 3. Update variables if needed 4. Click **"Update Template"** #### Previewing Templates 1. Click the **Preview** icon on any template 2. View the rendered HTML content 3. Check the plain text version 4. Review variable usage #### Deleting Templates 1. Click the **Delete** icon on any template 2. Confirm the deletion 3. **Warning**: This action cannot be undone ### Best Practices #### Content Guidelines 1. **Keep it concise**: Users prefer shorter emails 2. **Clear call-to-action**: Make it obvious what users should do next 3. **Mobile-friendly**: Use responsive HTML design 4. **Brand consistency**: Match your DAO's visual identity #### Variable Usage 1. **Always provide fallbacks**: Handle cases where variables might be empty 2. **Validate variables**: Ensure all template variables are provided when sending 3. **Use descriptive names**: Make variable purposes clear 4. **Document custom variables**: Keep track of what each variable represents #### HTML Best Practices 1. **Use table-based layouts**: Better email client compatibility 2. **Inline CSS**: Many email clients strip external stylesheets 3. **Test across clients**: Email rendering varies significantly 4. **Include alt text**: For images and accessibility ### Integration with Bulk Sending Templates integrate seamlessly with the bulk email sender: 1. Select your template from the dropdown 2. Fill in the required variables 3. Choose your recipient groups 4. Send to multiple users at once ### API Integration Templates can be used programmatically via the enhanced-email-service: ```javascript const { data, error } = await supabase.functions.invoke('enhanced-email-service', { body: { template_type: 'welcome_email', recipient_email: 'user@example.com', variables: { user_name: 'John Doe', dao_name: 'Treem DAO', dashboard_url: 'https://app.treemdao.com/dashboard' } } }); ``` ### Troubleshooting #### Template Not Available for Selection * Check if the template is marked as **Active** * Verify the template\_type is unique * Ensure all required fields are filled #### Variables Not Replacing * Check variable names match exactly (case-sensitive) * Ensure variables are defined in the template configuration * Verify variable syntax uses `{{variable_name}}` format #### HTML Not Rendering * Test HTML in the preview function * Check for unclosed tags or invalid markup * Ensure proper email-safe HTML structure # SMTP Configuration ## SMTP Configuration Configure custom email providers or use the default Resend service for sending emails from your Treem DAO platform. ### Overview The SMTP configuration system allows you to: * **Use Default Provider**: Resend service (recommended) * **Add Custom SMTP**: Configure your own email providers * **Multiple Configurations**: Set up different providers for different purposes * **Active Configuration**: Only one SMTP config can be active at a time * **Test Configurations**: Verify settings before making them active ### Default Provider: Resend **Resend** is the default email service provider, offering: * High delivery rates (99%+) * Built-in spam and bounce handling * Reliable infrastructure * Easy setup with API key * No additional configuration required #### Resend Setup The default Resend configuration is automatically available and requires no setup. It uses the `RESEND_API_KEY` configured in your Supabase secrets. ### Custom SMTP Configuration #### When to Use Custom SMTP Consider custom SMTP when you need: * **Brand-specific sending domain**: emails from your own domain * **Higher sending volumes**: enterprise-grade email providers * **Compliance requirements**: specific email service providers * **Cost optimization**: bulk sending discounts * **Integration requirements**: existing email infrastructure #### Adding SMTP Configuration 1. Navigate to **Admin Dashboard → Settings → Email System** 2. Click on the **Configuration** tab 3. Click **"New Configuration"** #### Configuration Fields **Configuration Name**: Descriptive name for this SMTP setup * Example: "Gmail SMTP", "Company Mail Server" * Used for identification in the admin interface **SMTP Host**: Your email provider's SMTP server * Gmail: `smtp.gmail.com` * Outlook: `smtp-mail.outlook.com` * SendGrid: `smtp.sendgrid.net` * Custom: Your provider's SMTP hostname **SMTP Port**: The port number for SMTP connections * **587**: STARTTLS (recommended) * **465**: SSL/TLS * **25**: Unencrypted (not recommended) **Username**: SMTP authentication username * Usually your email address * For some providers, it's a specific username **Password**: SMTP authentication password * Your email password * For Gmail/Outlook: App-specific password * For services like SendGrid: API key **From Email**: The sender email address * Must be authorized by your SMTP provider * Example: `noreply@yourdao.com` **From Name**: The display name for the sender * Example: "Treem DAO", "Your DAO Name" * What recipients see in their inbox **Use TLS**: Enable/disable transport layer security * **Recommended**: Always enable for security * Required by most modern email providers #### Provider-Specific Setup **Gmail Configuration** ``` SMTP Host: smtp.gmail.com SMTP Port: 587 Username: your-email@gmail.com Password: [App Password - not your regular password] Use TLS: Yes ``` **Important**: Enable 2-factor authentication and create an App Password: 1. Go to Google Account settings 2. Security → 2-Step Verification 3. App passwords → Generate new app password 4. Use the generated password in SMTP configuration **Microsoft Outlook/Office 365** ``` SMTP Host: smtp-mail.outlook.com SMTP Port: 587 Username: your-email@outlook.com Password: [Your account password or app password] Use TLS: Yes ``` **SendGrid** ``` SMTP Host: smtp.sendgrid.net SMTP Port: 587 Username: apikey Password: [Your SendGrid API Key] Use TLS: Yes ``` **Mailgun** ``` SMTP Host: smtp.mailgun.org SMTP Port: 587 Username: [Your Mailgun SMTP username] Password: [Your Mailgun SMTP password] Use TLS: Yes ``` #### Testing Configuration Before activating an SMTP configuration: 1. Click the **Test** button on the configuration card 2. A test email will be sent to the configured "From Email" address 3. Check if the email is received successfully 4. Verify sender name and deliverability #### Activating Configuration To make a custom SMTP configuration active: 1. Click **"Set as Active"** on the desired configuration 2. This will deactivate all other custom configurations 3. The system will use this SMTP for all outgoing emails 4. The default Resend service will be disabled #### Switching Back to Default To return to using Resend: 1. Deactivate all custom SMTP configurations 2. The system automatically falls back to Resend 3. No additional configuration needed ### Managing Multiple Configurations #### Use Cases for Multiple Configurations * **Development vs Production**: Different providers for testing * **Backup Configuration**: Failover to secondary provider * **Service-Specific**: Different providers for different email types * **Geographic Distribution**: Regional email providers #### Best Practices 1. **Keep one active**: Only one configuration should be active at a time 2. **Test before switching**: Always test new configurations 3. **Document settings**: Keep notes on provider-specific requirements 4. **Monitor delivery**: Watch analytics after switching providers ### Security Considerations #### Password Security * **Never share SMTP passwords**: Keep credentials secure * **Use app passwords**: When available, prefer app-specific passwords * **Rotate credentials**: Regularly update SMTP passwords * **Audit access**: Review who has access to SMTP configurations #### Domain Authentication For best deliverability with custom domains: 1. **SPF Record**: Add sender policy framework record 2. **DKIM**: Configure domain key identified mail 3. **DMARC**: Set up domain-based message authentication 4. **MX Record**: Ensure proper mail exchange configuration ### Troubleshooting #### Common SMTP Errors **Authentication Failed** * Verify username and password * Check if 2FA requires app password * Ensure SMTP authentication is enabled **Connection Refused** * Verify SMTP host and port * Check firewall settings * Confirm TLS settings match provider requirements **Sender Not Authorized** * Verify "From Email" is authorized by provider * Check domain verification status * Ensure sender policy framework (SPF) is configured #### Testing Delivery Issues 1. **Check spam folders**: Test emails might be filtered 2. **Verify recipient**: Ensure test email address is valid 3. **Review provider logs**: Check SMTP provider's sending logs 4. **Test with different recipients**: Try multiple email addresses #### Provider-Specific Issues **Gmail Issues** * Enable "Less secure app access" (not recommended) OR * Use App Passwords with 2FA (recommended) * Check Google Account security settings **Office 365 Issues** * Verify SMTP authentication is enabled for the account * Check if the account requires modern authentication * Ensure the account isn't locked or suspended ### Performance Monitoring #### Metrics to Track After configuring custom SMTP: 1. **Delivery Rate**: Percentage of emails successfully delivered 2. **Bounce Rate**: Emails that couldn't be delivered 3. **Response Time**: How quickly emails are sent 4. **Error Rate**: Failed sending attempts #### Analytics Integration The email analytics dashboard will show performance metrics for your active SMTP configuration, helping you monitor: * Daily sending volume * Success/failure rates * Response times * Error patterns ### Migration Guide #### From Default to Custom SMTP 1. **Prepare Configuration**: Set up your custom SMTP settings 2. **Test Thoroughly**: Verify all email types work correctly 3. **Monitor Closely**: Watch delivery rates after switching 4. **Have Rollback Plan**: Keep default provider as backup #### Between SMTP Providers 1. **Configure New Provider**: Add new SMTP configuration 2. **Test New Configuration**: Verify functionality 3. **Switch Active Configuration**: Deactivate old, activate new 4. **Monitor Performance**: Watch for delivery issues 5. **Update DNS Records**: If changing domains, update SPF/DKIM This comprehensive SMTP configuration system ensures reliable email delivery while providing flexibility for your specific needs. # Bulk Email Sending ## Bulk Email Sending Send emails to multiple recipients simultaneously using pre-configured templates and user groups. ### Overview The bulk email sender allows administrators to: * **Send to User Groups**: Target specific user segments * **Use Email Templates**: Leverage pre-configured templates with variables * **Custom Recipients**: Add individual email addresses * **Progress Tracking**: Monitor sending progress in real-time * **Batch Processing**: Automatic rate limiting to prevent spam issues ### Getting Started #### Step 1: Access Bulk Sender 1. Navigate to **Admin Dashboard → Settings → Email System** 2. Click on the **Bulk Send** tab 3. The interface shows configuration options and preview panels #### Step 2: Select Email Template 1. Choose from available active templates in the dropdown 2. Only active templates appear in the selection 3. Template preview will update automatically #### Step 3: Configure Template Variables If your selected template includes variables: 1. Fill in each variable field that appears 2. All recipients will receive the same variable values 3. Leave blank for variables that should remain as placeholders #### Step 4: Choose Recipients Select recipient groups and/or add custom emails: **User Groups**: Predefined segments of your user base**Custom Emails**: Individual email addresses (one per line) #### Step 5: Review and Send 1. Check the estimated recipient count 2. Preview the email content 3. Click **"Send to X Recipients"** to begin sending ### Recipient Groups #### Available User Groups **All Users**: Every registered user in the system * Includes all user roles and statuses * Use with caution for sensitive communications **Staked Users**: Users who have tokens staked * Excludes users with no active stakes * Good for governance-related communications **Administrators**: Users with admin privileges * System administrators and moderators * Use for internal communications **Regular Members**: Non-admin users * Excludes administrators from the list * Good for member-focused announcements #### Group Statistics Each group shows: * **Name**: Descriptive group identifier * **Count**: Number of users in the group * **Filter**: Criteria used to define the group ### Custom Email Lists #### Adding Individual Emails 1. Use the **"Custom Email Addresses"** text area 2. Enter one email address per line 3. System validates email format automatically 4. Invalid emails are filtered out before sending #### Format Requirements ``` user1@example.com user2@company.org admin@dao.com ``` **Valid Formats**: * Standard email format: `name@domain.com` * Plus addressing: `user+tag@domain.com` * Subdomains: `user@sub.domain.com` **Invalid Formats** (will be filtered): * Missing @ symbol: `userexample.com` * Multiple @ symbols: `user@@domain.com` * Empty lines or whitespace-only lines ### Template Variables #### Setting Global Variables When sending bulk emails, all recipients receive: * **Same variable values**: Set once, applied to all emails * **Personalization limitations**: Cannot customize per recipient * **Static content**: Variables become fixed text #### Common Bulk Email Variables | Variable | Description | Example Value | | --------------- | -------------------- | ------------------------------- | | `dao_name` | Organization name | Treem DAO | | `announcement` | Main message content | New proposal voting is open | | `deadline` | Important dates | March 15, 2024 | | `action_url` | Call-to-action link | | | `contact_email` | Support contact | | #### Best Practices for Variables 1. **Use generic values**: Avoid user-specific information 2. **Test with previews**: Verify variable replacement works correctly 3. **Provide meaningful content**: Don't leave variables empty 4. **Document purposes**: Keep track of what each variable represents ### Sending Process #### Batch Processing The system sends emails in batches to prevent: * **Rate limiting**: Avoiding SMTP provider limits * **Spam classification**: Preventing bulk email penalties * **System overload**: Managing server resources efficiently **Default Settings**: * Batch size: 10 emails per batch * Delay between batches: 1 second * Progress tracking: Real-time updates #### Progress Monitoring During sending: 1. **Progress bar**: Shows completion percentage 2. **Status updates**: Real-time sending status 3. **Batch tracking**: Number of batches completed 4. **Error handling**: Failed sends are logged #### Error Handling If errors occur during sending: * **Partial success**: Some emails may be sent successfully * **Error logging**: Failed attempts are recorded * **Retry logic**: System may attempt to resend failed emails * **Admin notification**: Significant errors trigger alerts ### Recipient Management #### Duplicate Handling The system automatically: 1. **Removes duplicates**: Same email address from multiple sources 2. **Preserves groups**: Maintains group membership information 3. **Combines lists**: Merges user groups and custom emails 4. **Final count**: Shows accurate recipient count #### Email Validation Before sending, the system: 1. **Format validation**: Checks email address syntax 2. **Domain validation**: Basic domain format checking 3. **Blacklist checking**: Removes known invalid domains 4. **User preferences**: Respects user email preferences ### Security and Compliance #### User Consent **Email Preferences**: The system respects user email preferences: * Users who disabled marketing emails are excluded from promotional bulk sends * Security notifications cannot be disabled * Users can opt out of newsletters and governance notifications **Unsubscribe Handling**: * All bulk emails should include unsubscribe options * Users can manage preferences in their profile * System honors opt-out requests automatically #### Spam Prevention **Rate Limiting**: * Automatic delays between batches * Configurable sending speeds * SMTP provider compliance **Content Guidelines**: * Avoid spam trigger words * Include proper sender identification * Provide clear unsubscribe options * Use authenticated sending domains ### Analytics and Tracking #### Bulk Send Metrics After sending, track: * **Total sent**: Number of emails successfully delivered * **Delivery rate**: Percentage of successful deliveries * **Bounce rate**: Failed delivery percentage * **Error details**: Specific failure reasons #### Integration with Email Analytics Bulk sends appear in the main email analytics: * **Recent Activity**: Shows bulk send campaigns * **Template Usage**: Tracks which templates are used most * **Performance Metrics**: Overall system health ### Use Cases #### Governance Communications **New Proposal Announcements**: * Template: `new_proposal_notification` * Recipients: Staked Users (voting eligible) * Variables: `proposal_title`, `voting_deadline`, `proposal_url` **Voting Reminders**: * Template: `voting_reminder` * Recipients: Staked Users who haven't voted * Variables: `proposal_title`, `time_remaining`, `vote_url` #### System Announcements **Platform Updates**: * Template: `system_update` * Recipients: All Users * Variables: `update_summary`, `changelog_url`, `maintenance_window` **Security Notifications**: * Template: `security_alert` * Recipients: All Users * Variables: `issue_description`, `action_required`, `support_url` #### Marketing Communications **Newsletter Distribution**: * Template: `monthly_newsletter` * Recipients: Users with newsletter enabled * Variables: `month_name`, `highlights`, `newsletter_url` **Event Announcements**: * Template: `event_invitation` * Recipients: Regular Members * Variables: `event_name`, `event_date`, `registration_url` ### Best Practices #### Planning Bulk Sends 1. **Define purpose**: Clear communication objectives 2. **Target audience**: Choose appropriate recipient groups 3. **Content review**: Proofread templates and variables 4. **Timing consideration**: Send at optimal times for your audience #### Testing Strategy 1. **Template testing**: Preview templates before bulk sending 2. **Small test groups**: Send to administrators first 3. **Variable verification**: Ensure all variables are properly set 4. **Delivery testing**: Verify emails reach different email providers #### Monitoring and Follow-up 1. **Track metrics**: Monitor delivery and engagement rates 2. **Handle bounces**: Address failed deliveries promptly 3. **User feedback**: Respond to user inquiries about bulk emails 4. **Adjust strategy**: Improve future campaigns based on results ### Troubleshooting #### Common Issues **No Recipients Selected**: * Verify user groups are selected or custom emails are entered * Check that selected groups contain users * Ensure email addresses are properly formatted **Template Variables Empty**: * Fill in all required template variables * Preview template to verify variable replacement * Check template configuration for required variables **Sending Failures**: * Verify SMTP configuration is working * Check email provider sending limits * Review error messages in recent activity logs **Low Delivery Rates**: * Check sender reputation with email providers * Verify domain authentication (SPF, DKIM) * Review email content for spam indicators This bulk email system provides powerful capabilities for reaching your DAO community while maintaining security, compliance, and deliverability best practices. # Email Analytics ## Email Analytics Monitor email performance, delivery rates, and user engagement through comprehensive analytics and reporting. ### Overview The email analytics system provides insights into: * **Delivery Performance**: Success rates and failure analysis * **Template Usage**: Most popular email templates * **Sending Volume**: Email activity over time * **Error Tracking**: Detailed failure information * **Trend Analysis**: Performance patterns and improvements ### Analytics Dashboard #### Accessing Analytics 1. Navigate to **Admin Dashboard → Settings → Email System** 2. Click on the **Analytics** tab 3. Select your desired time range (7, 30, or 90 days) #### Key Metrics Overview The dashboard displays four primary metrics cards: **Total Sent** * **Description**: Successfully delivered emails * **Icon**: Green checkmark * **Calculation**: Count of emails with 'sent' status * **Good Performance**: High numbers indicate active email system **Pending** * **Description**: Emails currently being processed * **Icon**: Yellow mail icon * **Calculation**: Count of emails with 'pending' status * **Normal Range**: Should be low during non-sending periods **Failed** * **Description**: Emails that couldn't be delivered * **Icon**: Red alert circle * **Calculation**: Count of emails with 'failed' status * **Target**: Keep as low as possible (< 5% of total) **Delivery Rate** * **Description**: Percentage of successful email deliveries * **Icon**: Blue trending up arrow * **Calculation**: (Total Sent / Total Emails) × 100 * **Benchmark**: Aim for > 95% delivery rate ### Charts and Visualizations #### Email Activity Over Time **Chart Type**: Bar chart showing daily email activity**Purpose**: Track sending patterns and identify peak usage**Data Displayed**: * Green bars: Successfully sent emails * Red bars: Failed deliveries * Yellow bars: Pending emails **Insights**: * Identify busy sending periods * Spot unusual activity spikes * Monitor system reliability over time #### Template Usage Distribution **Chart Type**: Pie chart showing template popularity**Purpose**: Understand which templates are used most frequently**Data Displayed**: * Template names with usage percentages * Color-coded segments for different templates * Hover tooltips with exact counts **Insights**: * Identify most valuable templates * Find unused templates for cleanup * Guide template optimization efforts ### Template Performance Analysis #### Performance Metrics Table For each email template, the system tracks: **Total Usage**: Number of times template was used**Sent Count**: Successfully delivered emails using this template**Failed Count**: Failed deliveries for this template**Success Rate**: Percentage of successful deliveries**Performance Badges**: Visual indicators for performance levels #### Performance Indicators **Success Rate Badges**: * **Green (Default)**: > 95% success rate * **Yellow (Secondary)**: 90-95% success rate * **Red (Destructive)**: < 90% success rate #### Template Optimization Use performance data to: 1. **Identify problematic templates**: Low success rates 2. **Optimize content**: Improve deliverability 3. **Update configurations**: Fix technical issues 4. **Archive unused templates**: Clean up template library ### Time Range Analysis #### Available Time Ranges **Last 7 Days**: Recent performance and immediate issues * Best for: Daily monitoring and quick issue identification * Update frequency: Real-time **Last 30 Days**: Monthly trends and pattern analysis * Best for: Regular performance reviews * Update frequency: Hourly **Last 90 Days**: Quarterly analysis and long-term trends * Best for: Strategic planning and system evaluation * Update frequency: Daily #### Comparative Analysis When switching time ranges, compare: * **Volume changes**: Increasing or decreasing email activity * **Performance trends**: Improving or degrading delivery rates * **Error patterns**: Recurring vs. one-time issues * **Template adoption**: New templates gaining popularity ### Error Analysis #### Error Categorization The system categorizes email failures into: **SMTP Errors**: * Authentication failures * Connection timeouts * Rate limiting issues * Server unavailability **Recipient Errors**: * Invalid email addresses * Mailbox full * Domain not found * Spam filtering **Content Errors**: * Template rendering failures * Variable substitution errors * Malformed HTML content * Size limitations #### Error Resolution **Common SMTP Errors**: 1. Check SMTP configuration settings 2. Verify credentials and authentication 3. Review provider rate limits 4. Test connection manually **Recipient Issues**: 1. Validate email address formats 2. Clean email lists regularly 3. Handle bounces appropriately 4. Monitor reputation scores **Content Problems**: 1. Test templates before deployment 2. Validate all required variables 3. Check HTML formatting 4. Monitor email size limits ### Performance Benchmarks #### Industry Standards **Delivery Rate**: > 95% * Excellent: > 98% * Good: 95-98% * Needs improvement: < 95% **Bounce Rate**: < 5% * Excellent: < 2% * Acceptable: 2-5% * High: > 5% **Failure Rate**: < 3% * Excellent: < 1% * Acceptable: 1-3% * High: > 3% #### DAO-Specific Considerations **Governance Emails**: Higher engagement expected * Target delivery rate: > 98% * Critical for voting notifications * Monitor closely during voting periods **Transactional Emails**: Must be highly reliable * Target delivery rate: > 99% * Includes purchase confirmations, security alerts * Immediate delivery required **Marketing Emails**: May have higher bounce rates * Target delivery rate: > 90% * Users may opt out more frequently * Monitor unsubscribe rates ### Automated Reporting #### Daily Reports Automated daily summaries include: * Previous day's sending volume * Delivery rate performance * Any error spikes or issues * Template usage changes #### Weekly Reports Weekly analytics reports provide: * 7-day performance trends * Template performance comparison * Error pattern analysis * Recommendations for improvement #### Monthly Reports Comprehensive monthly reports feature: * Complete performance analysis * Template optimization suggestions * System health assessment * Strategic recommendations ### Data Export #### Available Export Formats **CSV Export**: Raw data for external analysis * Email logs with timestamps * Success/failure status * Template usage statistics * Error details and codes **PDF Reports**: Formatted analytics summaries * Executive summary format * Charts and visualizations * Performance benchmarks * Recommendations section #### Export Process 1. Select desired time range 2. Choose export format (CSV or PDF) 3. Click export button 4. Download generated file 5. Import into external tools if needed ### Integration with Other Systems #### Supabase Analytics Email analytics integrate with Supabase's built-in analytics: * Database query performance * Function execution metrics * API usage statistics * Overall system health #### External Tools Export data for use with: * **Google Analytics**: Track email-driven website traffic * **Business Intelligence**: Comprehensive performance dashboards * **CRM Systems**: Customer communication tracking * **Marketing Platforms**: Campaign performance analysis ### Troubleshooting Analytics #### Missing Data If analytics show no data: 1. Verify time range selection 2. Check if any emails were sent in the period 3. Confirm database connectivity 4. Review error logs for issues #### Incorrect Metrics If numbers seem wrong: 1. Cross-reference with email logs 2. Check for timezone differences 3. Verify data aggregation logic 4. Compare with SMTP provider statistics #### Performance Issues If analytics load slowly: 1. Reduce time range scope 2. Check database performance 3. Clear browser cache 4. Contact system administrator ### Best Practices #### Regular Monitoring 1. **Daily checks**: Review key metrics during active periods 2. **Weekly analysis**: Identify trends and patterns 3. **Monthly reviews**: Comprehensive performance evaluation 4. **Quarterly planning**: Strategic improvements and goals #### Data-Driven Decisions Use analytics to: 1. **Optimize sending times**: Find peak engagement periods 2. **Improve templates**: Focus on high-performing content 3. **Clean email lists**: Remove consistently failing addresses 4. **Plan capacity**: Prepare for high-volume periods #### Continuous Improvement 1. **Set benchmarks**: Establish performance goals 2. **Track progress**: Monitor improvement over time 3. **Test changes**: A/B test template modifications 4. **Document learnings**: Keep records of successful optimizations This comprehensive analytics system ensures you have complete visibility into your email system's performance and can make data-driven decisions to improve communication effectiveness. # User Preferences ## User Email Preferences Allow users to control their email subscriptions and notification settings to improve engagement and comply with privacy regulations. ### Overview The user email preferences system enables: * **Individual Control**: Users manage their own email settings * **Granular Options**: Different notification types can be toggled independently * **Privacy Compliance**: Respects user consent and preferences * **Easy Management**: Simple interface for preference updates * **Bulk Controls**: Option to unsubscribe from non-essential emails ### Accessing Email Preferences #### For Users 1. Navigate to **Profile** page from the dashboard 2. Look for the **"Email Preferences"** section 3. Toggle individual preference switches as desired 4. Changes are saved automatically #### For Administrators Administrators can view (but not modify) user preferences through: * User management interfaces * Analytics dashboards showing preference trends * Bulk email sender (respects user preferences automatically) ### Email Preference Categories #### Newsletter Subscription **Purpose**: Weekly newsletter with DAO updates and insights**Default**: Enabled for new users**User Control**: Can be disabled at any time**Impact**: Users won't receive newsletter emails when disabled **Content Includes**: * DAO community updates * Weekly governance summary * Member spotlights * Educational content * Industry news relevant to the DAO #### Governance Notifications **Purpose**: Updates about proposals, voting, and governance activities**Default**: Enabled for new users**User Control**: Can be disabled, but not recommended for active members**Impact**: Users may miss important voting opportunities **Content Includes**: * New proposal notifications * Voting deadlines and reminders * Proposal status updates * Governance process changes * Community discussions #### Transaction Notifications **Purpose**: Confirmations and updates for financial transactions**Default**: Enabled for new users**User Control**: Can be disabled (not recommended)**Impact**: Users won't receive purchase confirmations, staking updates **Content Includes**: * Token purchase confirmations * Staking transaction confirmations * Reward distribution notifications * Payment processing updates * Wallet connection confirmations #### Security Notifications **Purpose**: Important security alerts and account changes**Default**: Enabled for new users (strongly recommended to keep enabled)**User Control**: Can be disabled (strongly discouraged)**Impact**: Users may miss critical security information **Content Includes**: * Password reset requests * Account login notifications * Security setting changes * Suspicious activity alerts * Two-factor authentication updates #### Marketing Emails **Purpose**: Promotional content, product updates, and special offers**Default**: Disabled for new users (opt-in required)**User Control**: Full control (opt-in/opt-out)**Impact**: Users won't receive promotional communications **Content Includes**: * Product announcements * Special promotions * Partnership announcements * Event invitations * Educational webinars ### Preference Management Interface #### Individual Toggles Each preference category features: * **Switch Control**: Easy on/off toggle * **Category Icon**: Visual identifier for each type * **Description Text**: Clear explanation of what emails are included * **Color Coding**: Different colors for each category type **Visual Design**: * Newsletter: Blue megaphone icon * Governance: Green bell icon * Transactions: Purple dollar sign icon * Security: Red shield icon * Marketing: Orange mail icon #### Bulk Actions **Unsubscribe from All Non-Essential**: Quick action to disable most email types * Disables: Newsletter, governance, marketing emails * Keeps enabled: Security notifications, transaction confirmations * One-click convenience for users who want minimal emails #### Auto-Save Functionality * Changes save automatically when toggled * No submit button required * Immediate feedback with toast notifications * Loading states during save operations ### Default Settings for New Users When new users join the platform: ``` Newsletter: ✓ Enabled Governance: ✓ Enabled Transactions: ✓ Enabled Security: ✓ Enabled Marketing: ✗ Disabled (requires opt-in) ``` This configuration ensures: * Users receive important operational information * Marketing requires explicit consent * Users can immediately adjust preferences * Compliance with email regulations ### Privacy and Compliance #### GDPR Compliance **Consent Management**: * Clear descriptions of email types * Easy opt-out mechanisms * Granular control over data usage * Explicit consent for marketing emails **Data Subject Rights**: * Users can view their current preferences * Full control over email subscriptions * Easy unsubscribe options * Data deletion requests honored #### CAN-SPAM Act Compliance **Required Elements**: * Clear identification of sender * Honest subject lines * Physical address disclosure * Easy unsubscribe mechanism * Prompt processing of opt-out requests #### Double Opt-In (Optional) For marketing emails, consider implementing: * Confirmation email for marketing opt-ins * Verification of email address ownership * Documentation of consent timestamp * Audit trail for compliance purposes ### Integration with Email Sending #### Automatic Filtering When sending emails, the system automatically: 1. **Checks user preferences**: Before adding recipients to send lists 2. **Filters by category**: Only includes users who opted in for that email type 3. **Respects bulk unsubscribe**: Honors "unsubscribe all" selections 4. **Maintains audit trail**: Logs preference-based filtering decisions #### Bulk Email Sender Integration The bulk email sender respects preferences by: * **Pre-filtering recipients**: Removes users who opted out of relevant categories * **Showing filtered counts**: Displays how many users were excluded * **Category matching**: Maps email templates to preference categories * **Override protection**: Prevents sending to opted-out users #### Template-to-Preference Mapping | Template Type | Preference Category | Behavior | | ----------------------- | ------------------- | --------------------------------- | | `newsletter` | Newsletter | Filtered by newsletter preference | | `new_proposal` | Governance | Filtered by governance preference | | `voting_reminder` | Governance | Filtered by governance preference | | `purchase_confirmation` | Transactions | Always sent (essential) | | `security_alert` | Security | Always sent (critical) | | `marketing_promo` | Marketing | Filtered by marketing preference | ### Analytics and Reporting #### Preference Statistics Track user preference trends: * **Opt-in rates**: Percentage of users enabling each category * **Opt-out trends**: Which preferences are disabled most often * **Segmentation data**: User engagement by preference settings * **Compliance metrics**: Marketing consent rates #### Preference Impact Analysis Monitor how preferences affect: * **Email delivery volume**: Reduction due to user opt-outs * **Engagement rates**: Whether targeted users engage more * **Unsubscribe rates**: If granular control reduces global unsubscribes * **User satisfaction**: Feedback on preference control ### Best Practices #### User Experience 1. **Clear labeling**: Make preference purposes obvious 2. **Immediate feedback**: Show when preferences are saved 3. **Easy access**: Link to preferences from all emails 4. **Mobile friendly**: Ensure preferences work on all devices #### Communication Strategy 1. **Respect choices**: Honor preferences consistently 2. **Value proposition**: Explain benefits of staying subscribed 3. **Frequency control**: Don't overwhelm even opted-in users 4. **Quality content**: Make emails worth subscribing to #### Technical Implementation 1. **Real-time updates**: Preferences take effect immediately 2. **Backup preferences**: Maintain preference history 3. **System integration**: All email systems check preferences 4. **Error handling**: Graceful degradation if preference system is unavailable ### Troubleshooting #### Users Still Receiving Unwanted Emails **Check**: 1. Preference settings are correctly saved 2. Email templates are properly categorized 3. Bulk sender respects preference filters 4. No override flags are set inappropriately #### Preferences Not Saving **Investigate**: 1. Database connectivity issues 2. User authentication problems 3. Browser compatibility issues 4. Network connectivity problems #### Missing Preference Options **Verify**: 1. User interface is displaying all categories 2. Database schema includes all preference fields 3. User has proper permissions to view preferences 4. No errors in preference loading logic ### Migration and Updates #### Adding New Preference Categories When adding new email types: 1. **Update database schema**: Add new preference fields 2. **Set sensible defaults**: Usually disabled for existing users 3. **Update user interface**: Add new toggle controls 4. **Map to email templates**: Connect templates to new preferences 5. **Communicate changes**: Inform users about new controls #### Modifying Existing Categories When changing preference behavior: 1. **Communicate changes**: Notify users in advance 2. **Preserve user choices**: Don't reset existing preferences 3. **Update documentation**: Keep user guides current 4. **Test thoroughly**: Ensure changes work as expected This comprehensive preference system ensures users have full control over their email experience while maintaining essential communications and regulatory compliance. # Glossary # FAQs