diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..4e582af --- /dev/null +++ b/README.en.md @@ -0,0 +1,47 @@ +# ๐ Digital Legal Entity (DLE) - Application Template + +**๐ Language / ะฏะทัะบ:** [๐ท๐บ ะ ัััะบะธะน](README.md) | [๐ฌ๐ง English](README.en.md) + +## Description +Complete Digital Legal Entity application template + +## ๐ Requirements +- Docker and Docker Compose + +## ๐ Documentation +- [General materials and instructions](docs-en/README.md) | [ะ ัััะบะธะน](docs/README.md) +- [Legal documents](legal-en/README.md) | [ะ ัััะบะธะน](legal/README.md) + +## ๐ Quick Start + +### Automatic installation (recommended) +```bash +curl -fsSL https://raw.githubusercontent.com/VC-HB3-Accelerator/DLE/main/setup-template.sh | bash +``` + +The script automatically downloads the latest artifacts from the release and deploys `docker-data`. + +### ๐ฆ Releases and artifacts +- [Release v1.0.0](https://github.com/VC-HB3-Accelerator/DLE/releases/tag/v1.0.0) โ contains an archive split into parts (`dle-template.tar.gz.part-*`) that is installed together with the script. + +### Running the application +```bash +docker-compose up -d +``` + +### Access to the application + +#### Production +- **Frontend**: http://localhost:9000 (HTTP) or https://localhost:9443 (HTTPS) + +### Stopping +```bash +docker-compose down +``` + +### ๐ **Contacts:** +- **Email:** info@hb3-accelerator.com +- **Website:** https://hb3-accelerator.com +- **GitHub:** https://github.com/VC-HB3-Accelerator +- **Support:** https://hb3-accelerator.com/ + diff --git a/README.md b/README.md index 4b8c60f..3bff47b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # ๐ Digital Legal Entity (DLE) - ะจะฐะฑะปะพะฝ ะฟัะธะปะพะถะตะฝะธั +**๐ Language / ะฏะทัะบ:** [๐ท๐บ ะ ัััะบะธะน](README.md) | [๐ฌ๐ง English](README.en.md) + ## ะะฟะธัะฐะฝะธะต ะะพะปะฝัะน ัะฐะฑะปะพะฝ ะฟัะธะปะพะถะตะฝะธั Digital Legal Entity @@ -7,8 +9,8 @@ - Docker ะธ Docker Compose ## ๐ ะะพะบัะผะตะฝัะฐัะธั -- [ะะฑัะธะต ะผะฐัะตัะธะฐะปั ะธ ะธะฝััััะบัะธะธ](docs/README.md) -- [ะฎัะธะดะธัะตัะบะธะต ะดะพะบัะผะตะฝัั](legal/README.md) +- [ะะฑัะธะต ะผะฐัะตัะธะฐะปั ะธ ะธะฝััััะบัะธะธ](docs/README.md) | [English](docs-en/README.md) +- [ะฎัะธะดะธัะตัะบะธะต ะดะพะบัะผะตะฝัั](legal/README.md) | [English](legal-en/README.md) ## ๐ ะัััััะน ะทะฐะฟััะบ diff --git a/docs-en/FAQ.md b/docs-en/FAQ.md new file mode 100644 index 0000000..537ba33 --- /dev/null +++ b/docs-en/FAQ.md @@ -0,0 +1,1196 @@ +# FAQ - Frequently Asked Questions about Digital Legal Entity (DLE) + +## ๐ Table of Contents + +1. [General Questions](#general-questions) +2. [Licensing and Payment](#licensing-and-payment) +3. [Installation and Deployment](#installation-and-deployment) +4. [Blockchain and Smart Contracts](#blockchain-and-smart-contracts) +5. [Asset Tokenization](#asset-tokenization) +6. [Voting System](#voting-system) +7. [AI Assistant](#ai-assistant) +8. [Technical Support](#technical-support) +9. [Functionality](#functionality) +10. [Security](#security) +11. [Updates](#updates) +12. [Economic Impact](#economic-impact) + +--- + +## General Questions + +### What is Digital Legal Entity (DLE)? + +**DLE** is a comprehensive web application for business management with blockchain integration, including: + +- **CRM and contact management** - centralized customer database with interaction history +- **AI assistant with vector search** - local AI for business process automation +- **Omnichannel communication system** - Telegram, Email, Web chat, SMS in a single interface +- **Blockchain integration** - multi-chain support (Ethereum, Polygon, BSC, Arbitrum, Optimism, Avalanche, Base) +- **Blockchain governance** - through smart contracts and token holder voting +- **Asset tokenization** - converting any assets into digital tokens +- **Groups and team spaces** - customizable spaces for projects with permission system + +### Who is DLE for? + +DLE is designed for **all types of organizations** that need transparent collective governance: + +- **Commercial organizations** (LLC, JSC, Sole Proprietorship, holdings) +- **Non-profit organizations** (NPOs, foundations, associations) +- **Government structures** (municipalities, agencies) +- **International organizations** (intergovernmental, global) +- **Investment funds** and **venture companies** +- **Startups** and **small businesses** +- **Cooperatives** and **associations** +- **Any other organizations** with collective governance needs + +### How is it different from SaaS solutions? + +| Parameter | DLE | Regular SaaS | +|-----------|-----|--------------| +| **Data ownership** | Full (on your infrastructure) | Data with provider | +| **Control** | 100% control | Limited | +| **Payment** | One-time (perpetual license) | Monthly subscription | +| **Customization** | Full | Limited | +| **Legal compliance** | For your region | Depends on provider | +| **AI without limits** | Free | $200+/month | +| **Blockchain** | Built-in | None or additional fee | +| **Updates** | Free for 5 years (for token holders) | Depends on plan | + +### What technologies are used? + +- **Frontend**: Vue.js 3 + Vite + Element Plus +- **Backend**: Node.js + Express +- **Database**: PostgreSQL + pgvector +- **AI**: Ollama (local LLM models) + FAISS Vector Search (RAG) +- **Blockchain**: Ethers.js v6, Hardhat, OpenZeppelin +- **Containerization**: Docker Compose +- **Package manager**: Yarn + +--- + +## Licensing and Payment + +### How much does DLE cost? + +**Price overview:** + +| License Type | Price | Management Tokens | Votes | +|--------------|-------|-------------------|-------| +| **Standard** | $1,000 USDT | 1 token | 1 vote | +| **Priority** | $10,000 USDT | 10 tokens | 10 votes | + +**โ ๏ธ Important**: +- All prices are WITHOUT TAXES +- Payment and conversion fees are paid by the buyer +- Service terms are the same for both licenses + +### What is included in the license? + +โ **All licenses include:** +- Lifetime access to the application +- All future updates free +- Technical support through portal +- AI assistant 24/7 without limits +- Participation in voting for new features +- Online training sessions (group and individual) +- Full source code with documentation + +**The only difference** - the number of votes in the governance system. + +### Are there subscriptions or monthly payments? + +**No!** DLE uses a **perpetual license** model: +- Pay once +- Access forever +- All updates free for 5 years for license token holders (see [legal/service-terms.md](../legal-en/service-terms.md)) +- No hidden fees +- AI works without request limits + +### What license types are available? + +**Two license types** (difference only in number of votes): + +| License Type | Price | Tokens | Votes | Influence | +|--------------|-------|--------|-------|-----------| +| **Standard** | $1,000 USDT | 1 token | 1 vote | Basic | +| **Priority** | $10,000 USDT | 10 tokens | 10 votes | Enhanced | + +**Service terms are the same** for both licenses. + +### What are governance tokens? + +**Governance tokens** are ERC20 tokens on the blockchain that provide: +- **Voting rights** for product development (1 token = 1 vote) +- **Participation in voting** for new features +- **Influence on development priorities** +- **Access to governance**: https://hb3-accelerator.com/ + +### Can I use multiple types of activities? + +**No, one license = one type of activity**: +- Each license is tied to one type of business +- Different types of activities require separate licenses +- You can redefine the type of activity, but only one at a time + +### What is included in technical support? + +**All license holders receive**: +- ๐ **Support portal**: https://hb3-accelerator.com/ +- ๐ฌ **Support chat** 24/7 +- ๐ค **AI assistant** for consultations +- ๐ **Online training sessions** (group and individual) +- ๐ **Library of recordings** of all sessions +- ๐ง **Email support** + +### How does the voting system work? + +**Democratic product governance**: +1. **Proposals** - community proposes new features +2. **Voting** - token holders vote (1 token = 1 vote) +3. **Quorum** - decisions are made with 51%+ votes +4. **Implementation** - approved features go into development + +**Web application for voting**: https://hb3-accelerator.com/ + +### Is there a money-back guarantee? + +**Yes, 70% refund program** within 5 years, if: +- More than 51% negative votes accumulated +- Complaints concern lack of updates +- Voting conducted through blockchain +- Request submitted within 5 years of purchase + +### Are taxes included in the price? + +**NO! All prices are WITHOUT TAXES**: +- Buyer independently pays all taxes +- VAT - 15-25% depending on country +- Sales Tax - in USA and other countries +- Income Tax - depends on tax status +- Customs duties - when importing to certain countries + +### Who pays payment fees? + +**ALL FEES ARE PAID BY THE BUYER**: +- **Currency conversion**: 1-5% of amount +- **Bank transfers**: $10-50+ per transaction +- **Blockchain gas fees**: $1-50+ depending on network +- **Payment system fees**: 2-5% of amount + +**Example total costs**: +- USDT directly: $1,000 + $15-80 = $1,015-1,080 +- SWIFT transfer: $1,000 + $25-80 = $1,025-1,080 +- Card in EUR: โฌ899 + โฌ30-45 = โฌ929-944 + +### How can I pay for the license? + +**Available payment methods**: +- ๐ต **USDT** - directly to addresses of authorized partners +- ๐ณ **Local currency** - equivalent in buyer's country currency +- ๐ฆ **Bank transfer** - through authorized dealers +- ๐ณ **Credit cards** - through partner payment systems + +### Where can I buy a license? + +**Official channels**: +- ๐ง **Directly from author**: info@hb3-accelerator.com +- ๐ **Web application**: https://hb3-accelerator.com/ +- ๐ค **Authorized dealers** - companies with official permission + +## Installation and Deployment + +### What are the system requirements? + +**Minimum requirements**: +- **CPU**: 4 cores +- **RAM**: 12 GB (4 GB application + 6 GB AI + 2 GB Vector Search) +- **Storage**: 100 GB SSD +- **OS**: Ubuntu 20.04+, Debian 11+, CentOS 8+, any Linux with Docker + +**Recommended**: +- **CPU**: 8+ cores +- **RAM**: 32 GB+ +- **Storage**: 500 GB+ NVMe SSD +- **GPU**: NVIDIA (accelerates AI 5-10x) + +### How to deploy DLE? + +**Simple installation via Docker**: +1. Clone repository +2. Run `docker-compose up -d` +3. Open http://localhost:9000 +4. Connect wallet +5. Configure RPC providers +6. Deploy smart contracts + +### Can I deploy in the cloud? + +**Yes, all options are supported**: +- **Own server** - full control +- **Cloud platforms** - AWS, Google Cloud, Azure +- **Local infrastructure** - for regulatory compliance +- **Docker Compose** - deployment with one command + +### How to connect a crypto wallet? + +**Step-by-step instructions**: +1. Install browser wallet (MetaMask, WalletConnect or similar) +2. Create or import account with governance token +3. In web application click **"Connect Wallet"** +4. Select wallet type and confirm connection +5. After successful connection, you'll see account address in top corner + +### How to configure RPC providers? + +**Blockchain network configuration**: +1. Go to **Settings** โ **Security** tab +2. Find **"RPC Providers"** section and click **"Add"** +3. Fill form for each network: + - **Network name** (Ethereum, Polygon, BSC) + - **RPC URL** (e.g.: `https://eth-mainnet.g.alchemy.com/v2/YOUR-API-KEY`) + - **Network ID** (Chain ID) +4. Click **"Save"** for each provider +5. System automatically checks connection correctness + +### How to deploy smart contracts? + +**Multi-chain deployment**: +1. Go to **Settings** โ **Blockchain** tab +2. Fill form +3. Click **"Start Deployment"** +4. Wait for completion (30-120 seconds) +5. Copy deployed contract address +6. Configure authentication via smart contract + +### How to configure authentication via smart contract? + +**Access configuration**: +1. Go to **Settings** โ **Authentication** tab +2. Paste smart contract address +3. Set thresholds: + - **Minimum tokens for editing** (e.g.: 100 tokens) + - **Minimum tokens for viewing** (e.g.: 1 token) + +### How to configure AI and database? + +**AI configuration**: +1. Go to **Settings** โ **AI** tab +2. Open **"Database"** subsection +3. Replace default passwords +4. Click **"Generate new encryption key"** +5. **Save key in secure place** (needed for data recovery) + +### How to configure internet access? + +**Application publishing**: +1. Go to **Settings** โ **Server** tab +2. Select **WEB SSH** or suitable service +3. Fill form for migration to VDS with: + - **Public IP address** + - **Domain name connection** +4. Click **"Publish"** +5. Wait for migration completion + +**โน๏ธ Required**: Registered domain name and access to DNS settings + +### How to configure legal documents? + +**Filling legal information**: +1. Go to **CRM** โ **Content** section +2. Open **"Company Legal Information"** form +3. Fill fields. Click **"Save"** + +**Working with templates**: +1. In **Content** section โ **"Templates"** +2. Select necessary documents: + - Privacy Policy + - Terms of Service + - Personal Data Processing Consent + - Cookie Usage Policy +3. Click **"Preview"** to check +4. Select action: + - **"Publish for public use"** + - **"Publish for internal use"** + - **"Print"** (export to PDF) + +**โ ๏ธ Recommendation**: Consult with lawyer before publishing documents + +--- + +## Functionality + +### What is the AI assistant in DLE? + +**AI Assistant** is a built-in intelligent assistant that uses: +- ๐ง **Ollama** - local open-source AI models (qwen2.5:7b) +- ๐ **Vector search** - FAISS for semantic search +- ๐ **RAG** (Retrieval-Augmented Generation) - knowledge base search +- ๐พ **Caching** - instant answers to frequent questions + +**Key advantages**: +1. **๐ 100% local** - all data on your server +2. **๐ Full privacy** - nothing goes to cloud +3. **โก Lightning-fast responses** - caching and vector search +4. **๐ฐ Zero API costs** - no payment for tokens +5. **๐ Learns from your data** - personalized answers +6. **๐ Multilingual** - supports Russian, English and more +7. **๐ 24/7 availability** - works around the clock + +### What are the AI assistant capabilities? + +**15 key application areas**: + +1. **๐ Customer service and support** - automatic responses 24/7, sentiment analysis, escalation of complex questions +2. **๐ Analytics and business intelligence** - big data analysis, sales forecasting, customer segmentation +3. **๐ฐ Financial planning and accounting** - automatic bookkeeping, cash flow forecasting, profitability analysis +4. **๐ฏ Marketing and sales** - content generation, message personalization, A/B testing, sales funnel management +5. **๐ฅ HR and personnel management** - resume screening, chatbot interviews, training planning, performance analysis +6. **๐ Project and task management** - automatic project planning, progress tracking, process optimization +7. **๐ Research and development** - market analysis, technology research, new product idea generation +8. **๐ก๏ธ Security and compliance** - security monitoring, threat detection, compliance analysis +9. **๐ Operational efficiency** - supply chain optimization, production planning, process automation +10. **๐ Training and development** - personalized training programs, interactive course creation, knowledge assessment +11. **๐ International operations** - automatic translation, cultural analysis, content adaptation +12. **๐ฎ Strategic planning** - macroeconomic trend analysis, scenario planning, investment evaluation +13. **๐ฑ Mobile and digital solutions** - mobile app development, chatbot creation, voice assistants +14. **๐ญ Industry solutions** - specialized solutions for healthcare, finance, retail, manufacturing +15. **๐ Integration and automation** - API integrations, workflow automation, unified ecosystem creation + +**Economic impact**: $507,600-519,600/year with ROI 50,760-51,960% + +### How does the AI assistant work? + +**Philosophy**: AI doesn't replace people, but becomes their co-pilot, freeing 85% of time for strategy and creativity. + +**Work architecture**: +1. **User asks question** โ "How to return product?" +2. **Question vectorization** โ Ollama mxbai-embed-large:latest (Text โ Vector [768 numbers]) +3. **Vector search (FAISS)** โ Search similar questions in database (Top-3 results by semantics) +4. **Contextual search (RAG)** โ Extract answers from knowledge base, filter by tags/products +5. **Answer generation (LLM)** โ Ollama qwen2.5:7b (Context + Question โ Answer) +6. **Caching** โ Save to cache for 1 hour (next same question < 50ms) +7. **Answer to user** โ "Product can be returned within..." + +**Technology stack**: +- **LLM model**: Ollama qwen2.5:7b (text generation, dialogue) +- **Embedding model**: mxbai-embed-large (text vectorization) +- **Vector DB**: FAISS (fast semantic search) +- **Main DB**: PostgreSQL (knowledge base storage) +- **Cache**: Node.js Map + TTL (accelerate repeated requests) +- **Queue**: AI Queue (priority task processing) + +### What are omnichannel communications? + +**Unified interface for all channels**: +- ๐ฌ **Telegram bot** - integration via Bot API +- ๐ง **Email** - SMTP/IMAP, Gmail, Outlook +- ๐ **Web chat** - website widget +- ๐ฑ **SMS** - integration via providers +- ๐ **Web forms** - form builder + +**Advantages**: +- One context for customer across all channels +- Automatic message routing +- AI auto-responses trained on your data +- Analytics by channel and response time + +### What is the electronic tables system? + +**Full-featured database** with graphical interface: +- โ **6 field types** (text, number, relation, lookup, etc.) +- โ **Relations between tables** (1:1, 1:N, N:N) +- โ **Lookup and data substitution** +- โ **Filtering and sorting** +- โ **Real-time updates** (WebSocket) +- โ **AI integration** (RAG for search) +- โ **Encryption** of all data (AES-256) + +### What are groups and spaces? + +**Team organization**: +- Create spaces for projects +- Invite participants +- Distribute roles and permissions (20+ types) +- Isolated data between groups +- Roles: Editor, ReadOnly, User + +--- + +## AI Assistant + +### What AI models are installed by default? + +**LLM models**: +- **qwen2.5:7b** (recommended) โ for Russian language, 4.7 GB + +**Embedding models**: +- **mxbai-embed-large:latest** (recommended) โ 670 MB + +### How to create a knowledge base for AI? + +**Creating FAQ table**: +1. Go to **Tables** โ **"+ Create Table"** +2. Fill: + - **Name**: `FAQ - Frequently Asked Questions` + - **Description**: `Knowledge base for AI assistant on customer service` + +**Column setup** (required): +- **Question** (Text, purpose: "Question for AI") โญ +- **Answer** (Text, purpose: "AI Answer") โญ +- **Product** (Multiselect, product filter) +- **Tags** (Multiselect, user tags) +- **Priority** (Number, priority) + +**Activation for AI**: +1. In table settings enable **"Use as source for AI"** โ +2. Click **"Save"** + +### How to configure system prompt? + +**Basic prompt**: +``` +You are a professional customer support assistant. + +Rules: +1. Answer politely and professionally +2. Use information from knowledge base +3. If information is not available โ suggest contacting operator +4. Answer briefly and to the point +5. Always end with question "How else can I help?" +``` + +**Advanced prompt** (with personalization): +``` +You are a professional customer support assistant for "Your Company Name". + +About company: +- We are engaged in [brief business description] +- Our values: quality, reliability, customer focus + +Communication style: +- Friendly but professional +- Address customer as "You" +- Use emojis moderately (1-2 per message) + +Response rules: +1. First search answer in knowledge base (RAG) +2. If found โ answer based on found information +3. If not found โ honestly say and offer operator help +4. Don't make up information about prices, terms, conditions +5. For complex questions offer to contact manager + +Always end with: "How else can I help? ๐" +``` + +### How to configure AI rules? + +**Creating rule set**: +1. Click **"Create"** next to "Rule Set" field +2. Fill: + - **Name**: `Hybrid mode (RAG + generation)` + - **Description**: `AI first searches knowledge base, if not found โ generates answer` + +**Rules (JSON)**: +```json +{ + "checkUserTags": true, + "searchRagFirst": true, + "generateIfNoRag": true, + "temperature": 0.7, + "maxTokens": 500 +} +``` + +**Parameters**: +- `checkUserTags: true` โ consider user tags in search +- `searchRagFirst: true` โ first search knowledge base +- `generateIfNoRag: true` โ generate answer if nothing found +- `temperature: 0.7` โ balance between accuracy and creativity (0.0-1.0) +- `maxTokens: 500` โ maximum answer length + +### How to configure RAG search? + +**Basic settings**: +- **Search method**: `Hybrid search` (recommended) +- **Maximum results**: `5` +- **Relevance threshold**: `0.1` (from 0.01 to 1.0) + +**Keyword extraction**: +- โ **Enable keyword extraction** +- **Minimum word length**: `3` +- **Maximum keywords**: `10` +- โ **Remove stop words** + +**Search weights (for hybrid)**: +- **Semantic search**: `70%` (accuracy) +- **Keyword search**: `30%` (speed) + +**Additional settings**: +- โ **Fuzzy search** (for typos) +- โ **Word stemming** (finds different word forms) +- โ **Synonym search** (currently disabled) + +### How to test AI assistant? + +**Built-in tester**: +1. In AI assistant settings find **"๐ง Test RAG functionality"** +2. Select table `FAQ - Frequently Asked Questions` +3. Enter test question: `How to pay for order?` +4. Click **"Test RAG"** +5. Check result: + - **Score -300 to 0** โ โ excellent match + - **Score 0 to 300** โ ๏ธ โ average match + - **Score >300** โ โ match not found + +**Testing via Web Chat**: +1. Find **"๐ฌ Chat with AI"** widget on main page +2. Enter question: `How much is delivery?` +3. Check AI response + +### How to integrate with Telegram and Email? + +**Telegram bot setup**: +1. Create bot via [@BotFather](https://t.me/botfather) in Telegram +2. Copy **Bot Token** +3. In DLE settings enter token and bot username +4. In AI assistant settings select this Telegram bot + +**Email integration setup**: +1. Go to **Settings** โ **Integrations** โ **Email** +2. Fill IMAP settings (for receiving emails) +3. Fill SMTP settings (for sending emails) +4. Click **"Test IMAP"** and **"Test SMTP"** to verify +5. In AI assistant settings select this Email + +## Economic Impact + +### How much can I save with DLE? + +**Comparison with SaaS over 5 years**: + +**Typical SaaS stack**: +- CRM (HubSpot): $200/month ร 60 months = $12,000 +- Chatbot (Intercom): $150/month ร 60 months = $9,000 +- Email (SendGrid): $100/month ร 60 months = $6,000 +- AI (ChatGPT API): $200/month ร 60 months = $12,000 +- **TOTAL**: $39,000 + +**DLE**: +- License (one-time): $1,000 +- Updates (5 years): $0 +- AI without limits: $0 +- **TOTAL**: $1,000 +- **SAVINGS**: $38,000 + +### What is the ROI from AI assistant? + +**Comparison with cloud solutions**: + +| Characteristic | DLE AI (Local) | ChatGPT API | Claude API | +|----------------|----------------|-------------|------------| +| **Cost** | $0 | ~$0.02/request | ~$0.03/request | +| **Privacy** | โ 100% | โ Data in OpenAI | โ Data in Anthropic | +| **Speed (cache)** | 50ms | 500-2000ms | 500-2000ms | +| **Offline work** | โ Yes | โ No | โ No | +| **Business customization** | โ Full | โ ๏ธ Limited | โ ๏ธ Limited | +| **API limits** | โ No | โ Yes | โ Yes | + +**Savings when using cloud APIs**: +- At 10,000 requests/month: ChatGPT $2,400/year, Claude $3,600/year, DLE $0/year +- At 50,000 requests/month: ChatGPT $12,000/year, Claude $18,000/year, DLE $0/year +- At 100,000 requests/month: ChatGPT $24,000/year, Claude $36,000/year, DLE $0/year + +**Total savings across all areas**: +- Customer service: $57,600 +- Supplier work + AI buyer: $64,800 +- Partner work: $43,200 +- Staff training: $30,000 +- Personnel management: $57,600 +- Reporting and analysis: $144,000 +- Content marketing: $86,400 +- API token savings: $24,000-36,000 +- **TOTAL**: $507,600-519,600/year + +**ROI**: 50,760-51,960% or 507-519x return + +### What are additional benefits from AI assistant? + +**Immeasurable advantages**: +- ๐ **Improved work quality** - AI works without fatigue and errors +- ๐ **Customer satisfaction +19%** - fast and accurate answers +- ๐ฅ **Employee retention +15%** - less routine, more interesting tasks +- ๐ **Decision speed +300%** - instant access to information +- ๐ก **More time for strategy** - AI frees 85% of time from routine +- ๐ฏ **Less routine, more creativity** - focus on business development + +### How much savings on asset tokenization? + +**Traditional real estate transaction ($1M)**: +- Realtor commission: 3-5% = $30,000-50,000 +- Legal services: $5,000-10,000 +- Property registration: $2,000-5,000 +- Time: 2-6 months +- **TOTAL**: $37,000-65,000 + +**Tokenized transaction via DLE**: +- Gas fees: $50-200 +- Smart contract (one-time): $500 +- Time: 5-10 minutes +- **TOTAL**: $550-700 + +**Savings**: 99% of costs and 99% of time + +--- + +## Web Application Questions + +### How to access DLE web application? + +**Access requirements**: +- Having DLE governance tokens in your wallet +- Wallet connection (MetaMask, WalletConnect, etc.) +- Stable internet connection + +**Login process**: +1. Open web application: https://hb3-accelerator.com/ +2. Click "Connect Wallet" +3. Select your wallet (MetaMask, WalletConnect) +4. Confirm connection +5. System checks token balance in smart contract +6. If tokens present - access granted + +**Access levels**: +- **0 tokens**: No access (only "No access" page) +- **1+ tokens**: ReadOnly (view data) +- **100+ tokens**: Editor (editing, creation) +- **Any amount**: Voting (1 token = 1 vote) + +### What browsers does the web application support? + +**Recommended browsers**: +- โ Chrome 90+ (best compatibility) +- โ Firefox 88+ +- โ Safari 14+ +- โ Edge 90+ +- โ Brave (with Web3 support) + +**Requirements**: +- JavaScript enabled +- Web3 compatibility (for wallet connection) +- Modern web standards support + +### How does authentication work in the web application? + +**Sign-In with Ethereum (SIWE)**: +- Private key **never** leaves your wallet +- Each nonce is used **once** and expires in 5 minutes +- Signature cannot be forged without private key +- Full authentication security + +**Process**: +1. Generate one-time nonce +2. Save to DB with encryption +3. Sign message with your wallet +4. Verify signature on server +5. Create session on successful verification + +### What to do if the web application is unavailable? + +**Alternative management methods**: + +1. **Via blockchain explorers**: + - Etherscan (Ethereum): https://etherscan.io + - Polygonscan (Polygon): https://polygonscan.com + - BscScan (BSC): https://bscscan.com + - Arbiscan (Arbitrum): https://arbiscan.io + +2. **Functions via Etherscan**: + - Check token balance + - Create proposals + - Vote on proposals + - Execute approved proposals + +3. **Advantages**: + - Complete independence from web application + - Impossible to forge data + - Access 24/7 from anywhere in the world + +## Usage Terms Questions + +### What license types are available? + +**Only license type - Perpetual License**: +- โณ **Validity period**: Lifetime (no time limit) +- ๐ **Updates**: FREE for all license holders +- ๐ซ **Cancellation**: License cannot be cancelled by company +- โ๏ธ **Service terms**: Same for all licenses + +**Options by number of tokens**: +- **Standard Support**: $1,000 USDT (1 token = 1 vote) +- **Priority Support**: $10,000 USDT (10 tokens = 10 votes) + +### What is included in the license? + +**All license holders receive**: +- โ All web application updates (free for 5 years for token holders) +- โ Access to documentation and knowledge base +- โ Technical support through application +- โ AI assistant 24/7 +- โ All integrations and deployment capabilities +- โ Participation in voting for new features +- โ Early access to beta features +- โ SLA 99% uptime guarantee +- โ Online training and implementation sessions + +### How does the voting system work? + +**Voting process**: +1. **Proposal creation**: Any token holder can create proposal +2. **Blockchain registration**: Voting created in smart contract +3. **Token holder voting**: Each token = 1 vote +4. **Implementation**: If 51%+ tokens vote - feature goes into development + +**Web application for voting**: https://hb3-accelerator.com/ +- Create proposals +- Vote for or against proposals +- View voting results +- Track development status + +### What usage restrictions are there? + +**โ Allowed**: +- Use for managing own business +- Deploy on own infrastructure +- Use selected type of activity (1 type per license) +- Data backup +- Local configuration modification +- Vote for new feature development +- Transfer license to heirs + +**โ Prohibited**: +- Resale or sublicensing +- Use more than one type of activity with one license +- Reverse engineering and source code modification +- Remove copyright and license notices +- Share between independent organizations +- Use for educational purposes without permission +- Deploy SaaS based on application + +### How does the 70% refund program work? + +**Refund conditions**: +You can request refund of **70% of license cost** within **5 years** from purchase, if: + +1. โ **Complaint threshold**: More than **51% negative votes** accumulated +2. ๐ **Reason**: Complaints concern **lack of update releases** +3. ๐ณ๏ธ **Voting**: Complaints were **accepted through token holder voting mechanism on blockchain** +4. โฑ๏ธ **Timeframe**: Request submitted within **5 years** from licensing + +**Refund process**: +1. Request submitted to hb3-accelerator.com with blockchain proof +2. Confirm conditions on smart contract (51%+ votes for refund) +3. Refund **70% of purchase amount** within 30 days + +### How to get technical support? + +**Unified support portal**: https://hb3-accelerator.com/ + +**Available channels**: +- ๐ Support portal (all licenses) +- ๐ฌ Chat with support team (all licenses) +- ๐ค AI assistant 24/7 (all licenses) +- ๐ Online training sessions (all licenses) +- ๐ Library of recordings (all licenses) +- ๐ง Email support (all licenses) + +**SLA (first response time)**: +- ๐ด Critical: 4 hours +- ๐ High: 8 hours +- ๐ก Medium: 24 hours +- ๐ข Low: 48 hours + +### How do application updates work? + +**Free updates for all license holders**: +- Bug fixes +- Performance improvements +- New features (approved by voting) +- Security updates + +**Frequency**: +- Security Patches: Immediately (when discovered) +- Regular Updates: Weekly (on Wednesdays) +- Major Features: Based on voting results + +**Download platform**: https://hb3-accelerator.com/ +- Download all released versions +- Detailed release notes +- Calendar of scheduled updates +- Automatic notifications about new versions + +### How does the web application security system work? + +**Multi-layer protection**: +- ๐ **TLS 1.3** for all connections +- ๐ **AES-256** for critical data in storage +- ๐ **Rate limiting** and DDoS protection +- ๐ **CSRF tokens** for all forms +- ๐ **XSS protection** (DOMPurify) +- ๐ **Helmet.js** for header protection + +**SIWE authentication**: +- Private key never leaves wallet +- Each nonce used once and expires in 5 minutes +- Signature cannot be forged without private key + +## Installation and Configuration Questions + +### What are the system requirements for installing DLE? + +**Minimum requirements**: +- **OS**: Linux, Windows, macOS +- **RAM**: 8 GB (16 GB recommended) +- **Disk**: 50 GB free space +- **Docker**: version 20.10+ +- **Docker Compose**: version 2.0+ + +**Recommended requirements**: +- **RAM**: 32 GB +- **Disk**: 100 GB SSD +- **CPU**: 8+ cores +- **Internet**: stable connection + +### How to install DLE? + +**Automatic installation (recommended)**: +```bash +curl -fsSL https://raw.githubusercontent.com/VC-HB3-Accelerator/DLE/main/setup-template.sh | bash +``` + +**Manual installation**: +1. Clone repository +2. Import Docker images +3. Create and import volumes +4. Start application + +**Application access**: +- Frontend: http://localhost:9000 (HTTP) or https://localhost:9443 (HTTPS) +- Backend API: http://localhost:9000/api + +### How to configure blockchain integration? + +**Requirements**: +- Cryptocurrency wallet (MetaMask, WalletConnect) +- RPC provider (Infura, Alchemy, or own node) +- USDT for smart contract deployment + +**Configuration process**: +1. Connect wallet +2. Configure RPC provider +3. Deploy DLE smart contract + +## Functionality Questions + +### What main features are available in DLE? + +**Blockchain features**: +- Create and manage smart contracts +- Token holder voting system +- Asset tokenization +- Multi-currency treasury +- Automatic payments + +**AI assistant**: +- Local AI without limits +- Knowledge base based on electronic tables +- Data analysis and forecasting +- Business process automation +- Omnichannel communications + +**Electronic tables**: +- Full-featured database +- Relations between tables (Relation) +- Automatic substitutions (Lookup) +- Real-time updates +- AI integration + +### How does the electronic tables system work? + +**Field types**: +- **Text** - text data +- **Number** - numeric values +- **Date** - dates and time +- **Boolean** - yes/no +- **Relation** - relations with other tables +- **Lookup** - automatic substitutions +- **File** - files and images + +**Functionality**: +- CRUD operations (create, read, update, delete) +- Filtering and sorting +- Search across all fields +- Export to various formats +- AI integration for analysis + +## Security Questions + +### How is data protected in DLE? + +**Encryption**: +- **TLS 1.3** for all connections +- **AES-256** for data in storage +- **Key management** under user control + +**Blockchain protection**: +- Tokens cannot be stolen (transfers blocked) +- All operations recorded on blockchain +- Impossible to forge history +- Independence from web application + +**Web application protection**: +- Rate limiting against DDoS +- CSRF and XSS protection +- Clean logs (sensitive data cleanup) +- Helmet.js for headers + +### What to do if hack is suspected? + +**Token protection**: +- DLE tokens blocked from transfers +- Only way to transfer - through voting +- Even if wallet hacked, tokens protected + +### How does the audit system work? + +**Blockchain transparency**: +- All actions recorded forever +- Impossible to hide or delete +- Public verification via Etherscan + +**Real-time monitoring**: +- Track all smart contract events +- Automatic alerts on suspicious activity +- Token holder notifications + +--- + +## Economics and ROI Questions + +### How much money will DLE save my business? + +**For business with $1M/year turnover**: +- **Bank fees**: savings $25,750/year (96%) +- **Corporate governance**: savings $42,000/year (78%) +- **Investment attraction**: savings $49,400 per deal (99%) +- **AI without limits**: savings $36,000/year (local vs cloud) +- **TOTAL**: $117,150/year + additional profit ~$1,000,000 + +**ROI**: 1,117% on DLE investment +**Payback**: < 1 month + +### What hidden costs does DLE have? + +**One-time costs**: +- License: $1,000-10,000 USDT +- Smart contract deployment: $100-500 (gas fees) +- Setup: $0 (self-service) + +**Monthly costs**: +- Hosting: $50-200/month +- RPC provider: $0-100/month (can be free) +- Gas fees: $10-100/month (depends on activity) + +**Comparison with traditional solutions**: +- Traditional business: $54,000+/year +- SaaS solutions: $12,000-60,000/year +- DLE: $1,200-3,000/year + +### How to calculate savings for my business? + +**Calculation formula**: +``` +Savings = (Turnover ร 0.03) + (Employees ร 2000) + (Investments ร 0.1) + +Where: +- 0.03 = 3% bank fees +- 2000 = $2,000/year per employee (management) +- 0.1 = 10% of attracted investment amount +``` + +**Example for small business** (turnover $100,000, 3 employees): +- Bank fees: $3,000 +- Management: $6,000 +- **TOTAL**: $9,000/year savings +- **ROI**: 900% on $1,000 license + +--- + +## Practical Application Questions + +### Where to start implementing DLE? + +**First month**: +1. **Week 1**: Installation and configuration +2. **Week 2**: Create knowledge base for AI +3. **Week 3**: Configure electronic tables +4. **Week 4**: Testing and team training + +**Priority tasks**: +1. Configure CRM for customers +2. Create knowledge base for support +3. Configure procurement automation +4. Connect omnichannel communications + +### How will DLE help with customers? + +**Support automation**: +- AI answers 80% of customer questions +- Works 24/7 without days off +- Analyzes customer sentiment +- Creates tickets automatically + +**Customer base management**: +- Full interaction history +- Automatic reminders +- Customer segmentation +- Need forecasting + +**Communication channels**: +- Telegram bot +- Email support +- Web chat on website + +### How will DLE help with suppliers? + +**Supplier database**: +- Catalog of all suppliers +- Price and condition comparison +- Ratings and reviews +- Cooperation history + +**AI buyer**: +- Find best offers +- Analyze contract terms +- Control delivery deadlines +- Automatic notifications + +**Savings**: +- Reduce purchase prices by 5-15% +- Accelerate supplier selection process +- Reduce risks + +### How will DLE help with finances? + +**Accounting automation**: +- Bookkeeping +- Report generation +- Expense control +- Budget planning + +**Blockchain finances**: +- Instant payments 24/7 +- Fees 50-100x lower +- No geographical restrictions +- Transparency of all operations + +**Analytics**: +- Cash flow forecasting +- Profitability analysis +- Financial risk identification +- KPI and metrics + +--- + +## Integration with Existing Systems Questions + +### How to migrate data from existing systems? + +**Step-by-step process**: +1. **Export data** from current system +2. **Clean and format** data +3. **Import to DLE** via web interface +4. **Verify correctness** of data +5. **Configure relations** between tables + +**Supported formats**: +- Excel (.xlsx, .xls) +- CSV +- JSON + +## Scaling Questions + +### How does DLE scale with business growth? + +**Horizontal scaling**: +- Add new servers +- Load distribution +- Database clustering +- CDN for static files + +**Vertical scaling**: +- Increase RAM and CPU +- SSD drives +- Query optimization +- Caching + +**Limits**: +- **Users**: up to 10,000 simultaneous +- **Data**: up to 1TB per table +- **API requests**: up to 10,000/minute +- **Files**: up to 100GB total size + +### How many users can work simultaneously? + +**Recommended limits**: +- **Small business** (up to 50 users): standard configuration +- **Medium business** (up to 500 users): increased RAM (32GB+) +- **Large business** (up to 5,000 users): cluster configuration +- **Corporations** (10,000+ users): distributed architecture + +**Performance**: +- **Interface response**: < 200ms +- **Page load**: < 2 seconds +- **API requests**: < 500ms +- **Search**: < 1 second + +### How does DLE handle large data volumes? + +**Optimizations**: +- **Indexing**: automatic indexes for search +- **Pagination**: load data in parts +- **Caching**: Redis for frequently used data +- **Compression**: data compression in database + +**Recommendations**: +- Use filters for large tables +- Configure archiving of old data +- Regularly clean unused files +- Monitor performance + +--- + +## Additional Resources + +### Documentation +- ๐ [FAQ](./FAQ.md) - this document +- ๐ง [Installation](./setup-instruction.md) - step-by-step setup +- ๐ค [AI Assistant](./ai-assistant.md) - full AI capabilities +- ๐ [Blockchain for Business](./blockchain-for-business.md) - practical cases +- ๐ [Application Description](./application-description.md) - feature overview + +### Training +- ๐ **Online sessions** (group and individual) +- ๐ณ๏ธ **Voting portal**: https://hb3-accelerator.com/ + +### Support +- ๐ฌ **Support chat**: https://hb3-accelerator.com/ +- ๐ง **Email**: info@hb3-accelerator.com +- ๐ **Website**: https://hb3-accelerator.com + +--- + +**ยฉ 2024-2025 Tarabanov Alexander Viktorovich. All rights reserved.** + +**Last update**: October 2025 + diff --git a/docs-en/README.md b/docs-en/README.md new file mode 100644 index 0000000..f631394 --- /dev/null +++ b/docs-en/README.md @@ -0,0 +1,29 @@ +# ๐ Digital Legal Entity Documentation + +**๐ Language / ะฏะทัะบ:** [๐ท๐บ ะ ัััะบะธะน](../docs/README.md) | [๐ฌ๐ง English](README.md) + +This section contains materials about the DLE product: overview, business cases, technical specifications, and implementation instructions. Use the list below to quickly find the document you need. + +## ๐ Available Documents + +| File | Brief Description | +| --- | --- | +| [application-description.md](./application-description.md) | Overview of the platform's purpose, key benefits, and economic impact. | +| [ai-assistant.md](./ai-assistant.md) | Detailed description of AI assistant capabilities and business cases. | +| [setup-ai-assistant.md](./setup-ai-assistant.md) | Step-by-step setup of a local AI assistant with vector search. | +| [setup-instruction.md](./setup-instruction.md) | Main installation and initial configuration instructions. | +| [blockchain-for-business.md](./blockchain-for-business.md) | Business justification and use cases for blockchain in DLE. | +| [blockchain-integration-technical.md](./blockchain-integration-technical.md) | Technical architecture of blockchain integration and smart contracts. | +| [security.md](./security.md) | Security model, access control, and protection mechanisms. | +| [service-terms.md](./service-terms.md) | Detailed terms for license purchase and maintenance. | +| [FAQ.md](./FAQ.md) | Answers to frequently asked questions about licensing, installation, and features. | +| [system-messages-management.md](./system-messages-management.md) | Technical specification for system message management. | +| [tables-system.md](./tables-system.md) | Description of the electronic tables system, architecture, and integrations. | + +--- + +### ๐ Related Materials + +- Legal documents and requirements are available in the [`../legal-en`](../legal-en/README.md) directory. +- Updates and additional information are published in the root [`README`](../README.md). + diff --git a/docs-en/ai-assistant.md b/docs-en/ai-assistant.md new file mode 100644 index 0000000..d1625a8 --- /dev/null +++ b/docs-en/ai-assistant.md @@ -0,0 +1,387 @@ +# DLE AI Assistant - Complete Business Capabilities + +> **Philosophy**: AI doesn't replace people, but becomes their co-pilot, freeing up 85% of time for strategy and creativity. + +## ๐ Table of Contents + +1. [Introduction](#introduction) +2. [Technology and Architecture](#technology-and-architecture) +3. [Complete AI Assistant Capabilities](#complete-ai-assistant-capabilities) +4. [Economic Impact](#economic-impact) +5. [Setup and Integration](#setup-and-integration) + +--- + +## Introduction + +### What is AI Assistant in DLE? + +**AI Assistant** is a built-in intelligent assistant that uses: +- ๐ง **Ollama** - local open-source AI models (qwen2.5:7b) +- ๐ **Vector Search** - FAISS for semantic search +- ๐ **RAG** (Retrieval-Augmented Generation) - knowledge base search +- ๐พ **Caching** - instant responses to frequent questions + +### Key Benefits + +1. **๐ 100% Local** - all data on your server +2. **๐ Complete Privacy** - nothing goes to the cloud +3. **โก Lightning-fast Responses** - caching and vector search +4. **๐ฐ Zero API Costs** - no token payments +5. **๐ Learns from Your Data** - personalized responses +6. **๐ Multilingual** - supports Russian, English, and more +7. **๐ 24/7 Availability** - works around the clock + +--- + +## Technology and Architecture + +### How It Works? + +``` +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ AI Assistant Architecture โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ + +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ 1. User asks a question โ +โ "How to return a product?" โ +โโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโ + โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ 2. Question Vectorization โ +โ Ollama mxbai-embed-large:latest โ +โ Text โ Vector [768 numbers] โ +โโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโ + โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ 3. Vector Search (FAISS) โ +โ Search for similar questions โ +โ Top-3 results by semantics โ +โโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโ + โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ 4. Contextual Search (RAG) โ +โ Extract answers from knowledge base โ +โ Filter by tags/products โ +โโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโ + โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ 5. Answer Generation (LLM) โ +โ Ollama qwen2.5:7b โ +โ Context + Question โ Answer โ +โโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโ + โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ 6. Caching โ +โ Save to cache for 1 hour โ +โ Next same question < 50ms โ +โโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโ + โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ 7. Response to User โ +โ "Product can be returned within..." โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +``` + +### Technology Stack + +| Component | Technology | Purpose | +|-----------|------------|---------| +| **LLM Model** | Ollama qwen2.5:7b | Text generation, dialogue | +| **Embedding Model** | mxbai-embed-large | Text vectorization | +| **Vector DB** | FAISS | Fast semantic search | +| **Main DB** | PostgreSQL | Knowledge base storage | +| **Cache** | Node.js Map + TTL | Accelerate repeated requests | +| **Queue** | AI Queue | Priority task processing | + +--- + +## Complete AI Assistant Capabilities + +### 1. ๐ Customer Service and Support + +**Automatic responses to common questions:** +- Instant 24/7 responses via Telegram, Email, Web chat +- Automatic problem diagnosis by order number +- Ticket creation in CRM with prioritization +- Knowledge base with vector search +- Multilingual customer support from different countries +- Real-time customer sentiment analysis +- Escalation of complex questions to live operators +- Personalized recommendations based on purchase history + +**Messenger Integration:** +- Telegram bot with AI assistant +- Email support with automatic analysis +- Web chat widget on website +- SMS notifications and alerts +- Web feedback forms + +### 2. ๐ Analytics and Business Intelligence + +**Automatic Data Analysis:** +- Big data analysis and trend identification +- Sales and demand forecasting for products/services +- Customer segmentation by behavior and preferences +- Marketing campaign effectiveness analysis +- Financial indicator anomaly detection +- Interactive dashboards with key metrics +- Competitive analysis +- Benchmarking and industry comparisons + +### 3. ๐ฐ Financial Planning and Accounting + +**Financial Process Automation:** +- Automatic accounting and report generation +- Cash flow forecasting and budget planning +- Product and service profitability analysis +- Financial risk identification and mitigation recommendations +- Automatic invoice creation and payment tracking +- Tax planning optimization +- KPI and financial indicator monitoring +- Consolidated reporting across all departments + +### 4. ๐ฏ Marketing and Sales + +**Content Marketing:** +- Content generation for social media, blogs, email campaigns +- Marketing message personalization for each customer +- A/B testing of various advertising options +- Customer acquisition channel effectiveness analysis +- Automatic email campaign creation +- SEO content and meta tag optimization +- Online reputation management + +**Sales:** +- Automatic commercial proposal creation +- Customer base analysis and opportunity identification +- Personalized product recommendations +- Automatic sales funnel tracking +- Cold call script generation + +### 5. ๐ฅ HR and Personnel Management + +**Recruitment and Personnel Management:** +- Automatic resume screening and candidate pre-selection +- Interviewing with chatbot +- Employee performance analysis +- Training and development planning +- Automatic job description creation +- Employee satisfaction analysis +- Vacation and shift planning +- Team mood monitoring + +**Employee Training:** +- Personalized training programs for employees +- Interactive course and material creation +- Adaptive learning for individual needs +- Knowledge and skill assessment +- Career development recommendations +- Knowledge base and FAQ creation + +### 6. ๐ Project and Task Management + +**Project Work Automation:** +- Automatic project planning and resource allocation +- Progress tracking and delay identification +- Workflow optimization and bottleneck elimination +- Automatic project reporting +- Risk management and reserve planning +- Distributed team coordination +- Management methodology effectiveness analysis + +### 7. ๐ Research and Development + +**Analytics and Research:** +- Market and competitive environment analysis +- New technology and trend research +- New product/service idea generation +- Patent and intellectual property analysis +- Technical documentation and specifications +- Customer feedback analysis for product improvement + +### 8. ๐ก๏ธ Security and Compliance + +**Security Monitoring:** +- IT system security monitoring +- Suspicious activity and threat detection +- Automatic security policy updates +- Regulatory compliance analysis +- Access and user rights management +- Log auditing and incident investigation + +### 9. ๐ Operational Efficiency + +**Process Optimization:** +- Supply chain and logistics optimization +- Production planning and inventory management +- Routine process automation +- Product and service quality analysis +- Asset management and maintenance +- Energy and resource consumption optimization + +### 10. ๐ Training and Development + +**Corporate Training:** +- Personalized training programs for employees +- Interactive course and material creation +- Adaptive learning for individual needs +- Knowledge and skill assessment +- Career development recommendations +- Knowledge base and FAQ creation + +### 11. ๐ International Activities + +**Global Capabilities:** +- Automatic document and communication translation +- Target market cultural analysis +- Content adaptation for local requirements +- International legislation change monitoring +- Currency risk management +- Coordination with foreign partners + +### 12. ๐ฎ Strategic Planning + +**Long-term Planning:** +- Macroeconomic trend analysis and business impact +- Scenario planning for various situations +- Merger and acquisition opportunity analysis +- Investment project evaluation +- New market entry planning +- Long-term development strategy development + +### 13. ๐ฑ Mobile and Digital Solutions + +**Digital Transformation:** +- Mobile app development with AI features +- Chatbot creation for various platforms +- Voice assistants for business processes +- IoT device integration +- Social media automation +- Virtual assistant creation + +### 14. ๐ญ Industry Solutions + +**Specialized Solutions:** +- **Healthcare**: diagnosis, treatment planning, patient management +- **Finance**: credit scoring, risk management, trading algorithms +- **Retail**: personalization, inventory management, pricing +- **Manufacturing**: quality control, predictive maintenance, optimization +- **Real Estate**: valuation, market analysis, property management +- **Education**: adaptive learning, knowledge assessment, planning + +### 15. ๐ Integration and Automation + +**System Integration:** +- API integrations with external systems +- Workflow automation (RPA) +- Data synchronization between various platforms +- Unified ecosystem creation for all business processes +- Data and system migration +- Integrated solution performance monitoring + +--- + +## Economic Impact + +### Comparison with Cloud Solutions + +| Characteristic | DLE AI (Local) | ChatGPT API | Claude API | +|----------------|----------------|-------------|------------| +| **Cost** | $0 | ~$0.02/request | ~$0.03/request | +| **Privacy** | โ 100% | โ Data in OpenAI | โ Data in Anthropic | +| **Speed (cache)** | 50ms | 500-2000ms | 500-2000ms | +| **Offline Work** | โ Yes | โ No | โ No | +| **Business Customization** | โ Full | โ ๏ธ Limited | โ ๏ธ Limited | +| **API Limits** | โ None | โ Yes | โ Yes | + +### Savings with Cloud API Usage + +**At 10,000 requests/month:** +- ChatGPT API: $200/month = **$2,400/year** +- Claude API: $300/month = **$3,600/year** +- DLE AI: **$0/year** โ + +**At 50,000 requests/month:** +- ChatGPT API: $1,000/month = **$12,000/year** +- Claude API: $1,500/month = **$18,000/year** +- DLE AI: **$0/year** โ + +**At 100,000 requests/month:** +- ChatGPT API: $2,000/month = **$24,000/year** +- Claude API: $3,000/month = **$36,000/year** +- DLE AI: **$0/year** โ + +### Total Savings Across All Areas + +| Area | Annual Savings | ROI | +|------|----------------|-----| +| **Customer Service** | $57,600 | 5,760% | +| **Supplier Work + AI Purchaser** | $64,800 | 6,480% | +| **Partner Work** | $43,200 | 4,320% | +| **Employee Training** | $30,000 | 3,000% | +| **Personnel Management** | $57,600 | 5,760% | +| **Reporting and Analysis** | $144,000 | 14,400% | +| **Content Marketing** | $86,400 | 8,640% | +| **API Token Savings** | $24,000-36,000 | 2,400-3,600% | +| **TOTAL:** | **$507,600-519,600** | **50,760-51,960%** | + +**DLE Implementation Cost**: $1,000 (one-time, Standard Support) +**ROI**: 50,760-51,960% or **507-519x return on investment** + +### Additional Benefits + +**Immeasurable Advantages:** +- ๐ Improved work quality +- ๐ Customer satisfaction +19% +- ๐ฅ Employee retention +15% +- ๐ Decision speed +300% +- ๐ก More time for strategy +- ๐ฏ Less routine, more creativity + +--- + +## Setup and Integration + +**What You Need to Launch:** +- โ Install DLE (see [Installation Instructions](./setup-instruction.md)) +- โ Run Ollama and install models +- โ Create knowledge base (FAQ, suppliers, HR) +- โ Configure AI assistant for your business +- โ Integrate with Telegram/Email (optional) + +**Setup Time:** +- ๐ **Quick Start**: 20-30 minutes (basic FAQ) +- โ๏ธ **Full Setup**: 1-2 hours (all capabilities) + +**Result:** +- ๐ค Working AI assistant 24/7 +- ๐ Knowledge base for customer responses +- ๐ Vector search on your data +- ๐ฐ Savings up to $519,600/year + +### Next Steps + +1. ๐ [Install DLE](./setup-instruction.md) +2. ๐ค [Configure AI Assistant](./setup-ai-assistant.md) +3. ๐ Upload knowledge base +4. ๐ Start saving time and money! + +--- + +## Support + +**Need Help with AI Setup?** + +๐ง **Email**: info@hb3-accelerator.com +๐ฌ **Chat**: https://hb3-accelerator.com +๐ **Documentation**: [FAQ](./FAQ.md) +๐ **Training**: Online sessions for token holders + +--- + +**ยฉ 2024-2025 Tarabanov Alexander Viktorovich. All rights reserved.** + +**Last Updated**: October 2025 + diff --git a/docs-en/application-description.md b/docs-en/application-description.md new file mode 100644 index 0000000..dbe52b5 --- /dev/null +++ b/docs-en/application-description.md @@ -0,0 +1,333 @@ +# Digital Legal Entity (DLE) - Web Application for Business Management + +> **Full Control. Zero Subscription Fee. AI Saves $507,600-519,600/year.** + +--- + +## ๐ Table of Contents + +1. [Who This Application Is For](#who-this-application-is-for) +2. [Key Benefits](#key-benefits) +3. [Main Features](#main-features) +4. [Economic Impact](#economic-impact) +5. [Technical Details](#technical-details) +6. [Purchase Terms](#purchase-terms) +7. [Additional Documentation](#additional-documentation) + +--- + +## ๐ฏ Who This Application Is For + +DLE is created for **all types of organizations** that need transparent collective management: + +- **Commercial organizations** (LLC, JSC, sole proprietors, holdings) +- **Non-profit organizations** (NPOs, foundations, associations) +- **Government structures** (municipalities, agencies) +- **Investment funds** and **venture companies** +- **Startups** and **small businesses** +- **Cooperatives** and **associations** + +--- + +## ๐ Key Benefits + +### Why DLE, Not SaaS? + +| Parameter | DLE | Regular SaaS | +|----------|-----|--------------| +| **๐ฐ Cost** | $1,000 one-time | $200-500/month | +| **๐ Data Ownership** | 100% yours | With provider | +| **๐ง Customization** | Full | Limited | +| **๐ Legal Compliance** | For your region | Depends on provider | +| **๐ก๏ธ Regulatory Compliance** | GDPR, CCPA, 152-FZ | Limited | +| **๐ค AI Without Limits** | Free | $200+/month | +| **๐ Blockchain** | Built-in | None or extra fee | +| **โก Updates** | Free 5 years (for token holders) | Depends on plan | + +### ๐ What You Get + +โ **Perpetual License** - pay once, use forever +โ **Free Updates** - all improvements without extra payment +โ **Full Source Code** - complete transparency +โ **AI on Your Server** - 100% confidentiality +โ **Blockchain Protection** - assets cannot be stolen +โ **Asset Tokenization** - 99% savings on transactions +โ **Voting Rights** - influence on product development +โ **Ready Regulatory Package** - privacy policy, personal data consent, user agreement, cookie policy +โ **70% Refund Guarantee** - within 5 years if no updates + +--- + +## ๐ Main Features + +### 1. CRM and Contact Management + +**Full Customer Management System**: +- Centralized contact database with interaction history +- Grouping by tags and categories +- Task and reminder system +- Import from CSV, Excel, external CRMs +- Export in various formats +- Document and template builder + +### 2. AI Assistant with Vector Search + +**Local AI on Your Server**: +- Ollama + Vector Search (RAG) +- qwen2.5:7b model (or any other) +- 100% confidentiality (data doesn't leave) +- Zero API token costs + +**Key Capabilities**: +- **๐ Customer Service** - 24/7 responses, customer sentiment analysis +- **๐ Analytics and Business Intelligence** - data analysis, sales forecasting +- **๐ฐ Financial Planning** - automated accounting, profitability analysis +- **๐ฏ Marketing and Sales** - content generation, message personalization +- **๐ฅ HR and Personnel Management** - resume screening, training planning +- **๐ Project Management** - automatic planning, progress tracking +- **๐ Research and Development** - market analysis, idea generation +- **๐ก๏ธ Security and Compliance** - security monitoring, compliance analysis +- **๐ Operational Efficiency** - process optimization, automation +- **๐ Training and Development** - personalized training programs +- **๐ International Activity** - automatic translation, content adaptation +- **๐ฎ Strategic Planning** - trend analysis, scenario planning +- **๐ฑ Mobile Solutions** - app development, chatbot creation +- **๐ญ Industry Solutions** - specialized solutions for different industries +- **๐ Integration and Automation** - API integrations, process automation + +**Economic Impact**: $507,600-519,600/year with ROI 50,760-51,960% + +> ๐ก **Detailed Information**: See [AI Assistant - Full Description](./ai-assistant.md) - detailed description of all capabilities, use cases, architecture, and savings calculations. + +### 3. Omnichannel Communications + +**Unified Interface for All Channels**: +- ๐ฌ Telegram bot, ๐ง Email, ๐ Web chat, ๐ฑ SMS, ๐ Web forms +- One context for customer across all channels +- AI auto-responses trained on your data +- Analytics by channel and response time + +### 4. Blockchain Management and Tokenization + +**Smart Contracts for Business**: +- Tokenization of any assets (real estate, IP, shares) +- Management through token holder voting +- Multi-chain support (7+ networks: Ethereum, Polygon, BSC, Arbitrum, Optimism, Avalanche, Base) +- Transparency of all operations on blockchain + +> ๐ก **Detailed Information**: See [Blockchain for Business](./blockchain-for-business.md) - practical use cases and [Blockchain Technical Documentation](./blockchain-integration-technical.md) - for developers. + +### 5. Groups and Team Spaces + +- Customizable spaces for projects +- Detailed permission system (20+ types) +- Roles: Editor, ReadOnly, User +- Integration with CRM and communications + +### 6. Internal Tools + +- Electronic tables (Excel-like) +- Analytics and reporting system +- Metrics monitoring +- WebSSH for server management + +### 7. Security and Protection + +**Multi-Level DLE Protection**: +- **Network Security** - TLS 1.3, HTTPS, DDoS protection +- **Authentication** - SIWE (wallet login), sessions in DB +- **Authorization** - detailed permissions (20+ types), token gating +- **Data Protection** - AES-256 encryption, SQL injection protection +- **Blockchain Protection** - tokens cannot be stolen without voting +- **Monitoring** - logging, alerts, audit trail + +**Regulatory Compliance**: +- **GDPR** - compliance with European personal data protection requirements +- **CCPA** - compliance with California requirements +- **Russian Legislation** - compliance with 152-FZ "On Personal Data" +- **Local Storage** - all data remains on your server +- **Transparency** - full control over personal data processing + +> ๐ก **Detailed Information**: See [DLE Security](./security.md) - detailed description of all protection levels, attack scenarios, security recommendations, and regulatory compliance. + +## ๐ฐ Economic Impact + +### Comparison with SaaS Over 5 Years + +**Typical SaaS Stack**: +``` +CRM (HubSpot): $200/mo ร 60 mo = $12,000 +Chatbot (Intercom): $150/mo ร 60 mo = $9,000 +Email (SendGrid): $100/mo ร 60 mo = $6,000 +AI (ChatGPT API): $200/mo ร 60 mo = $12,000 + โโโโโโโโโโโโโโโโโโโโโโโโโโโโโ + TOTAL: $39,000 +``` + +**DLE**: +``` +License (one-time): $1,000 +Updates (5 years): $0 +AI without limits: $0 + โโโโโโโโโโโโโโโโโโโโโโโโโโโโโ + TOTAL: $1,000 + +SAVINGS: $38,000 +``` + +### ROI from AI Assistant + +**Comparison with Cloud Solutions**: + +| Characteristic | DLE AI (Local) | ChatGPT API | Claude API | +|----------------|-------------------|-------------|------------| +| **Cost** | $0 | ~$0.02/request | ~$0.03/request | +| **Confidentiality** | โ 100% | โ Data in OpenAI | โ Data in Anthropic | +| **Speed (cache)** | 50ms | 500-2000ms | 500-2000ms | +| **Offline Work** | โ Yes | โ No | โ No | +| **Business Customization** | โ Full | โ ๏ธ Limited | โ ๏ธ Limited | +| **API Limits** | โ None | โ Yes | โ Yes | + +**Total Savings Across All Areas**: +- Customer Service: $57,600 +- Supplier Relations + AI Purchaser: $64,800 +- Partner Relations: $43,200 +- Staff Training: $30,000 +- Personnel Management: $57,600 +- Reporting and Analysis: $144,000 +- Content Marketing: $86,400 +- API Token Savings: $24,000-36,000 +- **TOTAL**: $507,600-519,600/year + +**Investment**: $1,000 +**ROI**: 50,760-51,960% or 507-519x return โ + +### Savings on Asset Tokenization + +**Traditional Real Estate Transaction ($1M)**: +- Realtor Commission: 3-5% = $30,000-50,000 +- Legal Services: $5,000-10,000 +- Title Registration: $2,000-5,000 +- Time: 2-6 months +- **Total**: $37,000-65,000 + +**Tokenized Transaction via DLE**: +- Gas Fees: $50-200 +- Smart Contract (one-time): $500 +- Time: 5-10 minutes +- **Total**: $550-700 + +**Savings**: 99% costs and 99% time โ + +--- + +## ๐ง Technical Details + +### Architecture + +**Modern Technology Stack**: +- **Frontend**: Vue.js 3 + Vite + Element Plus +- **Backend**: Node.js + Express +- **Database**: PostgreSQL + pgvector +- **AI**: Ollama (qwen2.5:7b) + FAISS Vector Search +- **Blockchain**: Ethers.js v6 + Hardhat +- **Containerization**: Docker Compose + +### Design Principles + +โ **Microservices Architecture** - easy to scale +โ **Full Control** - you own the application and data +โ **Modularity** - add new features through modules +โ **Security** - multi-level protection (TLS, AES-256, CSRF) +โ **API-first** - REST + WebSocket for integrations + +### Deployment + +**Flexible Installation Options**: +- **On Your Server** - full control +- **In Cloud** - AWS, Google Cloud, Azure +- **On Local Infrastructure** - regulatory compliance +- **Docker Compose** - deployment with one command + +**Minimum Requirements**: +- **CPU**: 4 cores +- **RAM**: 12 GB (4 GB application + 6 GB AI + 2 GB Vector Search) +- **Storage**: 100 GB SSD +- **OS**: Ubuntu 20.04+, Debian 11+, CentOS 8+, any Linux with Docker + +> ๐ก **Detailed Information**: See [Installation Instructions](./setup-instruction.md) - step-by-step setup and [AI Assistant Setup](./setup-ai-assistant.md) - specialized installation. + +--- + +## ๐ณ Purchase Terms + +> ๐ก **Detailed Information**: See [Service Terms](./service-terms.md) - detailed description of licensing model, pricing, guarantees, and purchase process. + +### Quick Overview + +**Perpetual License**: +- ๐ฐ **Pay Once** - use forever +- ๐ **Full Source Code** with documentation +- ๐ **Free Updates** 5 years for license token holders (see [legal-en/service-terms.md](../legal-en/service-terms.md)) +- ๐ณ๏ธ **Voting Rights** for product development + +**Pricing**: +| Package | Price | Votes | Support | +|-------|------|--------|-----------| +| **Standard Support** | $1,000 USDT | 1 vote | 24/7 chat | +| **Priority Support** | $10,000 USDT | 10 votes | 24/7 chat | + +**What's Included**: +โ Perpetual license for use +โ Source code with full documentation +โ Free updates 5 years for token holders +โ Technical support +โ Governance tokens on blockchain +โ Ready regulatory package +โ 70% refund guarantee within 5 years + +**How to Purchase**: +1. Contact us: info@hb3-accelerator.com +2. Receive payment details (USDT) +3. Pay for license +4. Receive code access and DLE tokens + +--- + +## ๐ Additional Documentation + +### ๐ฏ Quick Start +- ๐ **[FAQ](./FAQ.md)** - answers to 50+ questions (11 sections) +- ๐ง **[Installation](./setup-instruction.md)** - step-by-step setup in 15 minutes +- ๐ค **[AI Setup](./setup-ai-assistant.md)** - launch AI assistant + +### ๐ผ Business and Economics +- ๐ฐ **[Blockchain for Business](./blockchain-for-business.md)** - asset tokenization, 99% savings on transactions +- ๐ค **[AI Assistant](./ai-assistant.md)** - $507,600-519,600/year savings, "AI+Human" philosophy +- ๐ **[Tables System](./tables-system.md)** - data and document management + +### ๐ง Technical Documentation +- ๐ **[Blockchain Integration](./blockchain-integration-technical.md)** - smart contracts, API, code examples +- ๐ก๏ธ **[Security](./security.md)** - multi-level protection, GDPR/CCPA/152-FZ compliance +- โ๏ธ **[Service Terms](./service-terms.md)** - licensing, support, guarantees + +### ๐ General Information +- ๐ **[Main README](../README.md)** - complete list of all documents +- โ๏ธ **[Legal Documentation](../legal-en/README.md)** - legal information + +### ๐ Support and Contacts + +**Main Contacts**: +- ๐ง **Email**: info@hb3-accelerator.com +- ๐ **Website**: https://hb3-accelerator.com +- ๐ฌ **Support Chat**: https://hb3-accelerator.com/ +- ๐ **GitHub**: https://github.com/VC-HB3-Accelerator +--- + +**ยฉ 2024-2025 Tarabanov Alexander Viktorovich. All rights reserved.** + +**Digital Legal Entity (DLE)** - revolution in business management through blockchain and AI. + +**Document Version**: 2.0.0 +**Last Update**: October 2025 + diff --git a/docs-en/blockchain-for-business.md b/docs-en/blockchain-for-business.md new file mode 100644 index 0000000..0aad8e9 --- /dev/null +++ b/docs-en/blockchain-for-business.md @@ -0,0 +1,1288 @@ +# Blockchain Integration for Business: Solving Real Problems + +## ๐ Table of Contents + +1. [Introduction: Why Blockchain for Business?](#introduction-why-blockchain-for-business) +2. [Smart Contract as Universal Identifier](#smart-contract-as-universal-identifier) +3. [Asset Tokenization](#asset-tokenization) +4. [Solving Management Problems](#solving-management-problems) +5. [Financial Operations Without Banks](#financial-operations-without-banks) +6. [Transparency and Trust](#transparency-and-trust) +7. [Automation and Cost Reduction](#automation-and-cost-reduction) +8. [Practical Cases](#practical-cases) +9. [Economic Impact](#economic-impact) + +--- + +## Introduction: Why Blockchain for Business? + +### Traditional Business Problems + +Modern business faces many problems: + +| Problem | Consequences | Costs | +|---------|-------------|-------| +| ๐ฆ **Multiple Bank Accounts** | Accounting complexity, fees | 2-5% of turnover | +| ๐ **Bureaucracy** | Slow decisions, paperwork | 20-30% of time | +| ๐ค **Non-transparent Management** | Shareholder conflicts, corruption | Up to 40% of value | +| ๐ฐ **Illiquid Assets** | Cannot quickly sell/divide | Lost opportunities | +| ๐ **Geographic Restrictions** | Difficulties with international partners | Missed profit | +| โฐ **Slow Transactions** | 3-7 days for bank transfers | Capital freeze | + +### Solution: Digital Legal Entity on Blockchain + +DLE transforms your company into a **digital organization** with blockchain identity, where: +- โ One smart contract address = all company identification +- โ Any assets tokenized and easily manageable +- โ Transparent management through voting +- โ Instant financial operations without intermediaries +- โ Global availability 24/7 + +--- + +## Smart Contract as Universal Identifier + +### Concept: One Address for Everything + +In traditional business, a company has many identifiers: +``` +Traditional Company: +โโโ Tax ID/Registration Number +โโโ Bank Account #1 (RUB) +โโโ Bank Account #2 (USD) +โโโ Bank Account #3 (EUR) +โโโ Email: info@company.com +โโโ Phone: +7-xxx-xxx-xx-xx +โโโ Legal Address +โโโ Contract Details +โโโ Multiple Accounting Systems +``` + +**With DLE on Blockchain:** +``` +Digital Legal Entity: +โโโ 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C + โ + This ONE smart contract address replaces EVERYTHING: + โ Tax Identifier + โ Bank Account (multi-currency) + โ Email/Phone (receiving payments and messages) + โ Legal Identity + โ Communication Address + โ Asset Accounting System +``` + +### How It Works in Reality? + +#### 1. Tax Identifier + +**Traditionally:** +- Tax ID (Russia): 10 digits +- EIN (USA): 9 digits +- VAT ID (EU): 8-12 characters +- Different in each jurisdiction + +**With DLE:** +- Contract address: `0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C` +- **Same** in all countries and blockchains +- Link to traditional numbers stored in smart contract: + ```solidity + struct DLEInfo { + uint256 jurisdiction; // 643 = Russia, 840 = USA + string[] okvedCodes; // OKVED codes (activity types) + uint256 kpp; // KPP for Russia + string location; // Location + } + ``` + +**Advantages:** +- โ No need to register in each country +- โ Instant verification via blockchain +- โ Cannot forge or steal identifier + +#### 2. Bank Account (Multi-currency) + +**Traditionally:** +- Separate account for each currency +- Opening fees: $50-500 +- Monthly maintenance: $10-100 +- Conversion: 1-5% fees +- Transfers: 3-7 days + $25-50 + +**With DLE:** +- Contract address accepts any tokens: + - USDT, USDC (stablecoins = dollars) + - Native coins (ETH, MATIC, BNB) + - Any ERC20 tokens + - Tokenized assets + +**Transaction Example:** +``` +Client sends payment โ 0x742d35... + โ + Received in 30 seconds + Fee: $0.10-5 + Visible to all participants +``` + +**Advantages:** +- โ One address for all currencies +- โ Fees 50-100x lower +- โ Instant transactions +- โ Works 24/7, including weekends +- โ No blocks and freezes + +#### 3. Email and Phone for Company + +**Traditionally:** +- Email: info@company.com (can be hacked, lose domain) +- Phone: +7-xxx-xxx (can intercept SIM) +- Different channels for different purposes + +**With DLE:** +- **Contract address** = communication address +- Cryptographic signatures (cannot forge) +- Built-in omnichannel system: + ``` + 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C + โ + โโโโโโโโโโโโโดโโโโโโโโโโโโฌโโโโโโโโโโโโฌโโโโโโโโโโโ + โ Blockchain Messages โ Telegram โ Email โ Web + โ (cryptographically โ (bot) โ (SMTP) โ (form) + โ signed) โ โ โ + โโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโดโโโโโโโโโโโ + ``` + +**Advantages:** +- โ Cannot hack (private key = access) +- โ Complete communication history on blockchain +- โ Automatic sender verification +- โ All channels integrated in one place + +--- + +## Asset Tokenization + +### What is Tokenization? + +**Tokenization** - converting any asset into a digital token on blockchain that can: +- ๐ Quickly buy/sell +- ๐ Divide into shares (fractional ownership) +- ๐ฑ Exchange for other assets +- ๐ Track value in real-time +- ๐ Transfer worldwide instantly + +### Asset Types for Tokenization + +#### 1. ๐ข Real Estate + +**Traditional Problem:** +- Illiquidity (sale 3-12 months) +- High fees (3-6% of value) +- Cannot divide (cannot sell 10% of apartment) +- Bureaucracy (dozens of documents, notaries) + +**Solution Through Tokenization:** +``` +Office Building = 10,000,000 DLE Tokens +โโโ 1 token = 0.00001% of building +โโโ Token Price: $100 +โโโ Minimum Purchase: 1 token ($100) +โโโ Sale: 30 seconds on blockchain +``` + +**Advantages:** +- โ Anyone can buy share from $100 +- โ Sale in 30 seconds instead of 6 months +- โ Fee 0.1% instead of 5% +- โ Automatic rental payment distribution +- โ Transparent ownership history + +**Example:** +``` +You own office for 10 million rubles +โ Tokenization +Issue 100,000 tokens at 100 rubles +โ Sell 30% (30,000 tokens) +Received 3 million rubles in 1 day +โ Rent 500,000 rubles/month +Automatically distributed: +โโโ 70% (350,000 rubles) โ you +โโโ 30% (150,000 rubles) โ new token holders +``` + +#### 2. ๐ Stocks and Business Shares + +**Traditional Problem:** +- IPO costs millions and takes years +- LLC shares don't sell (need notary, tax office) +- Shareholder accounting - expensive and complex +- Dividends paid manually + +**Solution Through DLE:** +``` +Your Company = DLE Tokens +โโโ 1,000,000 tokens = 100% of company +โโโ You: 700,000 tokens (70%) +โโโ Partner: 200,000 tokens (20%) +โโโ Investors: 100,000 tokens (10%) +``` + +**Advantages:** +- โ "IPO" in 1 day instead of 2 years +- โ Cost: $100-1000 instead of $500,000+ +- โ Automatic dividend payments +- โ Instant share sale +- โ Transparent owner accounting + +**Case:** +``` +Startup seeking investment: + +Traditionally: +โโโ Investor search: 6-12 months +โโโ Lawyers and documents: $10,000-50,000 +โโโ Change registration: 1-2 months +โโโ TOTAL: $50,000 + year of time + +With DLE: +โโโ Issue tokens: 1 day +โโโ Sell on DEX: immediately +โโโ Cost: $100 (gas fees) +โโโ TOTAL: $100 + 1 day +``` + +#### 3. ๐จ Intellectual Property + +**What Can Be Tokenized:** +- Patents +- Copyrights (music, books, video) +- Trademarks +- Franchises +- Software Licenses + +**Example: Music Album Tokenization** +``` +Artist Album = 1,000,000 tokens +โโโ Artist keeps: 500,000 (50%) +โโโ Sells to fans: 500,000 tokens at $1 +โโโ Streaming revenue automatically divided: + โโโ 50% โ artist + โโโ 50% โ token holders +``` + +**Advantages:** +- โ Fans invest in favorite artist +- โ Automatic royalties +- โ Revenue transparency +- โ Secondary market (tokens can be resold) + +#### 4. ๐ฆ Goods and Inventory + +**Problem:** Warehouse goods are "dead" capital + +**Solution:** +``` +100 tons of wheat = 100,000 tokens +โโโ 1 token = 1 kg of wheat +โโโ Token Price: current exchange + 5% +โโโ Can sell/buy at any time +``` + +**Advantages:** +- โ Warehouse inventory liquidity +- โ Risk hedging (sell part in advance) +- โ Financing attraction for goods +- โ Transparent supply chain + +#### 5. ๐ Precious Items and Art + +**Case: Diamond Tokenization** +``` +5 Carat Diamond = 5,000 tokens +โโโ 1 token = 0.001 carat +โโโ Price: $100,000 / 5,000 = $20 per token +โโโ Physical diamond in vault (certified) +โโโ Token holders = co-owners of diamond +``` + +**Advantages:** +- โ Investment access from $20 +- โ Liquidity (sale in minutes) +- โ Diversification (buy shares in different stones) +- โ Transparent storage and insurance + +### How Tokenization Works in DLE? + +#### Treasury Model + +``` +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ DLE Smart Contract โ +โ Address: 0x742d35... โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ ASSETS (Treasury): โ +โ โโโ 10 BTC โ +โ โโโ 100,000 USDT โ +โ โโโ Tokenized Real Estate: 3 properties โ +โ โโโ Company Stocks: 10 issuers โ +โ โโโ Intellectual Property: 5 patents โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ MANAGEMENT: โ +โ โโโ Token holders vote for distribution โ +โ โโโ 51%+ = decision approved โ +โ โโโ Automatic execution by smart contract โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +``` + +**Process:** +1. **Company buys asset** (real estate, equipment, etc.) +2. **Asset placed in Treasury Module** of smart contract +3. **Token holders own shares** according to token amount +4. **Asset income** automatically distributed proportionally + +--- + +## Solving Management Problems + +### Traditional Corporate Governance Problems + +#### 1. Decision Opacity + +**Problem in Classic Companies:** +``` +Board of Directors: +โโโ Closed meetings +โโโ No decision records (or lost) +โโโ Cannot verify who voted how +โโโ Conflicts of interest hidden +โโโ Shareholders don't know what's happening +``` + +**Solution in DLE:** +``` +Each Proposal: +โโโ ID: #42 +โโโ Description: "Buy new office for 5 million" +โโโ Initiator: 0xABC...123 +โโโ Votes "For": 5,234,567 tokens (62%) +โโโ Votes "Against": 3,123,456 tokens (38%) +โโโ Who voted how: publicly on blockchain +โโโ Voting Date: 2025-10-25 +โโโ Result: Approved โ +``` + +**Advantages:** +- โ **Complete Transparency** - every shareholder sees everything +- โ **Immutable History** - cannot forge results +- โ **Automatic Counting** - no manipulation +- โ **Provability** - anyone can verify on blockchain + +#### 2. Slow Decision Making + +**Traditional Scheme:** +``` +Change Proposal โ + Document Preparation (2 weeks) โ + Lawyer Approval (1 week) โ + Shareholder Meeting (1 month) โ + Voting (1 day) โ + Protocol Preparation (1 week) โ + Registration (2 weeks) โ + TOTAL: 3 months +``` + +**With DLE on Blockchain:** +``` +Change Proposal โ + Create Proposal (5 minutes) โ + Voting (1-7 days) โ + Automatic Execution (30 seconds) โ + TOTAL: 1-7 days +``` + +**Savings:** 90-95% of time! + +#### 3. High Management Costs + +**Traditional Corporate Governance Expenses:** +``` +Annual LLC/Corp Management Expenses: +โโโ Accountant: $12,000-36,000/year +โโโ Lawyer: $10,000-50,000/year +โโโ Notary (transactions): $500-5,000/year +โโโ Shareholder Registry: $2,000-10,000/year +โโโ Audit: $5,000-50,000/year +โโโ Shareholder Meetings (organization): $2,000-10,000/year +โโโ TOTAL: $31,500-161,000/year +``` + +**With DLE:** +``` +Annual Expenses: +โโโ Gas fees for transactions: $100-1,000/year +โโโ RPC providers: $0-500/year (can be free) +โโโ Application hosting: $100-500/year +โโโ TOTAL: $200-2,000/year +``` + +**Savings:** 90-99% of expenses! + +#### 4. Corruption and Conflicts of Interest + +**Traditional Problem:** +- Director buys services from own company at inflated price +- Cannot track +- Hard to prove +- Long court proceedings + +**DLE Solution:** +``` +Proposal: "Buy equipment from Company X for $100,000" +โ +All token holders see: +โโโ Who initiated: 0xABC...123 (Ivan Ivanov) +โโโ Company X Owner: 0xABC...123 (SAME PERSON!) +โโโ Conflict of Interest: DETECTED โ ๏ธ +โโโ Token holders vote "Against" +``` + +**Advantages:** +- โ Automatic conflict detection +- โ Ownership transparency +- โ Cannot hide connections +- โ Collective decision making + +### Hierarchical Management (DLE Owns Other DLEs) + +**Concept:** One company owns shares of other companies + +``` +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ Holding DLE-A (Parent Company) โ +โ 1,000,000 tokens โ +โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโ + โ Owns tokens: + โโโโโโโโโผโโโโโโโโฌโโโโโโโโโโโโโโ + โ โ โ โ + โโโโโโโโโ โโโโโโโโโ โโโโโโโโโ โโโโโโโโโ + โDLE-B โ โDLE-C โ โDLE-D โ โDLE-E โ + โ70% โ โ51% โ โ100% โ โ25% โ + โRetail โ โManuf. โ โIT โ โStart. โ + โโโโโโโโโ โโโโโโโโโ โโโโโโโโโ โโโโโโโโโ +``` + +**Capabilities:** +1. **DLE-A votes in subsidiaries** automatically +2. **Consolidated management** of entire holding +3. **Transparent ownership structure** (visible to all) +4. **Automatic dividends** bottom-up + +**Example:** +``` +DLE-D earned 100,000 USDT profit +โ +Voting in DLE-D: "Pay dividends" +โ +100% tokens with DLE-A โ 100,000 USDT goes to DLE-A +โ +Automatically distributed among DLE-A shareholders +``` + +--- + +## Financial Operations Without Banks + +### Banking System Problems for Business + +| Problem | Consequences | Your Losses | +|---------|-------------|-------------| +| ๐ฆ **High Fees** | 2-5% per transaction | $20,000 on $1M turnover | +| โฐ **Slow Transfers** | 3-7 days | Capital freeze | +| ๐ **SWIFT Fees** | $25-50 per transfer | $300-600/month | +| ๐ฑ **Currency Conversion** | 3-7% spread | $30,000-70,000/year | +| ๐ซ **Account Blocks** | Business stops | Millions in losses | +| ๐ **Compliance** | Document requests | Employee time | +| ๐ **Country Restrictions** | No access to markets | Missed profit | + +### Solution: Cryptocurrency Operations Through DLE + +#### 1. Instant Payments 24/7 + +**Comparison:** +``` +Bank Transfer (International): +โโโ Time: 3-7 business days +โโโ Fee: $25-50 + 2-5% conversion +โโโ Works: Mon-Fri, 9:00-18:00 +โโโ Can be blocked + +Crypto Transfer (via DLE): +โโโ Time: 30 seconds - 5 minutes +โโโ Fee: $0.10-5 +โโโ Works: 24/7/365 +โโโ Cannot be blocked +``` + +**Real Case:** +``` +You sell goods to China for $100,000 + +Traditionally: +โโโ SWIFT transfer: 5 days +โโโ Bank fee: $50 +โโโ USDโCNY Conversion: 3% = $3,000 +โโโ Chinese bank fee: $30 +โโโ TOTAL: $3,080 fees + 5 days waiting + +With DLE (USDT): +โโโ Blockchain transfer: 30 seconds +โโโ Gas fee: $2 +โโโ Conversion: 0% (USDT = USD) +โโโ TOTAL: $2 fee + 30 seconds +``` + +**Savings:** $3,078 (99.9%) per transaction! + +#### 2. Multi-currency Treasury + +**One DLE address stores all currencies:** +``` +Treasury DLE: 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C +โโโ Stablecoins (= fiat currencies): +โ โโโ USDT: 500,000 (= $500,000) +โ โโโ USDC: 300,000 (= $300,000) +โ โโโ EURC: 200,000 (= โฌ200,000) +โ โโโ XSGD: 100,000 (= S$100,000) +โโโ Cryptocurrencies: +โ โโโ ETH: 100 ($200,000) +โ โโโ BTC: 5 ($250,000) +โ โโโ MATIC: 1,000,000 ($800,000) +โโโ Tokenized Assets: + โโโ Real Estate: $5,000,000 + โโโ Company Stocks: $2,000,000 +``` + +**Advantages:** +- โ No separate accounts +- โ Instant conversion (via DEX) +- โ Transparent balance for all shareholders +- โ Automatic accounting + +#### 3. Automatic Salary and Dividend Payments + +**Traditional Dividend Payment Scheme:** +``` +1. Shareholder Meeting: dividend decision +2. Accountant calculates amounts for each +3. Payment order preparation +4. Send to bank +5. Bank processes: 3-7 days +6. Taxes withheld +7. Payment to shareholders + +TOTAL: 2-4 weeks + errors + fees +``` + +**With DLE:** +```javascript +// One transaction to pay dividends to ALL shareholders +function distributeDividends(uint256 amount) { + // Smart contract automatically: + // 1. Takes USDT from treasury + // 2. Calculates each token holder's share + // 3. Sends proportionally to tokens + // 4. All in 30 seconds! +} +``` + +**Example:** +``` +Company Profit: 1,000,000 USDT +Token Holders: +โโโ Alice: 600,000 tokens (60%) โ 600,000 USDT +โโโ Bob: 300,000 tokens (30%) โ 300,000 USDT +โโโ Carol: 100,000 tokens (10%) โ 100,000 USDT + +One transaction โ Everyone received in 30 seconds +Fee: $5 instead of $50-500 +``` + +#### 4. Global Payments Without Restrictions + +**Traditional Payment Problems:** +- ๐ซ Sanctions (cannot send money to some countries) +- ๐ Compliance (need documents for each transfer) +- ๐ธ Limits (amount restrictions) +- โฐ Delays (banks check each transaction) + +**With Cryptocurrencies:** +- โ No geographic restrictions +- โ No protocol-level sanctions +- โ No amount limits +- โ Instant payments + +**Important:** You must still comply with local laws and pay taxes! + +--- + +## Transparency and Trust + +### Trust Problem in Business + +**Typical Distrust Situations:** + +1. **Investors โ Founders** + - "Where did our money go?" + - "Why no profit?" + - "Where's the expense report?" + +2. **Partners โ Each Other** + - "Did you really invest the promised amount?" + - "Who gets how much dividends?" + - "Why am I not participating in decisions?" + +3. **Clients โ Company** + - "Do you really own this asset?" + - "Is my money safe?" + - "Do you have a license?" + +### Solution: Blockchain as Source of Truth + +#### Financial Transparency + +**Every token holder sees in real-time:** + +``` +Treasury (Company Treasury): +โโโ Assets: +โ โโโ 500,000 USDT +โ โโโ 10 BTC +โ โโโ Real Estate: 3 properties +โ โโโ Stocks: 10 companies +โโโ Liabilities: +โ โโโ Loan: 100,000 USDT +โ โโโ Salary Fund: 50,000 USDT/month +โโโ Operation History: + โโโ 2025-10-20: Received 200,000 USDT from client + โโโ 2025-10-21: Paid 50,000 USDT salaries + โโโ 2025-10-22: Bought 2 BTC for 100,000 USDT +``` + +**Impossible:** +- โ Hide expenses +- โ Withdraw money secretly +- โ Forge balance +- โ Hide losses + +#### Decision Transparency + +**Every decision recorded forever:** + +``` +Proposal #15: "Buy new office for 5 million" +โโโ Initiator: Ivan Petrov (0xABC...123) +โโโ Creation Date: 2025-10-15 +โโโ Voting Period: 7 days +โโโ Votes: +โ โโโ "For": 62% (6,200,000 tokens) +โ โ โโโ Owners: [address list] +โ โโโ "Against": 38% (3,800,000 tokens) +โ โโโ Owners: [address list] +โโโ Status: APPROVED โ +โโโ Executed: 2025-10-22 (automatically) +``` + +**Advantages:** +- โ Cannot say "I didn't vote for this!" +- โ Visible who initiated decision +- โ Motivation transparent (connections, interests) +- โ Cannot rewrite history + +#### Ownership Transparency + +**Everyone knows who owns what:** + +``` +DLE Token Owners: +โโโ 0xABC...123 (Ivan Petrov): 600,000 tokens (60%) +โโโ 0xDEF...456 (Company X): 300,000 tokens (30%) +โโโ 0xGHI...789 (Fund Y): 100,000 tokens (10%) +``` + +**Automatic Checks:** +- โ ๏ธ Conflict of Interest: detected +- โ ๏ธ Related Parties: found +- โ ๏ธ Ownership Concentration: critical + +### Reputation on Blockchain + +**Each company (DLE) has:** +- โ Immutable operation history +- โ Partner ratings +- โ Public financial indicators +- โ Verified assets + +**It's Like:** +- ๐ Credit History (but transparent) +- โญ Marketplace Rating (but cannot fake) +- ๐ Audit (but constant and free) + +--- + +## Automation and Cost Reduction + +### Eliminating Intermediaries + +**Who Blockchain Removes from Process:** + +``` +Traditional Transaction: +Company A โ Bank A โ SWIFT โ Bank B โ Company B + โ โ โ โ โ + 3-5% 0.5-1% $25-50 0.5-1% 3-5% + TOTAL: 7-12% fees + 3-7 days + +Blockchain Transaction: +Company A โโโโโโโโโโโโโโโโโโโโโโโ Company B + $0.10-5, 30 seconds +``` + +**Savings on $1,000,000 Turnover:** +- Traditionally: $70,000-120,000 fees +- Blockchain: $100-500 fees +- **Savings: $69,500-119,500 (99%)** + +### Process Automation + +#### 1. Corporate Governance + +**Was (Manual):** +``` +Steps for Decision Making: +1. Proposal Preparation: 2-5 days +2. Lawyer Approval: 3-7 days +3. Shareholder Distribution: 1 day +4. Meeting Convening: 30 days (by law) +5. Voting: 1 day +6. Vote Counting: 1-2 days +7. Protocol Preparation: 3-5 days +8. Decision Registration: 14-30 days + +TOTAL: 55-85 days +Cost: $2,000-10,000 +``` + +**Became (Automatic):** +``` +1. Create Proposal: 5 minutes +2. Voting: 1-7 days (configurable) +3. Automatic Execution: 30 seconds + +TOTAL: 1-7 days +Cost: $2-5 (gas fees) +``` + +#### 2. Dividend Payment + +**Was (Manual):** +``` +1. Determine Dividend Amount: 1 day +2. Calculate Each Shareholder's Share: 2-3 days +3. Payment Order Preparation: 2 days +4. Send to Bank: 1 day +5. Bank Processing: 3-7 days +6. Shareholder Receipt: 1-3 days + +TOTAL: 10-17 days +Cost: $500-2,000 +Errors: 5-10% of transactions +``` + +**Became (Automatic):** +``` +function distributeDividends() { + // One transaction โ everyone received +} + +TOTAL: 30 seconds +Cost: $5-20 +Errors: 0% (smart contract math) +``` + +#### 3. Audit and Reporting + +**Was (Manual):** +``` +Annual Audit: +โโโ Document Collection: 1-2 weeks +โโโ Auditor Review: 2-4 weeks +โโโ Corrections: 1-2 weeks +โโโ Final Report: 1 week +โโโ Cost: $5,000-50,000 + ++ Quarterly Reporting: another $2,000-10,000/quarter +``` + +**Became (Automatic):** +``` +Blockchain = Constant Audit: +โโโ Every transaction verified by network +โโโ Cannot forge data +โโโ Real-time reports for all +โโโ Cost: $0 (already included in blockchain) +``` + +**Savings:** $13,000-90,000/year on audit and reporting + +### Smart Contracts Instead of Lawyers + +**What Gets Automated:** + +| Process | Was | Became | +|---------|-----|--------| +| **Conditional Payment** | Escrow ($500-2,000) | Smart Contract ($5) | +| **Multi-party Signatures** | Notary ($100-500) | Multisig ($2-10) | +| **Automatic Payments** | Accountant ($2,000/month) | Smart Contract ($10/month) | +| **Royalty Distribution** | Lawyer ($5,000+) | Smart Contract ($20) | + +**Example: Escrow for Transaction** + +Traditionally: +``` +1. Find Escrow Agent +2. Sign Escrow Agreement +3. Pay Services: $500-2,000 +4. Transfer Money to Agent +5. Condition Check (manual) +6. Payment (3-7 days) +``` + +With Smart Contract: +```solidity +contract Escrow { + // Money locked until condition met + if (condition_met) { + send_money_to_seller(); + } else if (deadline_expired) { + return_money_to_buyer(); + } +} +``` +Cost: $5, automatic execution in 30 seconds + +--- + +## Practical Cases + +### Case 1: Startup Attracts Investment + +**Situation:** +Technology startup seeking $500,000 investment. + +**Traditional Path:** +``` +1. Investor Search: 6-12 months +2. Due Diligence: 2-3 months +3. Negotiations and Valuation: 1-2 months +4. Legal Formalities: 1-2 months + โโโ Charter Changes + โโโ Stock Issue + โโโ Tax Office Registration +5. Process Cost: + โโโ Lawyers: $20,000-50,000 + โโโ Appraisers: $5,000-10,000 + โโโ Registration: $2,000-5,000 + โโโ TOTAL: $27,000-65,000 + +TOTAL: 10-19 months + $27,000-65,000 +``` + +**With DLE on Blockchain:** +``` +1. Create DLE: 1 day + โโโ Issue 10,000,000 tokens + โโโ Founders Keep: 7,000,000 (70%) + โโโ For Investors: 3,000,000 (30%) + +2. Token Placement: + โโโ Launchpad on DEX + โโโ Price: $0.167 per token + โโโ Sold in: 3 days + โโโ Received: $500,000 + +3. Process Cost: + โโโ Smart Contract Deploy: $100 + โโโ DEX Listing: $500 + โโโ TOTAL: $600 + +TOTAL: 4 days + $600 +``` + +**Result:** +- โก 90x faster +- ๐ฐ 45-100x cheaper +- ๐ Access to global investors +- โ Instant token liquidity + +### Case 2: Real Estate Fund + +**Situation:** +Investment fund owns office building worth $10,000,000. Wants to raise funds for new project. + +**Traditional Path:** +``` +Options: +1. Bank Loan Secured: + โโโ Rate: 12-18% + โโโ Processing Time: 2-3 months + โโโ Appraisal + Lawyer Cost: $50,000 + +2. Sell Building Entirely: + โโโ Sale Time: 6-18 months + โโโ Agent Commission: 3-5% ($300,000-500,000) + โโโ Loses Asset + +3. Attract Fund Investors: + โโโ Fund Creation: $50,000-200,000 + โโโ Time: 6-12 months + โโโ Annual Maintenance: $20,000-50,000 +``` + +**With Tokenization via DLE:** +``` +1. Building Tokenization: + โโโ Issue 10,000,000 tokens + โโโ 1 token = $1 of building value + โโโ Time: 1 day + +2. Sell 30% of Tokens: + โโโ 3,000,000 tokens on DEX + โโโ Price: $1 per token + โโโ Sold in: 2 weeks + โโโ Received: $3,000,000 + +3. Rental Payments: + โโโ Rent: $100,000/month + โโโ Automatic Distribution: + โ โโโ 70% ($70,000) โ fund + โ โโโ 30% ($30,000) โ token holders + โโโ Payments: monthly, automatic + +4. Cost: + โโโ Tokenization: $500 + โโโ Listing: $500 + โโโ TOTAL: $1,000 +``` + +**Result:** +- โก Got $3M in 2 weeks +- ๐ฐ Kept asset (own 70%) +- ๐ Passive income continues +- ๐ Can buy back tokens +- ๐ธ Cost $1,000 vs $50,000-200,000 + +### Case 3: Music Label + +**Situation:** +Independent music label wants to release new artist's album. + +**Traditional Path:** +``` +1. Investment Search for Recording: + โโโ Need: $50,000 + โโโ Sources: bank, investors + โโโ Terms: 50% royalties to investors + โโโ Search Time: 3-6 months + +2. Album Release: + โโโ Recording: $30,000 + โโโ Promotion: $20,000 + โโโ Time: 3-6 months + +3. Streaming Revenue: + โโโ Spotify: $0.003-0.005 per play + โโโ Platforms Take: 30% + โโโ Label: 35% + โโโ Investors: 35% + โโโ Artist: 30% + +TOTAL: 6-12 months, artist gets only 30% +``` + +**With Tokenization via DLE:** +``` +1. Create DLE for Album: + โโโ Issue 1,000,000 tokens + โโโ Artist Keeps: 500,000 (50%) + โโโ Sell to Fans: 500,000 at $0.10 + โโโ Received: $50,000 in 1 week + +2. Album Release: + โโโ Recording: $30,000 + โโโ Promotion: $20,000 + โโโ Time: 3-6 months + +3. Streaming Revenue: + โโโ Revenue: $10,000/month + โโโ Automatic Distribution: + โ โโโ 50% ($5,000) โ artist + โ โโโ 50% ($5,000) โ token holders (fans) + โโโ Payments: monthly, automatic + +4. Bonuses: + โโโ Fans earn from artist's success + โโโ Tokens can be resold (secondary market) + โโโ Artist directly connected to fans + โโโ All revenue transparency +``` + +**Result:** +- โก Got investment in week +- ๐ฐ Artist gets 50% instead of 30% +- ๐ต Fans earn together with artist +- ๐ Token liquidity on secondary market + +### Case 4: Agribusiness (Crop Tokenization) + +**Situation:** +Farm grows wheat. Needs money for planting (April), harvest in August. + +**Traditional Path:** +``` +1. Bank Loan: + โโโ Amount: $200,000 + โโโ Rate: 15% annual + โโโ Loan Term: 6 months + โโโ Interest: $15,000 + โโโ Processing Time: 1 month + +2. Risks: + โโโ Crop Failure โ cannot pay loan + โโโ Price Drop โ losses + โโโ Bankruptcy +``` + +**With Crop Tokenization via DLE:** +``` +1. April (Planting): + โโโ Harvest Forecast: 1,000 tons of wheat + โโโ Issue 1,000,000 tokens + โโโ 1 token = 1 kg of wheat + โโโ Token Price: $0.25 (current price + 10%) + โโโ Sell 800,000 tokens โ $200,000 + +2. August (Harvest): + โโโ Harvested: 1,000 tons + โโโ Price Rose to $0.30/kg + โโโ Token Holders Can: + โ โโโ Get Physical Wheat + โ โโโ Sell Tokens at $0.30 + โ โโโ Earn: 20% in 4 months + โโโ Farmer Got Money Without Loan + +3. Advantages: + โโโ No Interest (0% vs 15%) + โโโ Crop Risk Shared with Investors + โโโ Direct Connection with Buyers + โโโ Entire Supply Chain Transparency +``` + +**Result:** +- ๐ฐ Saved $15,000 on interest +- ๐พ Risks shared with investors +- ๐ Investors earned 20% in 4 months +- ๐ Transparent supply chain + +--- + +## Economic Impact + +### Savings Calculation for Typical Business + +**Initial Data:** +- Turnover: $1,000,000/year +- Employees: 10 people +- Shareholders: 5 people +- International Operations: 20% of turnover + +#### 1. Banking Fee Savings + +``` +Traditionally: +โโโ Account Maintenance: $1,200/year +โโโ Domestic Transactions: 1% ร $800,000 = $8,000 +โโโ International Transfers: 5% ร $200,000 = $10,000 +โโโ SWIFT Fees: 50 transfers ร $35 = $1,750 +โโโ Currency Conversion: 3% ร $200,000 = $6,000 +โโโ TOTAL: $26,950/year + +With DLE (Crypto): +โโโ Gas Fees: $1,000/year +โโโ RPC Providers: $200/year +โโโ TOTAL: $1,200/year + +SAVINGS: $25,750/year (96%) +``` + +#### 2. Corporate Governance Savings + +``` +Traditionally: +โโโ Accountant: $24,000/year +โโโ Lawyer (Corporate Law): $15,000/year +โโโ Notary (Meetings, Transactions): $2,000/year +โโโ Shareholder Registry: $3,000/year +โโโ Audit: $10,000/year +โโโ TOTAL: $54,000/year + +With DLE: +โโโ Automation via Smart Contracts +โโโ Accountant (Taxes Only): $12,000/year +โโโ TOTAL: $12,000/year + +SAVINGS: $42,000/year (78%) +``` + +#### 3. Investment Attraction Savings + +``` +Traditionally (One Deal): +โโโ Lawyers: $30,000 +โโโ Appraisers: $7,000 +โโโ Due Diligence: $10,000 +โโโ Change Registration: $3,000 +โโโ TOTAL: $50,000 + +With DLE (Token Issue): +โโโ Smart Contract Deploy: $100 +โโโ DEX Listing: $500 +โโโ TOTAL: $600 + +SAVINGS: $49,400 per deal (99%) +``` + +#### 4. Time Savings (Opportunity Cost) + +``` +Traditionally: +โโโ Decision Making: 2-3 months +โโโ Dividend Payment: 2-3 weeks +โโโ Investment Attraction: 6-12 months +โโโ International Transfers: 3-7 days + +With DLE: +โโโ Decision Making: 1-7 days +โโโ Dividend Payment: 30 seconds +โโโ Investment Attraction: 1-14 days +โโโ International Transfers: 30 seconds + +Time Value Estimate: +โโโ 10 months saved ร $100,000 turnover/month +โโโ Additional Profit: $1,000,000 +``` + +### Total Annual Savings + +``` +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ ECONOMIC IMPACT FOR BUSINESS WITH โ +โ $1,000,000/YEAR TURNOVER โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ Banking Fees: -$25,750 โ +โ Corporate Governance: -$42,000 โ +โ Investment Attraction: -$49,400 โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ TOTAL SAVINGS: $117,150/year โ +โ โ +โ + Additional Profit from Speed: โ +โ ~$1,000,000 (missed opportunities) โ +โ โ +โ TOTAL IMPACT: $1,117,150 โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ ROI: 1,117% on DLE Investment โ +โ Payback: < 1 month โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +``` + +### Comparison with Competitors + +| Solution | Cost/Year | Transaction Fees | Speed | Transparency | +|----------|-----------|------------------|-------|--------------| +| **Traditional Business** | $54,000+ | 3-7% | 3-7 days | โ Low | +| **SaaS Solutions** | $12,000-60,000 | 2-5% | 1-3 days | โ ๏ธ Medium | +| **DLE on Blockchain** | $1,200-3,000 | 0.01-0.5% | 30 sec | โ Full | + +--- + +## Conclusion + +### Why Blockchain is the Future of Business? + +Digital Legal Entity on blockchain solves fundamental problems of modern business: + +1. **๐ฆ Financial Freedom** + - Operations without banks + - Instant transfers worldwide + - Minimal fees (99% savings) + - No geographic restrictions + +2. **๐ Universal Identity** + - One smart contract address = all identifiers + - Replaces Tax ID, bank account, email, phone + - Cryptographic protection from forgery + +3. **๐ฐ Asset Tokenization** + - Any asset becomes liquid + - Fractional ownership (from $1) + - Global market 24/7 + - Automatic income + +4. **๐ณ๏ธ Transparent Management** + - Every shareholder sees everything + - Cannot hide decisions + - Automatic execution + - Protection from corruption + +5. **โก Automation** + - Smart contracts instead of lawyers + - Automatic payments + - Eliminates human errors + - 90-99% time and money savings + +### Economic Benefit + +For business with $1M/year turnover: +- ๐ฐ **Savings: $117,000/year** (on fees and management) +- โก **Additional Profit: ~$1,000,000** (from speed) +- ๐ **ROI: 1,117%** on DLE implementation +- ๐ฏ **Payback: < 1 month** + +### Start Now! + +1. ๐ **[Study FAQ](./FAQ.md)** - answers to popular questions +2. ๐ **[Install DLE](./setup-instruction.md)** - step-by-step guide +3. ๐ **[Configure Blockchain](./blockchain-integration-technical.md)** - technical documentation +4. ๐ฌ **[Get Support](https://hb3-accelerator.com/)** - we'll help! + +--- + +## Additional Resources + +### Documentation +- ๐ [FAQ](./FAQ.md) +- ๐ง [Installation](./setup-instruction.md) +- ๐ [Blockchain Technical Documentation](./blockchain-integration-technical.md) +- ๐ [Terms of Service](./service-terms.md) + +### Support +- ๐ฌ **Support Chat**: https://hb3-accelerator.com/ +- ๐ง **Email**: info@hb3-accelerator.com +- ๐ **Website**: https://hb3-accelerator.com + +--- + +**ยฉ 2024-2025 Tarabanov Alexander Viktorovich. All rights reserved.** + +**Last Updated**: October 2025 + diff --git a/docs-en/blockchain-integration-technical.md b/docs-en/blockchain-integration-technical.md new file mode 100644 index 0000000..dd4bbc6 --- /dev/null +++ b/docs-en/blockchain-integration-technical.md @@ -0,0 +1,1049 @@ +# Digital Legal Entity (DLE) Blockchain Integration + +## ๐ Table of Contents + +1. [Introduction](#introduction) +2. [Smart Contract Architecture](#smart-contract-architecture) +3. [Main DLE Contract](#main-dle-contract) +4. [Modular System](#modular-system) +5. [Multichain Architecture](#multichain-architecture) +6. [Voting System (Governance)](#voting-system-governance) +7. [Smart Contract Deployment](#smart-contract-deployment) +8. [Wallet Authentication](#wallet-authentication) +9. [Frontend Integration](#frontend-integration) +10. [Security](#security) +11. [Practical Examples](#practical-examples) + +--- + +## Introduction + +Digital Legal Entity (DLE) uses blockchain technologies to provide **tokenized governance** (similar to a joint-stock company on blockchain) and **transparent decision-making** through smart contracts. + +### Why Blockchain in DLE? + +1. **๐ณ๏ธ Governance Like Joint-Stock Company** - decisions made by token holders through blockchain voting +2. **๐ Transparency** - all votes and operations recorded on blockchain +3. **๐ก๏ธ Censorship Resistance** - smart contract guarantees token holder rights +4. **๐ Immutability** - decision history is unchangeable +5. **๐ Multichain Support** - work in multiple blockchains simultaneously + +### DLE Governance Model + +DLE uses a **hybrid governance model**: + +| Aspect | Implementation | +|--------|----------------| +| **Voting** | Token holders (like shareholders) | +| **Quorum** | 51%+ tokens for decision making | +| **Asset Distribution** | Through voting (like in JSC) | +| **Parameter Changes** | Through token holder voting | +| **Application Code** | Proprietary (author) | +| **Updates** | Author develops, token holders vote on priorities | + +This is a **tokenized joint-stock company on blockchain**, where: +- โ Parameter management - through token holder voting (like shareholders) +- โ Asset distribution - through voting (like in JSC) +- โ ๏ธ Code development - centralized (author) +- โ ๏ธ Update releases - author (based on voting priorities) + +### Supported Blockchains + +DLE works with any **EVM-compatible** networks: +- โ Ethereum (mainnet & testnets: Sepolia, Holesky) +- โ Polygon (mainnet & testnets) +- โ Arbitrum (One & Sepolia) +- โ Binance Smart Chain (BSC) +- โ Base (mainnet & Sepolia) +- โ And any other EVM networks + +--- + +## Smart Contract Architecture + +### System Overview + +``` +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ DLE Ecosystem โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ DLE Core Contract (ERC20Votes) โ โ +โ โ โข Governance Tokens (ERC20) โ โ +โ โ โข Voting (ERC20Votes) โ โ +โ โ โข Signatures (ERC20Permit) โ โ +โ โ โข Proposals โ โ +โ โ โข Multichain Support โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ Modules (Extensions) โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค โ +โ โ โข HierarchicalVotingModule โ โ +โ โ - Voting in other DLEs โ โ +โ โ - Owning tokens of other DLEs โ โ +โ โ โ โ +โ โ โข TreasuryModule โ โ +โ โ - Treasury Management โ โ +โ โ - Token Storage โ โ +โ โ โ โ +โ โ โข TimelockModule โ โ +โ โ - Delayed Execution โ โ +โ โ - Protection from Instant Changes โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ DLEReader (Data Reader) โ โ +โ โ โข Batch Data Reading โ โ +โ โ โข RPC Query Optimization โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +``` + +### Standards and Libraries + +DLE uses proven **OpenZeppelin** standards: + +| Standard | Purpose | +|----------|---------| +| **ERC20** | Basic token functionality | +| **ERC20Votes** | Voting with snapshots | +| **ERC20Permit** | Signatures without gas (meta-transactions) | +| **ReentrancyGuard** | Reentrancy protection | +| **ECDSA** | Signature verification | + +--- + +## Main DLE Contract + +### Contract Structure + +File: `backend/contracts/DLE.sol` + +```solidity +contract DLE is ERC20, ERC20Permit, ERC20Votes, ReentrancyGuard, IMultichainMetadata { + // Main DLE Data + struct DLEInfo { + string name; // Organization name + string symbol; // Token symbol + string location; // Location + string coordinates; // GPS coordinates + uint256 jurisdiction; // Jurisdiction + string[] okvedCodes; // OKVED codes + uint256 kpp; // KPP (for Russia) + uint256 creationTimestamp; + bool isActive; + } + + // Voting Proposal + struct Proposal { + uint256 id; + string description; + uint256 forVotes; // "For" votes + uint256 againstVotes; // "Against" votes + bool executed; + bool canceled; + uint256 deadline; + address initiator; + bytes operation; // Operation to execute + uint256 governanceChainId; // Voting network + uint256[] targetChains; // Target networks for execution + uint256 snapshotTimepoint; + mapping(address => bool) hasVoted; + } +} +``` + +### Key Capabilities + +#### 1. Governance Tokens (ERC20) + +DLE tokens represent **voting rights** in governance: +- 1 token = 1 vote +- Tokens **NOT transferable** by normal methods (only through governance) +- EIP-712 signatures for meta-transactions + +```solidity +// Token Transfers BLOCKED +function transfer(address, uint256) public pure override returns (bool) { + revert ErrTransfersDisabled(); +} + +// Approvals BLOCKED +function approve(address, uint256) public pure override returns (bool) { + revert ErrApprovalsDisabled(); +} +``` + +#### 2. Voting (ERC20Votes) + +Uses **snapshots** of votes: +- Flash-loan protection +- Votes taken from past block +- Delegation (optional) + +```solidity +function getPastVotes(address account, uint256 timepoint) public view returns (uint256) +``` + +#### 3. Multichain Support + +DLE can be deployed in **multiple networks simultaneously**: +- One address in all networks (deterministic deployment) +- Voting in one network (governance chain) +- Execution in any target networks + +```solidity +// Supported Networks +mapping(uint256 => bool) public supportedChains; +uint256[] public supportedChainIds; + +// Add Network (only through voting) +function _addSupportedChain(uint256 _chainId) internal { + require(!supportedChains[_chainId], "Chain already supported"); + supportedChains[_chainId] = true; + supportedChainIds.push(_chainId); + emit ChainAdded(_chainId); +} +``` + +#### 4. Modular Architecture + +DLE supports **extensions through modules**: + +```solidity +// Modules +mapping(bytes32 => address) public modules; +mapping(bytes32 => bool) public activeModules; + +// Add Module (only through voting) +function _addModule(bytes32 _moduleId, address _moduleAddress) internal { + if (_moduleAddress == address(0)) revert ErrZeroAddress(); + if (activeModules[_moduleId]) revert ErrProposalExecuted(); + + modules[_moduleId] = _moduleAddress; + activeModules[_moduleId] = true; + + emit ModuleAdded(_moduleId, _moduleAddress); +} +``` + +### Operations Available Through Voting + +| Operation | Description | +|-----------|-------------| +| `_addModule` | Add new module | +| `_removeModule` | Remove module | +| `_addSupportedChain` | Add blockchain | +| `_removeSupportedChain` | Remove blockchain | +| `_transferTokens` | Transfer tokens | +| `_updateDLEInfo` | Update DLE information | +| `_updateQuorumPercentage` | Change quorum | +| `_updateVotingDurations` | Change voting duration | + +--- + +## Modular System + +### 1. HierarchicalVotingModule + +**Purpose**: Hierarchical Voting - DLE can vote in other DLEs. + +**File**: `backend/contracts/HierarchicalVotingModule.sol` + +**Capabilities**: +- โ DLE can own tokens of other DLEs +- โ Vote in other DLEs on its behalf +- โ Create proposals in other DLEs +- โ Track voting chain + +```solidity +struct ExternalDLEInfo { + address dleAddress; + string name; + string symbol; + uint256 tokenBalance; // Balance of tokens of this DLE + bool isActive; + uint256 addedAt; +} + +// Add External DLE +function addExternalDLE( + address dleAddress, + string memory name, + string memory symbol +) external onlyDLE; + +// Create Proposal in External DLE +function createProposalInExternalDLE( + address externalDLE, + string calldata description, + uint256 duration, + bytes calldata operation, + uint256 chainId +) external onlyDLE returns (uint256); +``` + +**Usage Example**: +```javascript +// DLE-A owns tokens of DLE-B +// DLE-A can vote in DLE-B automatically +const hierarchicalModule = await ethers.getContractAt('HierarchicalVotingModule', moduleAddress); +await hierarchicalModule.voteInExternalDLE(dleBAddress, proposalId, true); +``` + +### 2. TreasuryModule + +**Purpose**: Treasury and asset management for DLE. + +**File**: `backend/contracts/TreasuryModule.sol` + +**Capabilities**: +- โ Token and asset storage +- โ Management through token holder voting +- โ Payment sending +- โ Income accumulation + +```solidity +// Transfer Tokens from Treasury (only through DLE voting) +function transferTokens( + address token, + address recipient, + uint256 amount +) external onlyDLE; + +// Get Token Balance in Treasury +function getTokenBalance(address token) external view returns (uint256); +``` + +**Usage Example**: +```javascript +// Create Proposal for Treasury Payment +const operation = treasuryModule.interface.encodeFunctionData('transferTokens', [ + tokenAddress, + recipientAddress, + ethers.parseEther('100') +]); + +await dleContract.createProposal( + 'Pay 100 tokens for marketing', + 86400, // 24 hours + operation, + chainId, + [chainId] +); +``` + +### 3. TimelockModule + +**Purpose**: Delayed operation execution for security. + +**File**: `backend/contracts/TimelockModule.sol` + +**Capabilities**: +- โ Delay before execution (timelock) +- โ Cancellation possibility before execution +- โ Protection from instant changes + +```solidity +struct TimelockProposal { + uint256 proposalId; + uint256 executionTime; // Time when can execute + bytes32 operationHash; + bool executed; + bool canceled; +} + +// Create Timelock Proposal +function scheduleProposal( + uint256 proposalId, + bytes calldata operation, + uint256 delay +) external onlyDLE returns (bytes32); + +// Execute After Timelock Expires +function executeTimelockProposal(bytes32 operationHash) external; +``` + +### 4. DLEReader + +**Purpose**: Optimized data reading from contracts. + +**File**: `backend/contracts/DLEReader.sol` + +**Capabilities**: +- โ Batch reading of multiple data in one RPC query +- โ Get detailed DLE information +- โ List all proposals with details +- โ Gas optimization for reading + +```solidity +// Get Full DLE Information in One Query +function getDLEFullInfo(address dleAddress) external view returns ( + string memory name, + string memory symbol, + uint256 totalSupply, + DLEInfo memory info, + uint256 proposalCount, + // ... and other data +); + +// Get All Proposals (batch read) +function getAllProposals(address dleAddress) external view returns (ProposalInfo[] memory); +``` + +--- + +## Multichain Architecture + +### Concept + +DLE supports **deterministic deployment** - one address in all networks: + +``` +Ethereum: 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C +Polygon: 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C โ Same address! +Arbitrum: 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C +BSC: 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C +``` + +### How It Works? + +1. **Init Code Generation** - same bytecode for all networks +2. **Fixed Nonce** - deployment from same nonce +3. **CREATE Opcode** - address = keccak256(deployerAddress, nonce) +4. **Result** - same address in all networks + +### Voting in One Network + +**Voting** happens in **one network** (governance chain), and **execution** - in any target networks: + +``` +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ Ethereum (Governance Chain) โ +โ 1. Proposal Creation โ +โ 2. Voting โ +โ 3. Vote Counting โ +โ 4. Signature Generation for Execution โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ + โ + โโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโ + โ โ +โโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโ +โ Polygon โ โ Arbitrum โ +โ (Target Chain) โ โ (Target Chain) โ +โ 5. Execution โ โ 5. Execution โ +โ with Signatureโ โ with Signatureโ +โโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโ +``` + +### Multichain Execution + +Execution through **signatures** (off-chain coordination): + +```solidity +function executeWithSignatures( + uint256 proposalId, + bytes32 operationHash, + address[] calldata signers, + bytes[] calldata signatures +) external nonReentrant; +``` + +**Process**: +1. Proposal approved in governance network +2. Token holder signatures generated +3. Signatures passed to target networks +4. Contract verifies signatures and executes operation + +--- + +## Voting System (Governance) + +### Creating Proposal + +```solidity +function createProposal( + string calldata _description, + uint256 _duration, + bytes calldata _operation, + uint256 _chainId, + uint256[] calldata _targetChains, + address _initiator +) external returns (uint256); +``` + +**Parameters**: +- `_description` - proposal description +- `_duration` - voting duration (in seconds) +- `_operation` - operation to execute (encoded function call) +- `_chainId` - network ID for voting +- `_targetChains` - target networks for execution +- `_initiator` - initiator address + +**Example** (backend): +```javascript +const { ethers } = require('ethers'); + +// Operation: add module +const operation = dleContract.interface.encodeFunctionData('_addModule', [ + ethers.id('TIMELOCK_MODULE'), // moduleId + timelockModuleAddress +]); + +// Create Proposal +const tx = await dleContract.createProposal( + 'Add Timelock Module for Protection', + 86400 * 3, // 3 days + operation, + 1, // Ethereum mainnet + [1, 137, 42161], // Ethereum, Polygon, Arbitrum + walletAddress +); + +const receipt = await tx.wait(); +const proposalId = receipt.events[0].args.proposalId; +``` + +### Voting + +```solidity +function vote(uint256 _proposalId, bool _support) external; +``` + +**Parameters**: +- `_proposalId` - proposal ID +- `_support` - true = "For", false = "Against" + +**Example** (frontend): +```javascript +// Connect to Contract +const dleContract = new ethers.Contract(dleAddress, dleAbi, signer); + +// Vote "For" +await dleContract.vote(proposalId, true); + +// Vote "Against" +await dleContract.vote(proposalId, false); +``` + +### Proposal Execution + +```solidity +function execute(uint256 _proposalId) external nonReentrant; +``` + +**Execution Conditions**: +1. โ Voting completed (deadline passed) +2. โ Quorum reached (e.g., 10% of tokens voted) +3. โ More "For" votes than "Against" +4. โ Proposal not yet executed + +**Example**: +```javascript +// Check if Can Execute +const proposal = await dleContract.proposals(proposalId); +const canExecute = ( + proposal.deadline < Date.now() / 1000 && + !proposal.executed && + proposal.forVotes > proposal.againstVotes +); + +if (canExecute) { + await dleContract.execute(proposalId); +} +``` + +### Quorum + +Quorum determines **minimum number of votes** for decision making: + +```solidity +uint256 public quorumPercentage; // Percentage of totalSupply (e.g., 10%) + +function _hasQuorum(uint256 _forVotes, uint256 _againstVotes) internal view returns (bool) { + uint256 totalVotes = _forVotes + _againstVotes; + uint256 requiredVotes = (totalSupply() * quorumPercentage) / 100; + return totalVotes >= requiredVotes; +} +``` + +**Changing Quorum** (only through voting): +```javascript +const operation = dleContract.interface.encodeFunctionData('_updateQuorumPercentage', [ + 15 // New quorum 15% +]); + +await dleContract.createProposal( + 'Increase Quorum to 15%', + 86400 * 7, + operation, + chainId, + [chainId] +); +``` + +--- + +## Smart Contract Deployment + +### Multichain Deployment + +**Script**: `backend/scripts/deploy/deploy-multichain.js` + +**Capabilities**: +- โ Deployment to multiple networks simultaneously (parallel) +- โ Deterministic address (one address in all networks) +- โ Automatic contract verification +- โ Retry logic on errors +- โ Nonce management for synchronization + +**Run**: +```bash +cd backend +yarn deploy:multichain +``` + +**Configuration** (database): +Deployment parameters stored in `settings` table: +- `supported_chain_ids` - list of network IDs for deployment +- `rpc_providers` - RPC URLs for each network +- `dle_config` - DLE configuration (name, symbol, partners, etc.) + +**Configuration Example**: +```json +{ + "name": "My Company DLE", + "symbol": "MYCO", + "location": "Moscow, Russia", + "coordinates": "55.7558,37.6173", + "jurisdiction": 643, + "okvedCodes": ["62.01", "62.02"], + "kpp": 770401001, + "quorumPercentage": 10, + "initialPartners": ["0x742d35..."], + "initialAmounts": [1000000], + "supportedChainIds": [1, 137, 42161] +} +``` + +### Module Deployment + +**Script**: `backend/scripts/deploy/deploy-modules.js` + +**Run**: +```bash +cd backend +yarn deploy:modules +``` + +**Process**: +1. Load DLE address from database +2. Parallel deployment of all modules in all networks +3. CREATE2 deployment for deterministic addresses +4. Automatic verification +5. Save module addresses to database + +### Contract Verification + +**Automatic Verification** via Etherscan API: + +```javascript +async function verifyDLEAfterDeploy(chainId, contractAddress, constructorArgs, apiKey, params) { + await hre.run("verify:verify", { + address: contractAddress, + constructorArguments: constructorArgs, + contract: "contracts/DLE.sol:DLE" + }); +} +``` + +**Supported Scanners**: +- Etherscan (Ethereum, Sepolia, Holesky) +- Polygonscan +- Arbiscan +- BSCScan +- Basescan + +--- + +## Wallet Authentication + +### SIWE (Sign-In with Ethereum) + +DLE uses **SIWE** standard for authentication: + +**File**: `backend/routes/auth.js` + +**Authentication Process**: + +``` +โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ +โ Frontend โ โ Backend โ +โโโโโโโโฌโโโโโโโโ โโโโโโโโฌโโโโโโโโ + โ โ + โ 1. Request nonce โ + โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ>โ + โ โ + โ 2. Return nonce โ + โ<โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค + โ โ + โ 3. Sign Message in Wallet โ + โ (Private Key NOT Transferred!) โ + โ โ + โ 4. Send Signature โ + โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ>โ + โ โ + โ 5. Verify Signature + โ 6. Check Tokens + โ 7. Create Session + โ โ + โ 8. Successful Authentication โ + โ<โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค + โ โ +``` + +### Request Nonce + +```javascript +// POST /api/auth/nonce +app.post('/api/auth/nonce', async (req, res) => { + const { address } = req.body; + + // Generate Random Nonce + const nonce = crypto.randomBytes(32).toString('hex'); + + // Save to DB with Encryption + await db.query( + 'INSERT INTO nonces (identity_value_encrypted, nonce_encrypted, expires_at) VALUES ($1, $2, $3)', + [encrypt(address.toLowerCase()), encrypt(nonce), expiresAt] + ); + + res.json({ nonce }); +}); +``` + +### Signature Verification + +```javascript +// POST /api/auth/verify +app.post('/api/auth/verify', async (req, res) => { + const { address, signature, nonce } = req.body; + + // Form SIWE Message + const message = new SiweMessage({ + domain: req.get('host'), + address: ethers.getAddress(address), + statement: 'Sign in with Ethereum to the app.', + uri: req.get('origin'), + version: '1', + chainId: 1, + nonce: nonce + }); + + // Verify Signature + const isValid = await verifySignature( + message.prepareMessage(), + signature, + address + ); + + if (!isValid) { + return res.status(401).json({ error: 'Invalid signature' }); + } + + // Check Tokens in Smart Contract + const userAccessLevel = await getUserAccessLevel(address); + + // Create Session + req.session.userId = userId; + req.session.address = address; + req.session.authenticated = true; + req.session.userAccessLevel = userAccessLevel; + + res.json({ success: true, userAccessLevel }); +}); +``` + +### Access Level Check + +```javascript +async function getUserAccessLevel(address) { + // Get DLE Contract Address from Settings + const dleAddress = await getSettingValue('contract_address'); + if (!dleAddress) { + return { level: 'user', tokenCount: 0, hasAccess: false }; + } + + // Connect to Contract + const dleContract = new ethers.Contract(dleAddress, dleAbi, provider); + + // Get Token Balance + const tokenCount = await dleContract.balanceOf(address); + + // Access Thresholds from Settings + const editorThreshold = await getSettingValue('editor_token_threshold') || 100; + const readonlyThreshold = await getSettingValue('readonly_token_threshold') || 1; + + // Determine Access Level + if (tokenCount >= editorThreshold) { + return { level: 'editor', tokenCount, hasAccess: true }; + } else if (tokenCount >= readonlyThreshold) { + return { level: 'readonly', tokenCount, hasAccess: true }; + } else { + return { level: 'user', tokenCount: 0, hasAccess: false }; + } +} +``` + +--- + +## Frontend Integration + +### Wallet Connection + +**File**: `frontend/src/services/web3Service.js` + +```javascript +import { ethers } from 'ethers'; + +export async function connectWallet() { + if (!window.ethereum) { + throw new Error('MetaMask not installed'); + } + + // Request Wallet Access + await window.ethereum.request({ method: 'eth_requestAccounts' }); + + // Create Provider + const provider = new ethers.BrowserProvider(window.ethereum); + const signer = await provider.getSigner(); + const address = await signer.getAddress(); + + return { provider, signer, address }; +} +``` + +### Message Signing + +```javascript +export async function signMessage(signer, message) { + try { + const signature = await signer.signMessage(message); + return signature; + } catch (error) { + throw new Error('User rejected signature'); + } +} +``` + +### Authentication + +```javascript +import axios from 'axios'; + +export async function authenticateWithWallet(address, signer) { + // 1. Get Nonce + const { data } = await axios.post('/api/auth/nonce', { address }); + const { nonce } = data; + + // 2. Form SIWE Message + const message = `Sign in with Ethereum to the app.\n\nNonce: ${nonce}`; + + // 3. Sign + const signature = await signMessage(signer, message); + + // 4. Send for Verification + const response = await axios.post('/api/auth/verify', { + address, + signature, + nonce, + issuedAt: new Date().toISOString() + }); + + return response.data; +} +``` + +### Contract Interaction + +```javascript +import { ethers } from 'ethers'; +import dleAbi from '@/contracts/DLE.json'; + +export async function getDLEContract(address, signerOrProvider) { + return new ethers.Contract(address, dleAbi.abi, signerOrProvider); +} + +// Create Proposal +export async function createProposal(contract, description, duration, operation, chainId) { + const tx = await contract.createProposal( + description, + duration, + operation, + chainId, + [chainId] + ); + + const receipt = await tx.wait(); + return receipt; +} + +// Vote +export async function voteOnProposal(contract, proposalId, support) { + const tx = await contract.vote(proposalId, support); + await tx.wait(); +} + +// Get Proposal Information +export async function getProposal(contract, proposalId) { + const proposal = await contract.proposals(proposalId); + return { + id: proposal.id.toString(), + description: proposal.description, + forVotes: ethers.formatEther(proposal.forVotes), + againstVotes: ethers.formatEther(proposal.againstVotes), + executed: proposal.executed, + deadline: new Date(proposal.deadline * 1000) + }; +} +``` + +### Vue Component for Voting + +```vue + + + {{ proposal.description }} + + For: {{ proposal.forVotes }} + Against: {{ proposal.againstVotes }} + + + Vote "For" + Vote "Against" + + + + + + + +``` + +--- + +## Security + +> ๐ก **Detailed Information**: See [DLE Security](./security.md) - detailed description of all protection levels, attack scenarios, and security recommendations. + +### Brief Technical Overview + +**Key Smart Contract Security Principles:** +- ๐ **ReentrancyGuard** - reentrancy protection +- ๐ซ **Transfer Blocking** - tokens transfer only through governance +- ๐ธ **Vote Snapshots** - flash-loan attack protection +- โ๏ธ **EIP-712 Signatures** - contract wallet support +- โ **Parameter Validation** - all input data validation +- ๐ฐ **Custom Errors** - gas savings on errors + +**Implementation Examples:** + +```solidity +// Reentrancy Protection +import "@openzeppelin/contracts/utils/ReentrancyGuard.sol"; + +contract DLE is ReentrancyGuard { + function execute(uint256 _proposalId) external nonReentrant { + // Operation protected from reentrancy + } +} + +// Token Transfer Blocking +function transfer(address, uint256) public pure override returns (bool) { + revert ErrTransfersDisabled(); +} + +// Vote Snapshots +uint256 public snapshotTimepoint = block.number - 1; + +function vote(uint256 _proposalId, bool _support) external { + uint256 votingPower = getPastVotes(msg.sender, snapshotTimepoint); + require(votingPower > 0, "No voting power"); +} +``` + +--- + +## Practical Examples + +> ๐ก **Detailed Examples and Cases**: See [Blockchain for Business](./blockchain-for-business.md) - detailed description of real business cases, economic calculations, and practical DLE usage examples. + +### Brief Technical Overview + +**Main Usage Scenarios:** + +1. **Multichain Deployment** - DLE deployment in multiple networks simultaneously +2. **Module Addition** - functionality extension through voting +3. **Hierarchical Voting** - DLE can vote in other DLEs +4. **Treasury Management** - fund distribution through token holder voting +--- + +## Conclusion + +Blockchain integration in DLE provides: +- โ **Governance Like Joint-Stock Company** - token holders vote on decisions +- โ **Transparency** of all decisions on blockchain +- โ **Multichain Support** for work in multiple networks +- โ **Modular Architecture** for functionality extension +- โ **Security** through proven OpenZeppelin standards + +### Additional Resources + +- ๐ [Main README](../README.md) +- ๐ [FAQ](./FAQ.md) +- ๐ง [Installation Instructions](./setup-instruction.md) +- ๐ [Terms of Service](./service-terms.md) +- โ๏ธ [Legal Documentation](../legal/README.md) + +### Contacts and Support + +- ๐ **Portal**: https://hb3-accelerator.com/ +- ๐ง **Email**: info@hb3-accelerator.com +- ๐ **GitHub**: https://github.com/VC-HB3-Accelerator + +--- + +**ยฉ 2024-2025 Tarabanov Alexander Viktorovich. All rights reserved.** + +**Last Updated**: October 2025 + diff --git a/docs-en/security.md b/docs-en/security.md new file mode 100644 index 0000000..fc575b4 --- /dev/null +++ b/docs-en/security.md @@ -0,0 +1,1309 @@ +# Security of Digital Legal Entity (DLE) + +## ๐ Table of Contents + +1. [Introduction](#introduction) +2. [Security Model](#security-model) +3. [Token-Based Access Control](#token-based-access-control) +4. [Smart Contract Security](#smart-contract-security) +5. [Wallet Hack Protection](#wallet-hack-protection) +6. [Web Application Security](#web-application-security) +7. [Module Management](#module-management) +8. [Audit and Monitoring](#audit-and-monitoring) +9. [Security Recommendations](#security-recommendations) +10. [Attack Scenarios and Protection](#attack-scenarios-and-protection) + +--- + +## Introduction + +Digital Legal Entity (DLE) is built with a focus on **security at all levels**: +- ๐ Access control through blockchain tokens +- ๐ก๏ธ Smart contract protection from hacking +- ๐ Impossible to steal tokens even if wallet is hacked +- โ๏ธ Management only through voting with quorum + +### Key Security Principles + +1. **Security by default** - all actions are prohibited until explicitly allowed +2. **Least privilege** - everyone gets only necessary rights +3. **Transparency** - all actions recorded on blockchain +4. **Immutability** - impossible to forge history +5. **Collective control** - critical operations only through voting + +--- + +## Security Model + +### Security Architecture + +``` +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ DLE Protection Levels โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ โ +โ Level 1: Blockchain (Immutable Base) โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ โข DLE Smart Contract (audited, immutable) โ โ +โ โ โข Governance Tokens (ERC20Votes) โ โ +โ โ โข History of all operations on blockchain โ โ +โ โ โข Impossible to change rules without voting โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ โ +โ Level 2: Web Application (Backend) โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ โข Real-time token verification โ โ +โ โ โข Wallet authentication (SIWE) โ โ +โ โ โข Data encryption (AES-256) โ โ +โ โ โข Rate limiting and DDoS protection โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ โ +โ Level 3: Frontend (Vue.js) โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ โข Wallet connection โ โ +โ โ โข Transaction signing โ โ +โ โ โข XSS protection (DOMPurify) โ โ +โ โ โข CSRF tokens โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ โ +โ Level 4: User โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ โข Wallet private key (MetaMask, WalletConnect) โ โ +โ โ โข Confirmation of each operation โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +``` + +### Threat Model + +| Threat | Risk Level | Protection | +|--------|------------|------------| +| **Wallet hack** | ๐ก Medium | Tokens cannot be transferred without voting | +| **Web application hack** | ๐ข Low | All rights verified on blockchain, management via blockchain explorers | +| **Smart contract compromise** | ๐ข Low | Audit, OpenZeppelin, immutability | +| **DDoS attack** | ๐ก Medium | Rate limiting, CDN, backup servers | +| **Phishing** | ๐ High | User education, domain verification | +| **Insider threat** | ๐ข Low | All actions through voting | + +### โ ๏ธ Critical: Web Application is Only an Interface + +**Key feature of DLE architecture:** + +``` +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ Web Application (Interface) โ +โ โ +โ Frontend + Backend = CONVENIENCE of use โ +โ โข Beautiful UI โ +โ โข Convenient navigation โ +โ โข Quick access to functions โ +โ โ +โ โ ๏ธ Can be hacked/unavailable โ +โ โ BUT! Business assets are protected โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ + โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ Blockchain (Real Power) โ +โ โ +โ Smart Contracts = REAL asset management โ +โ โข Governance tokens โ +โ โข Treasury with assets โ +โ โข Voting rules โ +โ โข History of all decisions โ +โ โ +โ ๐ Protected by cryptography โ +โ โ Works independently of web application โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +``` + +**What happens when web application is hacked:** + +``` +Web application hacked/unavailable: +โโโ โ Web interface doesn't work +โโโ โ Backend may show incorrect information +โโโ โ Frontend may be replaced +โ +BUT: +โโโ โ All business assets remain on blockchain +โโโ โ Smart contracts continue to work +โโโ โ Tokens cannot be stolen +โโโ โ Can manage via Etherscan/Polygonscan/etc. +โโโ โ Can create new frontend and connect to same contracts +``` + +**Real example:** + +1. Attacker hacks your server with web application +2. Tries to show fake token balances +3. **But**: Real balances on blockchain remain unchanged +4. You open Etherscan and see the truth +5. Create proposal via Etherscan for recovery +6. Vote and execute proposal +7. Restore web application +8. **Result**: Not a single token lost โ + +--- + +## Token-Based Access Control + +### How It Works + +**Without tokens, access to application is IMPOSSIBLE.** + +``` +Access attempt to DLE: +โโโ 1. User connects wallet +โโโ 2. Backend checks token balance in smart contract +โโโ 3. If NO tokens โ Access DENIED +โโโ 4. If tokens EXIST โ Access granted (level depends on amount) +``` + +### Access Levels + +| Tokens on balance | Access Level | Rights | +|-------------------|--------------|--------| +| **0 tokens** | โ No access | Only "No access" page | +| **1+ tokens** | โ ReadOnly | View data | +| **100+ tokens** | โ Editor | Editing, creation | +| **Any amount** | ๐ณ๏ธ Voting | 1 token = 1 vote | + +### Real-Time Token Verification + +**Backend** constantly checks token balance: + +```javascript +// Every request checks tokens +async function checkAccess(req, res, next) { + const address = req.session.address; + + // Get token balance from smart contract + const dleContract = new ethers.Contract(dleAddress, dleAbi, provider); + const balance = await dleContract.balanceOf(address); + + if (balance === 0n) { + return res.status(403).json({ + error: 'Access denied: no tokens' + }); + } + + // Determine access level + const accessLevel = determineAccessLevel(balance); + req.user = { address, balance, accessLevel }; + + next(); +} +``` + +**Important**: Verification happens on **every request**, so: +- โ If tokens transferred โ access instantly lost +- โ If tokens received โ access instantly appears +- โ Impossible to bypass verification + +### Initial Token Distribution + +**Tokens are distributed by owner when deploying smart contract:** + +```solidity +constructor(DLEConfig memory config) { + // Create tokens + _mint(address(this), totalSupply); + + // Distribute among partners + for (uint i = 0; i < config.initialPartners.length; i++) { + _transfer( + address(this), + config.initialPartners[i], + config.initialAmounts[i] + ); + } +} +``` + +**Process**: +1. Wallet owner deploys DLE smart contract +2. Specifies partner addresses and token amounts for each +3. Tokens automatically distributed on deployment +4. After that, all changes only through voting + +**Distribution example**: +```javascript +const config = { + initialPartners: [ + '0xAlice...', // Founder 1 + '0xBob...', // Founder 2 + '0xCarol...' // Investor + ], + initialAmounts: [ + 500000, // 50% for Alice + 300000, // 30% for Bob + 200000 // 20% for Carol + ] +}; +``` + +--- + +## Smart Contract Security + +### Protection from Token Transfers + +**CRITICAL**: Governance tokens **CANNOT** be transferred by normal means! + +```solidity +// Transfers BLOCKED +function transfer(address to, uint256 amount) + public + pure + override + returns (bool) +{ + revert ErrTransfersDisabled(); +} + +// Approvals BLOCKED +function approve(address spender, uint256 amount) + public + pure + override + returns (bool) +{ + revert ErrApprovalsDisabled(); +} + +// TransferFrom BLOCKED +function transferFrom(address from, address to, uint256 amount) + public + pure + override + returns (bool) +{ + revert ErrTransfersDisabled(); +} +``` + +**What this means**: +- โ Cannot send tokens to exchange +- โ Cannot sell tokens on DEX +- โ Cannot transfer tokens to another person directly +- โ Attacker CANNOT steal tokens even from hacked wallet + +### Only Way to Transfer Tokens + +**Only through voting with quorum:** + +```solidity +// Transfer tokens (only through governance) +function _transferTokens(address recipient, uint256 amount) internal { + require(msg.sender == address(this), "Only through governance"); + _transfer(address(this), recipient, amount); +} +``` + +**Transfer process**: +``` +1. Proposal creation + โโโ "Transfer 1000 tokens to address 0xNew..." + โโโ Required: minimum 1 token to create + +2. Voting + โโโ Duration: 1-30 days (configurable) + โโโ Each token = 1 vote + โโโ Required: quorum (e.g., 10% of all tokens) + +3. Quorum check + โโโ If "For" > "Against" AND quorum reached + โโโ โ Proposal approved + +4. Execution + โโโ Smart contract automatically transfers tokens + โโโ Event recorded on blockchain forever +``` + +### Quorum Configuration + +**Quorum is set on deployment** and can only be changed through voting: + +```solidity +uint256 public quorumPercentage; // For example, 10% + +function _hasQuorum(uint256 forVotes, uint256 againstVotes) + internal + view + returns (bool) +{ + uint256 totalVotes = forVotes + againstVotes; + uint256 required = (totalSupply() * quorumPercentage) / 100; + return totalVotes >= required; +} +``` + +**Quorum examples**: +- 5% - easy to reach (for active organizations) +- 10% - standard (recommended) +- 20% - strict (for critical decisions) +- 51% - absolute majority + +### Reentrancy Protection + +```solidity +import "@openzeppelin/contracts/utils/ReentrancyGuard.sol"; + +contract DLE is ReentrancyGuard { + function execute(uint256 proposalId) + external + nonReentrant // Reentrancy protection + { + // Proposal execution + } +} +``` + +### Flash-Loan Protection + +**Vote snapshots** prevent attacks with temporary token loans: + +```solidity +// Votes taken from PREVIOUS block +uint256 public snapshotTimepoint = block.number - 1; + +function vote(uint256 proposalId, bool support) external { + // Use balance from previous block + uint256 votingPower = getPastVotes(msg.sender, snapshotTimepoint); + require(votingPower > 0, "No voting power"); + + // Voting +} +``` + +**Why this is safe**: +1. Attacker takes flash-loan of 1,000,000 tokens +2. Tries to vote +3. Smart contract checks balance in **previous block** +4. In previous block attacker had 0 tokens +5. Voting rejected โ + +### Parameter Validation + +```solidity +// Address check +if (address == address(0)) revert ErrZeroAddress(); + +// Token ownership check +if (balanceOf(msg.sender) == 0) revert ErrNotHolder(); + +// Voting duration check +if (duration < minVotingDuration) revert ErrTooShort(); +if (duration > maxVotingDuration) revert ErrTooLong(); + +// Supported network check +if (!supportedChains[chainId]) revert ErrUnsupportedChain(); +``` + +### Custom Errors for Gas Savings + +```solidity +// Gas savings: custom errors instead of require +error ErrZeroAddress(); +error ErrNotHolder(); +error ErrAlreadyVoted(); +error ErrTransfersDisabled(); +error ErrApprovalsDisabled(); +error ErrProposalMissing(); +error ErrWrongChain(); +``` + +--- + +## Wallet Hack Protection + +### Scenario: Attacker Got Private Key + +**What attacker can do:** + +``` +Attacker attempts: + +1. โ Send tokens to own address + โโโ BLOCKED: transfer() blocked + +2. โ Sell tokens on DEX (Uniswap, etc.) + โโโ BLOCKED: approve() blocked + +3. โ Send via transferFrom + โโโ BLOCKED: transferFrom() blocked + +4. โ Create proposal "Transfer tokens to me" + โโโ Requires voting by other token holders + โโโ Quorum: 10%+ must vote "For" + โโโ MOST LIKELY WILL FAIL +``` + +### Real Attack Example + +``` +Attacker hacked Alice's wallet (500,000 tokens): + +1. Creates proposal: + "Transfer 500,000 tokens to address 0xEvil..." + +2. Votes "For" with own 500,000 votes (50%) + +3. But quorum = 10% = 100,000 votes + Already reached? YES โ + +4. "For" = 500,000 (50%) + "Against" = 0 + +5. Result: Proposal APPROVED โ + +PROBLEM: If Alice has majority of tokens! +``` + +### Protection from Majority Token Attack + +**Solution 1: Timelock Module** + +```solidity +// Delayed execution (e.g., 3 days) +uint256 public constant TIMELOCK_DELAY = 3 days; + +function scheduleProposal(uint256 proposalId) external { + // Proposal approved, but executes only after 3 days + executionTime = block.timestamp + TIMELOCK_DELAY; +} +``` + +**Advantage**: Other token holders see dangerous proposal and can: +- Vote "Against" +- Create counter-proposal +- Take measures (e.g., contact court) + +**Solution 2: Multisignature** + +```solidity +// Requires multiple signatures for critical operations +mapping(uint256 => mapping(address => bool)) public approvals; + +function executeWithApprovals( + uint256 proposalId, + address[] calldata signers, + bytes[] calldata signatures +) external { + // Verify signatures of multiple token holders + require(signers.length >= minSigners, "Not enough signers"); + + for (uint i = 0; i < signers.length; i++) { + // Signature verification + verifySignature(proposalId, signers[i], signatures[i]); + } + + // Execution +} +``` + +**Solution 3: Cold Wallet for Large Holders** + +Recommended to keep tokens on: +- ๐ฅถ **Hardware wallet** (Ledger, Trezor) - maximum protection +- ๐ **Multisignature** (Gnosis Safe) - requires multiple signatures +- โ๏ธ **Cold storage** - offline, not connected to internet + +### Suspicious Proposal Monitoring + +**Backend automatically detects dangerous proposals:** + +```javascript +// Suspicious proposal detector +function detectSuspiciousProposal(proposal) { + const alerts = []; + + // Check 1: Transfer of large token amount + if (proposal.operation.includes('_transferTokens')) { + const amount = decodeAmount(proposal.operation); + const percentage = (amount / totalSupply) * 100; + + if (percentage > 10) { + alerts.push({ + level: 'HIGH', + message: `Proposal transfers ${percentage}% of all tokens!` + }); + } + } + + // Check 2: Initiator votes with own tokens + if (proposal.forVotes === proposal.initiatorBalance) { + alerts.push({ + level: 'MEDIUM', + message: 'Initiator votes only with own tokens' + }); + } + + // Check 3: Fast voting (< 24 hours) + if (proposal.duration < 86400) { + alerts.push({ + level: 'MEDIUM', + message: 'Voting less than 24 hours - little time for verification' + }); + } + + // Send notifications to all token holders + if (alerts.length > 0) { + notifyAllTokenHolders(proposal, alerts); + } +} +``` + +--- + +## Web Application Security + +### SIWE Authentication + +**Sign-In with Ethereum** - standard for secure authentication: + +```javascript +// Generate nonce (one-time) +const nonce = crypto.randomBytes(32).toString('hex'); + +// Save to DB with encryption +await db.query( + 'INSERT INTO nonces (address_encrypted, nonce_encrypted, expires_at) VALUES ($1, $2, $3)', + [encrypt(address), encrypt(nonce), expiresAt] +); + +// Signature verification +const message = new SiweMessage({ + domain: req.get('host'), + address: ethers.getAddress(address), + nonce: nonce, + chainId: 1 +}); + +const isValid = await verifySignature( + message.prepareMessage(), + signature, + address +); +``` + +**Security**: +- โ Private key **never** leaves wallet +- โ Each nonce used **once** +- โ Nonce expires in 5 minutes +- โ Impossible to forge signature without private key + +### Data Encryption + +```javascript +// AES-256 encryption +const crypto = require('crypto'); + +function encrypt(text, key) { + const iv = crypto.randomBytes(16); + const cipher = crypto.createCipheriv('aes-256-cbc', key, iv); + + let encrypted = cipher.update(text, 'utf8', 'hex'); + encrypted += cipher.final('hex'); + + return iv.toString('hex') + ':' + encrypted; +} + +function decrypt(encrypted, key) { + const parts = encrypted.split(':'); + const iv = Buffer.from(parts[0], 'hex'); + const encryptedText = parts[1]; + + const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv); + let decrypted = decipher.update(encryptedText, 'hex', 'utf8'); + decrypted += decipher.final('utf8'); + + return decrypted; +} +``` + +**What is encrypted**: +- ๐ Wallet addresses in DB +- ๐ Nonces for authentication +- ๐ Session data +- ๐ Private messages + +### Rate Limiting + +```javascript +const rateLimit = require('express-rate-limit'); + +// Request limiting +const apiLimiter = rateLimit({ + windowMs: 15 * 60 * 1000, // 15 minutes + max: 100, // maximum 100 requests + message: 'Too many requests, try again later' +}); + +// Authentication limiting (stricter) +const authLimiter = rateLimit({ + windowMs: 15 * 60 * 1000, + max: 5, // maximum 5 authentication attempts + skipSuccessfulRequests: true +}); + +app.use('/api/', apiLimiter); +app.use('/api/auth/', authLimiter); +``` + +### CSRF Protection + +```javascript +const csrf = require('csurf'); + +// CSRF tokens for all forms +const csrfProtection = csrf({ cookie: true }); + +app.post('/api/action', csrfProtection, async (req, res) => { + // CSRF token verification automatic +}); +``` + +### XSS Protection + +```javascript +import DOMPurify from 'dompurify'; + +// Clean HTML from dangerous code +function sanitizeHTML(html) { + return DOMPurify.sanitize(html, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a', 'p'], + ALLOWED_ATTR: ['href'] + }); +} + +// Usage +const userInput = req.body.comment; +const safeHTML = sanitizeHTML(userInput); +``` + +### Helmet.js for Header Protection + +```javascript +const helmet = require('helmet'); + +app.use(helmet({ + contentSecurityPolicy: { + directives: { + defaultSrc: ["'self'"], + scriptSrc: ["'self'", "'unsafe-inline'"], + styleSrc: ["'self'", "'unsafe-inline'"], + imgSrc: ["'self'", "data:", "https:"], + } + }, + hsts: { + maxAge: 31536000, + includeSubDomains: true, + preload: true + } +})); +``` + +### Clean Logs System + +**Automatic log cleanup from sensitive data:** + +```javascript +function cleanLogs() { + const sensitivePatterns = [ + /0x[a-fA-F0-9]{40}/g, // Wallet addresses + /pk_[a-zA-Z0-9]{64}/g, // Private keys (if accidentally logged) + /nonce:\s*[a-f0-9]{64}/gi, // Nonces + ]; + + // Replace sensitive data with *** + let cleanedLog = logContent; + sensitivePatterns.forEach(pattern => { + cleanedLog = cleanedLog.replace(pattern, '[REDACTED]'); + }); + + return cleanedLog; +} +``` + +--- + +## Module Management + +### Only DLE Smart Contract Manages Modules + +**`onlyDLE` modifier** guarantees that only DLE smart contract can call module functions: + +```solidity +// Module: TreasuryModule +contract TreasuryModule { + address public immutable dleContract; + + modifier onlyDLE() { + require(msg.sender == dleContract, "Only DLE can call"); + _; + } + + // Only DLE can transfer tokens from treasury + function transferTokens( + address token, + address recipient, + uint256 amount + ) external onlyDLE { + IERC20(token).transfer(recipient, amount); + } +} +``` + +**What this means**: +- โ Wallet owner **CANNOT** directly call module functions +- โ Backend **CANNOT** call module functions +- โ Attacker **CANNOT** interact with module +- โ **Only** DLE smart contract through voting + +### Module Usage Process + +``` +1. Token holder creates proposal + โโโ "Transfer 1000 USDC from Treasury to marketing" + +2. Proposal contains encoded module function call + โโโ operation = treasuryModule.transferTokens(USDC, marketing, 1000) + +3. Voting + +4. If approved, DLE contract calls module: + โโโ TreasuryModule.transferTokens() โ + โโโ msg.sender = DLE contract โ + +5. Module verifies msg.sender and executes +``` + +### Adding New Module + +**Only through voting:** + +```solidity +// Module addition operation +function _addModule(bytes32 moduleId, address moduleAddress) internal { + require(msg.sender == address(this), "Only through voting"); + require(moduleAddress != address(0), "Invalid address"); + require(!activeModules[moduleId], "Module already exists"); + + modules[moduleId] = moduleAddress; + activeModules[moduleId] = true; + + emit ModuleAdded(moduleId, moduleAddress); +} +``` + +**Process**: +1. Deploy new module +2. Create proposal: "Add module X at address 0x..." +3. Voting +4. If approved โ module added +5. Module can be used + +### Removing Compromised Module + +If module turns out to be vulnerable: + +``` +1. Token holder creates emergency proposal + โโโ "Remove compromised module X" + โโโ Duration: 1 day (emergency voting) + +2. Voting (accelerated) + +3. Module removed + โโโ Can no longer be called from DLE contract +``` + +--- + +## Audit and Monitoring + +### Blockchain Transparency + +**All actions recorded forever:** + +```solidity +// Events for audit +event ProposalCreated(uint256 proposalId, address initiator); +event ProposalVoted(uint256 proposalId, address voter, bool support); +event ProposalExecuted(uint256 proposalId, bytes operation); +event ModuleAdded(bytes32 moduleId, address moduleAddress); +event TokensTransferred(address recipient, uint256 amount); +``` + +**Verification in blockchain explorer:** +``` +https://etherscan.io/address/0xDLE_CONTRACT_ADDRESS +โโโ All transactions publicly visible +โโโ Impossible to hide or delete +``` + +### Real-Time Monitoring + +**Backend tracks all events:** + +```javascript +// Subscribe to smart contract events +dleContract.on('ProposalCreated', async (proposalId, initiator, event) => { + logger.info(`New proposal #${proposalId} from ${initiator}`); + + // Get proposal details + const proposal = await dleContract.proposals(proposalId); + + // Security analysis + const risks = analyzeProposalRisks(proposal); + + // Notify token holders + if (risks.level === 'HIGH') { + await notifyAllTokenHolders({ + type: 'SECURITY_ALERT', + proposalId, + risks + }); + } +}); +``` + +### Alert System + +```javascript +// Critical events require immediate notification +const criticalEvents = [ + 'ProposalCreated', // New proposal + 'ModuleAdded', // Module added + 'TokensTransferred' // Tokens transferred +]; + +async function sendAlert(event, data) { + // Email notifications + await sendEmail({ + to: allTokenHolders, + subject: `[DLE Alert] ${event}`, + body: formatAlert(data) + }); + + // Telegram notifications + await sendTelegram({ + chat: dleNotificationsChat, + message: formatAlert(data) + }); + + // Log entry + logger.warn(`ALERT: ${event}`, data); +} +``` + +--- + +## Security Recommendations + +### For Token Holders + +1. **๐ฅถ Use hardware wallet** (Ledger, Trezor) + - Private key never leaves device + - Confirmation of each operation on physical device + +2. **๐ Store seed phrase securely** + - Write on paper, don't store digitally + - Use metal plates for durability + - Store in safe or bank deposit box + +3. **๐จ Enable notifications** + - Email alerts on new proposals + - Telegram bots for critical events + +4. **๐ Check all proposals** + - Read description before voting + - Verify recipient addresses + - Use timelock for critical operations + +5. **โ๏ธ Split tokens** + - Hot wallet: 10-20% for daily use + - Cold wallet: 80-90% for long-term storage + +### For Administrators + +1. **๐ Regular updates** + ```bash + # Weekly update + docker-compose pull + docker-compose up -d + ``` + +2. **๐พ Backups** + ```bash + # Daily database backup + docker exec dapp-postgres pg_dump -U user db > backup.sql + ``` + +3. **๐ Log monitoring** + ```bash + # Check logs for suspicious activity + docker logs dapp-backend | grep -i "error\|warning\|failed" + ``` + +4. **๐ Encryption key rotation** + - Change encryption key once a year + - Keep old keys for decrypting historical data + +5. **๐ก๏ธ Firewall configuration** + ```bash + # Allow only necessary ports + ufw allow 80/tcp # HTTP + ufw allow 443/tcp # HTTPS + ufw enable + ``` + +### For Developers + +1. **โ Smart contract audits** + - Use Slither for static analysis + - Mythril for vulnerability search + - Manual audit of critical code + +2. **๐งช Testing** + ```bash + # Run tests + cd backend + yarn test + + # Code coverage + yarn coverage + ``` + +3. **๐ Code review** + - All changes through pull requests + - Minimum 2 reviewers for critical changes + +4. **๐ Secure dependencies** + ```bash + # Vulnerability check + yarn audit + npm audit fix + ``` + +--- + +## Attack Scenarios and Protection + +### Scenario 1: Phishing Attack + +**Attack:** +``` +1. Attacker creates fake site: dlle.com (instead of dle.com) +2. Sends phishing emails to token holders +3. Asks to connect wallet and sign transaction +``` + +**Protection:** +```javascript +// Backend verifies domain in SIWE message +const message = new SiweMessage({ + domain: req.get('host'), // Must be correct domain + uri: req.get('origin') +}); + +// Frontend shows warning +if (window.location.hostname !== 'dle.app') { + alert('โ ๏ธ WARNING: This is NOT the official DLE site!'); +} +``` + +**User recommendations:** +- โ Always verify URL before connecting wallet +- โ Use browser bookmarks +- โ Verify SSL certificate (green lock) + +### Scenario 2: Backend Server Hack + +**Attack:** +``` +1. Attacker gains access to backend server +2. Tries to modify code to bypass token verification +3. Or completely takes web application offline +``` + +**Protection:** +``` +โ Token verification happens on blockchain (immutable) +โ Backend can be compromised, but: + โโโ Cannot change token balance in smart contract + โโโ Cannot create fake tokens + โโโ Cannot change smart contract rules + โโโ Users will see discrepancy between backend and blockchain +``` + +**Critical: Web Application is Only an Interface!** + +Even with **complete hack** of web application: +- โ **All business assets protected** on blockchain +- โ **Smart contracts continue to work** independently of web application +- โ **Can manage via blockchain explorers** (Etherscan, Polygonscan, etc.) + +### Management via Blockchain Explorers + +**If web application unavailable, use blockchain explorers:** + +#### 1. Check Token Balance + +``` +1. Open Etherscan: https://etherscan.io +2. Enter DLE smart contract address +3. Go to "Read Contract" tab +4. Call balanceOf(address) function +5. Enter your wallet address +6. Click "Query" - see token balance โ +``` + +**Example**: +``` +Contract Address: 0x1234...DLE +Function: balanceOf +Address: 0xYourWallet... +Result: 500000 (your token balance) +``` + +#### 2. Create Proposal via Etherscan + +``` +1. Open Etherscan and find DLE smart contract +2. Go to "Write Contract" tab +3. Connect MetaMask wallet +4. Find createProposal function +5. Fill parameters: + - description: "Restore web application" + - operation: encoded function call + - votingDuration: 86400 (1 day in seconds) +6. Click "Write" and confirm transaction โ +``` + +**Example proposal creation**: +```solidity +// Via Etherscan Write Contract +createProposal( + "Transfer 10,000 USDT for infrastructure recovery", + 0x..., // encoded transferTokens call + 86400 // 1 day +) +``` + +#### 3. Vote via Etherscan + +``` +1. Open DLE smart contract on Etherscan +2. "Write Contract" tab +3. Connect wallet +4. Function vote(uint256 proposalId, bool support) + - proposalId: proposal number (e.g., 5) + - support: true (for) or false (against) +5. Click "Write" โ +``` + +#### 4. Check Proposal Status + +``` +1. "Read Contract" tab on Etherscan +2. Function proposals(uint256) +3. Enter proposal ID +4. See all details: + - Description + - "For" and "Against" votes + - Status (Active, Executed, Failed) + - Voting end time +``` + +#### 5. Execute Approved Proposal + +``` +1. If proposal approved and time expired +2. Open "Write Contract" +3. Function execute(uint256 proposalId) +4. Enter proposal ID +5. Click "Write" - proposal executes โ +``` + +### Popular Blockchain Explorers for DLE + +| Network | Blockchain Explorer | URL | +|---------|---------------------|-----| +| **Ethereum Mainnet** | Etherscan | https://etherscan.io | +| **Polygon** | Polygonscan | https://polygonscan.com | +| **Binance Smart Chain** | BscScan | https://bscscan.com | +| **Arbitrum** | Arbiscan | https://arbiscan.io | +| **Optimism** | Optimistic Etherscan | https://optimistic.etherscan.io | +| **Avalanche** | SnowTrace | https://snowtrace.io | +| **Base** | BaseScan | https://basescan.org | + +### Advantages of Management via Blockchain Explorers + +**1. Complete independence from web application** +``` +Web application hacked โ Blockchain works โ +Backend server down โ Smart contracts work โ +Frontend unavailable โ Can manage via Etherscan โ +``` + +**2. Impossible to forge data** +``` +Attacker on backend โ Blockchain explorer shows truth +Fake frontend โ Etherscan shows real tokens +Modified logic โ Smart contract works as intended +``` + +**3. Access 24/7 from anywhere in the world** +``` +No server access โ Etherscan always available +Application maintenance โ Management via blockchain +DDoS attack on site โ Blockchain unavailable for DDoS +``` + +**Response to hack:** +1. Users notice strange web application behavior +2. Check token balance directly via Etherscan โ +3. Create proposal via Etherscan for recovery +4. Vote for infrastructure recovery +5. Administrators restore backend from backup +6. **No tokens or assets lost** โ + +**Conclusion**: Web application is just a convenient interface. Real power and assets are on blockchain, where they are protected by cryptography and impossible to change or steal through web application hack. + +### Scenario 3: 51% Attack + +**Attack:** +``` +1. Attacker buys or gets >51% of all tokens +2. Creates proposal "Transfer all assets to me" +3. Votes with all own tokens "For" +4. Proposal approved +``` + +**Protection:** +```javascript +// Timelock Module gives time to react +const TIMELOCK = 7 days; + +// Other token holders can: +1. Vote "Against" (if they still have 49%) +2. Create counter-proposal +3. Contact law enforcement +4. Cancel proposal via emergency function (if configured) +``` + +**Long-term protection:** +- Even token distribution among partners +- Multisignature for large operations +- Quadratic voting (option for future versions) + +### Scenario 4: Social Engineering + +**Attack:** +``` +1. Attacker impersonates DLE support +2. Asks token holder "for verification" to sign message +3. Message is actually approval to transfer tokens +``` + +**Protection:** +```javascript +// Frontend always shows WHAT is being signed +function signMessage(message) { + // Show user exact content + const confirmation = confirm(` + You are about to sign: + ${message} + + โ ๏ธ NEVER sign messages at request of "support"! + + Continue? + `); + + if (!confirmation) return; + + // Sign +} +``` + +**Recommendations:** +- โ Support **NEVER** asks to sign message +- โ Don't trust "urgent" requests +- โ Always verify what you're signing +- โ If in doubt - contact official support + +--- + +## Conclusion + +### Multi-Layer DLE Protection + +``` +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ DLE Security Levels โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ 1๏ธโฃ Blockchain โ +โ โโโ Tokens cannot be stolen even with hack โ +โ โ +โ 2๏ธโฃ Smart Contracts โ +โ โโโ Audit, OpenZeppelin, immutability โ +โ โ +โ 3๏ธโฃ Voting with quorum โ +โ โโโ Impossible to make unilateral decisions โ +โ โ +โ 4๏ธโฃ Timelock โ +โ โโโ Time to react in case of attack โ +โ โ +โ 5๏ธโฃ Backend verification โ +โ โโโ Real-time token verification โ +โ โ +โ 6๏ธโฃ Frontend protection โ +โ โโโ XSS, CSRF, rate limiting โ +โ โ +โ 7๏ธโฃ Monitoring and alerts โ +โ โโโ Detection of suspicious actions โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +``` + +### Key Security Advantages + +1. **๐ Token-based access control** + - Without tokens access impossible + - Real-time verification on blockchain + +2. **๐ก๏ธ Protection from token theft** + - Cannot transfer without voting + - Even if wallet hacked, tokens protected + +3. **๐ Independence from web application** + - Even if web application hacked, business assets protected on blockchain + - Can manage via blockchain explorers (Etherscan, Polygonscan, etc.) + - Smart contracts work independently of frontend/backend + - Web application is only convenient interface, real power on blockchain + +4. **โ๏ธ Collective governance** + - Critical decisions only through voting + - Quorum prevents unilateral actions + +5. **๐ Modules under smart contract control** + - Only DLE contract can call modules + - No direct access + +6. **๐ Full transparency** + - All actions on blockchain + - Impossible to hide or forge + +### Next Steps + +1. ๐ [Study technical documentation](./blockchain-integration-technical.md) +2. ๐ง [Set up secure environment](./setup-instruction.md) +3. ๐ [Read FAQ](./FAQ.md) +4. ๐ฌ [Get support](https://hb3-accelerator.com/) +--- + +**ยฉ 2024-2025 Tarabanov Alexander Viktorovich. All rights reserved.** + +**Last update**: October 2025 + diff --git a/docs-en/service-terms.md b/docs-en/service-terms.md new file mode 100644 index 0000000..dd9f44b --- /dev/null +++ b/docs-en/service-terms.md @@ -0,0 +1,43 @@ + + +# Digital Legal Entity Purchase and Service Terms โ Brief Summary + +> Important: This is a brief summary of terms. The canonical and legally binding full text is located here: [legal-en/service-terms.md](../legal-en/service-terms.md). + +Key Points: +- License Type: Perpetual, rights determined by number of tokens (1 or 10). +- Updates and Basic Maintenance: Free for 5 years from on-chain token transfer date. +- Development Voting: 1 token = 1 vote, decisions by majority โฅ51%. +- 70% Refund possible if program conditions are met (see original). +- Support, releases, knowledge base โ through application `https://hb3-accelerator.com/`. +- Full list of limitations/liability โ in original. + +## ๐ Additional Documentation + +### Explore DLE Capabilities +- ๐ค **[AI Assistant](./ai-assistant.md)** - second pilot for team, frees time for strategy +- ๐ผ **[Blockchain for Business](./blockchain-for-business.md)** - asset tokenization and business solutions +- ๐ก๏ธ **[DLE Security](./security.md)** - multi-level protection for your business + +### Technical Documentation +- ๐ **[Blockchain Technical Documentation](./blockchain-integration-technical.md)** - for developers +- ๐ง **[Installation Instructions](./setup-instruction.md)** - step-by-step setup +- ๐ **[Application Description](./application-description.md)** - functionality overview +- ๐ **[FAQ](./FAQ.md)** - frequently asked questions + +### Contacts and Support +- ๐ง **Email**: info@hb3-accelerator.com +- ๐ **Website**: https://hb3-accelerator.com +- ๐ฌ **Support Chat**: https://hb3-accelerator.com/ +- ๐ **GitHub**: https://github.com/VC-HB3-Accelerator + diff --git a/docs-en/setup-ai-assistant.md b/docs-en/setup-ai-assistant.md new file mode 100644 index 0000000..6a25c9f --- /dev/null +++ b/docs-en/setup-ai-assistant.md @@ -0,0 +1,929 @@ +# AI Assistant Setup Guide with Vector Search + +## ๐ค Complete Guide to Launching an Intelligent Assistant + +This document describes the step-by-step process of setting up an AI assistant for solving business tasks through spreadsheets and vector search. + +--- + +## ๐ What You'll Set Up + +After completing the instructions, you will have: + +โ Working AI assistant with local model (Ollama) +โ Knowledge base for customer responses (FAQ) +โ Supplier work automation +โ Employee training system +โ Vector search on your data +โ Significant time and resource savings + +> ๐ก **Economic Impact**: See [AI Assistant](./ai-assistant.md) - detailed description of all capabilities and savings calculations. + +--- + +## โฑ๏ธ Setup Time + +- **Quick Setup**: 20-30 minutes (basic FAQ) +- **Full Setup**: 1-2 hours (all capabilities) + +--- + +## Step 1: Installing and Running Ollama + +### 1.1 Checking Ollama Status + +1. Go to **Settings** โ **Integrations** tab +2. Find the **"Ollama"** block and click **"Details"** +3. Check connection status: + - โ **"Ollama is running"** โ ready, proceed to step 1.3 + - โ **"Ollama API not responding"** โ proceed to step 1.2 + +### 1.2 Starting Ollama (if not running) + +If Ollama is not running, execute in terminal: + +```bash +# For Docker (recommended) +docker-compose up -d ollama + +# Or locally +ollama serve +``` + +Refresh the page and check status again. + +### 1.3 Installing AI Model + +1. In the **Ollama** section, click **"Install Model"** +2. Select model: + - **qwen2.5:7b** (recommended) โ for Russian, 4.7 GB + - **llama2:7b** โ for English, 3.8 GB + - **mistral:7b** โ universal, 4.1 GB +3. Click **"Install"** +4. Wait for download to complete (5-10 minutes depending on internet speed) + +> ๐ก **Tip**: Model downloads once and is stored locally + +### 1.4 Installing Embedding Model + +1. In the same section, find **"Install Embedding Model"** +2. Select model: + - **mxbai-embed-large:latest** (recommended) โ 670 MB + - **nomic-embed-text:latest** โ alternative, 274 MB +3. Click **"Install"** + +> โ ๏ธ **Important**: Embedding model is needed for vector search (RAG) + +--- + +## Step 2: Creating Knowledge Base (Spreadsheets) + +### 2.1 Creating FAQ Table + +1. Go to **Tables** (in main menu) +2. Click **"+ Create Table"** +3. Fill in: + - **Name**: `FAQ - Frequently Asked Questions` + - **Description**: `Knowledge base for AI assistant customer service` +4. Click **"Create"** + +### 2.2 Configuring Table Columns + +Add the following columns: + +#### Column 1: Question (required for RAG) + +1. Click **"+ Add Column"** +2. Fill in: + - **Name**: `Question` + - **Type**: `Text` + - **Purpose**: Select `Question for AI` โญ +3. Click **"Save"** + +> โ ๏ธ **Critical**: Must select purpose "Question for AI" โ this field will be indexed for vector search + +#### Column 2: Answer (required for RAG) + +1. Click **"+ Add Column"** +2. Fill in: + - **Name**: `Answer` + - **Type**: `Text` + - **Purpose**: Select `AI Answer` โญ +3. Click **"Save"** + +#### Column 3: Product (optional, for filtering) + +1. Click **"+ Add Column"** +2. Fill in: + - **Name**: `Product` + - **Type**: `Multiple Choice` + - **Options**: `Basic`, `Premium`, `Corporate` + - **Purpose**: Select `Product Filter` +3. Click **"Save"** + +#### Column 4: Tags (optional, for categorization) + +1. Click **"+ Add Column"** +2. Fill in: + - **Name**: `Tags` + - **Type**: `Multiple Choice` + - **Options**: `Payment`, `Delivery`, `Return`, `Warranty`, `Support` + - **Purpose**: Select `User Tags` +3. Click **"Save"** + +#### Column 5: Priority (optional) + +1. Click **"+ Add Column"** +2. Fill in: + - **Name**: `Priority` + - **Type**: `Number` + - **Purpose**: Select `Priority` +3. Click **"Save"** + +> ๐ก **Tip**: Questions with higher priority will be shown to AI first + +### 2.3 Filling Knowledge Base + +Add typical questions and answers: + +**Example 1: Payment** + +| Question | Answer | Product | Tags | Priority | +|----------|--------|---------|------|----------| +| How to pay for order? | We accept payment by bank card, PayPal, or bank transfer. Choose convenient method when placing order. | All | Payment | 10 | +| Can I pay in installments? | Yes, for orders from 50,000โฝ installment plan available for 3, 6 or 12 months without overpayment. | Premium, Corporate | Payment | 8 | + +**Example 2: Delivery** + +| Question | Answer | Product | Tags | Priority | +|----------|--------|---------|------|----------| +| How long does delivery take? | Standard delivery: 3-5 business days in Russia. Express delivery: 1-2 days in major cities. | All | Delivery | 10 | +| How much does delivery cost? | Free delivery for orders from 5,000โฝ. For orders less than 5,000โฝ delivery cost is 300โฝ. | All | Delivery | 9 | + +**Example 3: Return** + +| Question | Answer | Product | Tags | Priority | +|----------|--------|---------|------|----------| +| How to return product? | Return possible within 14 days from receipt. Product must be in original packaging, with preserved appearance. Contact support to process return. | All | Return | 10 | +| When will money be returned? | Refund processed within 5-10 business days after product received at our warehouse. | All | Return | 8 | + +> ๐ก **Recommendation**: Add minimum 20-30 questions for quality AI work. More questions = more accurate answers! + +### 2.4 Activating Table as AI Source + +1. In top right corner of table, find **โ๏ธ Table Settings** +2. Enable toggle **"Use as AI Source"** โ +3. Click **"Save"** + +> โ **Done!** Table is now indexed for vector search + +--- + +## Step 3: Configuring AI Provider (Ollama) + +### 3.1 Opening Ollama Settings + +1. Go to **Settings** โ **Integrations** +2. Find **"Ollama"** block and click **"Details"** + +### 3.2 Checking Base URL + +1. Check **Base URL** field: + - For Docker: `http://ollama:11434` โ + - For local: `http://localhost:11434` +2. If URL is incorrect, fix and click **"Save"** + +### 3.3 Selecting Model + +1. In **"Model (LLM)"** field, select installed model: + - `qwen2.5:7b` (recommended for Russian) +2. In **"Embeddings Model"** field, select: + - `mxbai-embed-large:latest` +3. Click **"Save"** + +--- + +## Step 4: Configuring AI Assistant + +### 4.1 Opening Assistant Settings + +1. Go to **Settings** โ **Integrations** +2. Find **"AI Assistant"** block and click **"Details"** + +### 4.2 Configuring System Prompt + +In **"System Prompt"** field, enter instructions for AI: + +**Basic Prompt (to start)**: + +``` +You are a professional customer support assistant. + +Rules: +1. Answer politely and professionally +2. Use information from knowledge base +3. If information not available โ suggest contacting operator +4. Answer briefly and to the point +5. Always end with question "How else can I help?" +``` + +**Advanced Prompt (with personalization)**: + +``` +You are a professional customer support assistant for "Your Company Name". + +About company: +- We are engaged in [brief business description] +- Our values: quality, reliability, customer focus + +Communication style: +- Friendly but professional +- Address customer as "You" +- Use emojis moderately (1-2 per message) + +Response rules: +1. MANDATORY: Answer ONLY in Russian. All questions and answers must be in Russian +2. First search answer in knowledge base (RAG) +3. If found โ answer based on found information +4. If not found โ honestly say and suggest operator help +5. Don't make up information about prices, terms, conditions +6. For complex questions suggest contacting manager + +Always end with: "How else can I help? ๐" +``` + +### 4.3 Selecting Models + +1. **LLM Model**: Select `qwen2.5:7b (ollama)` +2. **Embedding Model**: Select `mxbai-embed-large:latest (ollama)` + +> ๐ก **Tip**: Models automatically pulled from Ollama settings + +> ๐ **Context Window Size**: +> - **Qwen2.5:7b**: Base context = **32,768 tokens** (~24,000 Russian words) +> - Total data sent to model: +> - System prompt: ~500-2000 characters (~300-1200 tokens) +> - Conversation history: up to 20 messages (~100-500 tokens per message = ~2000-10000 tokens) +> - RAG context: ~500-2000 tokens (from found data) +> - Current question: ~50-200 tokens +> - **Total**: approximately 3,000-15,000 tokens (sufficient reserve) +> - If larger context needed โ use Qwen3 with YaRN (up to 131K tokens) + +### 4.4 Selecting RAG Table + +1. In **"Selected RAG Tables"** field, select created table: + - `FAQ - Frequently Asked Questions` +2. Click **"Save"** + +### 4.5 Configuring AI Rules + +Create rule set for managing AI behavior: + +1. Click **"Create"** button next to "Rule Set" field +2. In modal window, fill in: + +**Name**: `Hybrid Mode (RAG + Generation)` + +**Description**: `AI first searches knowledge base, if not found โ generates answer` + +**Rules (JSON)**: +```json +{ + "checkUserTags": true, + "searchRagFirst": true, + "generateIfNoRag": true, + "temperature": 0.7, + "maxTokens": 500 +} +``` + +3. Click **"Save"** +4. Select created rule in dropdown + +> ๐ก **What parameters mean**: +> - `checkUserTags: true` โ consider user tags when searching +> - `searchRagFirst: true` โ first search knowledge base +> - `generateIfNoRag: true` โ generate answer if nothing found +> - `temperature: 0.7` โ balance between accuracy and creativity (0.0-1.0) +> - `maxTokens: 500` โ maximum answer length + +### 4.6 RAG Search Settings + +Expand **"๐ RAG Search Settings"** section: + +**Basic Settings:** +1. **Search Method**: Select `Hybrid Search` (recommended) +2. **Maximum Results**: `5` +3. **Relevance Threshold**: `0.1` (from 0.01 to 1.0) + +**Keyword Extraction:** +1. โ **Enable Keyword Extraction** +2. **Minimum Word Length**: `3` +3. **Maximum Keywords**: `10` +4. โ **Remove Stop Words** + +**Search Weights (for hybrid):** +1. **Semantic Search**: `70%` (accuracy) +2. **Keyword Search**: `30%` (speed) + +**Additional Settings:** +1. โ **Fuzzy Search** (for typos) +2. โ **Word Stemming** (finds different word forms) +3. โ **Synonym Search** (currently disabled) + +### 4.7 Saving Settings + +Click **"Save"** button at bottom of form. + +--- + +## Step 5: Testing AI Assistant + +### 5.1 Using Built-in Tester + +1. On AI assistant settings page, scroll down to **"๐ System Monitoring"** block +2. In **"๐ง RAG Functionality Test"** section: + - Ensure table `FAQ - Frequently Asked Questions` is selected + - Enter test question: `How to pay for order?` + - Click **"Test RAG"** +3. Observe process: + - ๐ Searching answer in knowledge base... (vector search) + - ๐ค Generating answer with AI... (LLM generation) + - โ Done! +4. Check result: + - Answer from your table should be displayed + - Score (similarity score): closer to 0 is better + +> ๐ก **Good Score**: from -300 to 0 (answer found) +> โ ๏ธ **Bad Score**: greater than 300 (answer not found, AI will make up its own) + +### 5.2 Testing via Web Chat + +1. Go to application main page +2. Find **"๐ฌ Chat with AI"** widget (usually bottom right) +3. Click widget to open chat +4. Enter question: `How much does delivery cost?` +5. Check AI response + +**Expected Result:** +``` +๐ค AI Assistant: +Free delivery for orders from 5,000โฝ. +For orders less than 5,000โฝ delivery cost is 300โฝ. + +How else can I help? ๐ +``` + +### 5.3 Testing Different Scenarios + +Try asking various questions: + +**โ Question from knowledge base:** +``` +User: "How to return product?" +AI: [Answer from FAQ table] +``` + +**โ ๏ธ Question NOT from knowledge base:** +``` +User: "What's the weather today?" +AI: "Sorry, I specialize in questions about our company and products. + For weather questions, please contact specialized services. + How else can I help?" +``` + +**๐ฏ Question with typo:** +``` +User: "How to pay for order?" (typo) +AI: [Will find correct answer thanks to fuzzy search] +``` + +--- + +## Step 6: Advanced Capabilities (Optional) + +### 6.1 Creating Supplier Table + +#### "Supplier Database" Table Structure + +1. Create new table: `Supplier Database` +2. Add columns: + +| Column | Type | Description | +|--------|------|-------------| +| Company Name | Text | Supplier name | +| Product Category | Multiple Choice | Electronics, Furniture, Clothing, etc. | +| Contact Person | Text | Manager name | +| Email | Text | Email address | +| Phone | Text | Contact phone | +| Prices | Text | Price list (brief description) | +| Payment Terms | Text | Deferred payment, prepayment, etc. | +| Minimum Order | Number | Minimum order amount | +| Delivery Time | Text | Delivery terms | +| Rating | Number | Rating from 1 to 10 | +| Notes | Text | Additional information | + +3. Activate as AI source +4. Fill with your supplier data + +#### Prompt for AI Purchaser + +Add to system prompt: + +``` +ADDITIONALLY - Working with Suppliers: + +When user asks about suppliers: +1. Search in "Supplier Database" base +2. Filter by product category +3. Sort by rating and terms +4. Provide TOP-3 recommendations + +Response format: +๐ TOP-3 suppliers for "[category]": + +1. [Name] โญ [Rating]/10 + ๐ง [Email] | ๐ [Phone] + ๐ฐ Terms: [Payment Terms] + ๐ Delivery: [Delivery Time] + ๐ฆ Minimum: [Minimum Order]โฝ + +2. ... +3. ... + +I recommend contacting [First Supplier Name] โ best terms. +``` + +### 6.2 Creating Employee Training Table + +#### "Employee Knowledge Base" Table Structure + +1. Create new table: `Employee Knowledge Base` +2. Add columns: + +| Column | Type | Description | +|--------|------|-------------| +| Question | Text | Employee question (purpose: Question for AI) | +| Answer | Text | Detailed answer (purpose: AI Answer) | +| Category | Multiple Choice | Sales, HR, Finance, IT, Marketing | +| Department | Multiple Choice | Which department it's relevant for | +| Difficulty | Number | From 1 (simple) to 5 (complex) | +| Instructions | Text | Step-by-step instructions (if any) | +| Links | Text | Links to documents/videos | +| Update Date | Date | When information was updated | + +3. Example questions: + +**"Sales" Category:** +- "How to process customer return?" +- "What discounts can be given to regular customers?" +- "How to work with corporate customers?" + +**"HR" Category:** +- "How to apply for vacation?" +- "Where to contact for sick leave?" +- "How does new employee onboarding work?" + +**"IT" Category:** +- "How to get access to corporate email?" +- "What to do with VPN problems?" +- "How to create support ticket?" + +### 6.3 Creating Table Relationships + +#### Example: "Customers" โ "Orders" Relationship + +1. Create **"Customers"** table: + - Name, Email, Phone, Status (VIP/Regular) + +2. Create **"Orders"** table: + - Order Number, Date, Amount + +3. In "Orders" table, add column: + - **Name**: `Customer` + - **Type**: `Relation` + - **Related Table**: select `Customers` + - **Display Field**: select `Name` + +4. Add another column in "Orders": + - **Name**: `Customer Email` + - **Type**: `Lookup` + - **Relation Through**: select `Customer` column + - **Lookup Field**: select `Email` + +**Result**: When selecting customer, their Email is automatically filled! + +#### Using AI with Related Tables + +AI automatically understands relationships and can answer questions: + +``` +User: "Show all orders for customer Ivanov" +AI: [Searches Orders table, filters by customer Ivanov] +``` + +--- + +## Step 7: Telegram and Email Integration (Optional) + +### 7.1 Setting Up Telegram Bot + +1. Go to **Settings** โ **Integrations** โ **Telegram** +2. Create bot via [@BotFather](https://t.me/botfather) in Telegram: + - Send `/newbot` + - Choose bot name and username + - Copy **Bot Token** +3. In DLE settings, enter: + - **Bot Token**: paste token from BotFather + - **Bot Username**: your bot username (e.g., `@mycompany_bot`) +4. Click **"Save"** +5. In AI assistant settings, select this Telegram bot in **"Telegram Bot"** field + +**Result**: AI will respond to Telegram messages! + +### 7.2 Setting Up Email Integration + +1. Go to **Settings** โ **Integrations** โ **Email** +2. Fill IMAP settings (for receiving emails): + - **IMAP Host**: `imap.gmail.com` (for Gmail) + - **IMAP Port**: `993` + - **IMAP User**: your email + - **IMAP Password**: app password (not main password!) +3. Fill SMTP settings (for sending emails): + - **SMTP Host**: `smtp.gmail.com` + - **SMTP Port**: `587` + - **SMTP User**: your email + - **SMTP Password**: app password + - **From Email**: email for sending +4. Click **"Test IMAP"** and **"Test SMTP"** to verify +5. Click **"Save"** +6. In AI assistant settings, select this Email in **"Email Contact"** field + +> โ ๏ธ **Important for Gmail**: Create "App Password" in Google security settings + +**Result**: AI will automatically respond to incoming emails! + +--- + +## Step 8: Monitoring and Optimization + +### 8.1 Checking Service Status + +1. Go to **Settings** โ **Integrations** โ **AI Assistant** +2. Scroll down to **"๐ System Monitoring"** +3. Click **"๐ Refresh Status"** +4. Check statuses: + - ๐ข **Backend**: should be "Running" + - ๐ข **Postgres**: should be "Running" + - ๐ข **Ollama**: should show number of models + - ๐ข **Vector Search**: should be "Running" + +> โ ๏ธ If something is red (๐ด) โ see "Troubleshooting" section below + +### 8.2 Analyzing Answer Quality + +Regularly check AI answer quality: + +1. **Score in RAG Tester**: + - **-300 to 0** โ โ excellent match + - **0 to 300** โ ๏ธ โ average match + - **>300** โ โ match not found + +2. **If Score is Bad**: + - Add more similar questions to table + - Use different phrasings of same question + - Increase relevance threshold (e.g., to 0.2) + +### 8.3 Optimizing RAG Settings + +Experiment with settings to improve results: + +**For More Accurate Answers:** +``` +Search Method: Semantic +Relevance Threshold: 0.05 (lower = stricter) +Weights: Semantic 100% / Keywords 0% +``` + +**For Faster Answers:** +``` +Search Method: Keyword Search +Maximum Results: 3 +``` + +**For Balance (Recommended):** +``` +Search Method: Hybrid +Weights: Semantic 70% / Keywords 30% +Relevance Threshold: 0.1 +``` + +--- + +## โ AI Assistant Ready to Work! + +### What You Now Have + +โ **Local AI Assistant** without cloud dependency +โ **FAQ Knowledge Base** for customer responses +โ **Vector Search** for accurate answers +โ **Configured Rules** for AI behavior +โ **Monitoring System** for quality control + +### Economic Impact + +With proper AI assistant setup, you will get: + +โ **Task Automation** - freeing time for strategy +โ **Improved Service Quality** - AI works 24/7 without fatigue +โ **Reduced Operating Costs** - less staff on routine tasks +โ **Faster Decision Making** - instant access to information + +> ๐ก **Detailed Information**: See [AI Assistant - Complete Description](./ai-assistant.md#economic-impact) - detailed description of all capabilities, use cases, and savings calculations. + +--- + +## ๐ Next Steps + +### Expand AI Capabilities + +1. **Add More Tables**: + - Partner knowledge base + - Employee instructions + - Product catalog + - Contact database + +2. **Create Rules for Different Scenarios**: + - Strict mode (RAG only) โ for finance + - Creative mode (more generation) โ for marketing + - Hybrid mode (balance) โ for support + +3. **Integrate with Other Systems**: + - CRM (customer synchronization) + - Warehouse system (inventory) + - Accounting (invoices and payments) + +### Train Your Team + +1. Show employees how AI works +2. Explain how to add new questions to base +3. Establish regular knowledge base update process +4. Assign responsible person for AI answer quality + +--- + +## ๐ Troubleshooting + +### Problem: Ollama Not Starting + +**Symptoms**: Status "Ollama API not responding" + +**Solution**: +```bash +# Check container +docker ps | grep ollama + +# Restart +docker-compose restart ollama + +# Check logs +docker-compose logs ollama +``` + +### Problem: AI Answers Inaccurately + +**Symptoms**: Answers don't match knowledge base + +**Solution**: +1. Check Score in tester (should be < 300) +2. Add more question variations to table +3. Decrease relevance threshold (e.g., to 0.05) +4. Check that columns have correct purposes ("Question for AI", "AI Answer") + +### Problem: Vector Search Not Working + +**Symptoms**: Vector Search status shows error + +**Solution**: +1. Check if Embedding model is installed +2. Rebuild index: on table page click **"๐ Rebuild Index"** +3. Check that table is activated as AI source + +### Problem: AI Answers in Wrong Language + +**Symptoms**: Answers in English instead of Russian + +**Solution**: +1. Change system prompt, adding at start: `ALWAYS answer in Russian.` +2. Use `qwen2.5:7b` model instead of `llama2:7b` +3. In AI rules, set `"language": "ru"` + +### Problem: Slow Responses + +**Symptoms**: AI responds longer than 5-10 seconds + +**Solution**: +1. Use smaller model (`mistral:7b` instead of `qwen2.5:14b`) +2. Decrease `maxResults` in RAG settings (e.g., to 3) +3. Disable "Synonym Search" in additional settings +4. Use SSD for storing models + +--- + +## ๐ Additional Documentation + +### Learn AI Capabilities + +- ๐ค **[AI Assistant - Complete Description](./ai-assistant.md)** - all capabilities and use cases +- ๐ **[Spreadsheet System](./tables-system.md)** - technical description of tables (temporary) +- โ๏ธ **[AI Configuration](./setup-ai-assistant.md#technical-documentation-for-developers)** - technical setup details + +### General Documentation + +- ๐ก๏ธ **[Security](./security.md)** - how AI protects your data +- ๐ผ **[Blockchain for Business](./blockchain-for-business.md)** - AI integration with blockchain +- ๐ **[FAQ](./FAQ.md)** - frequently asked questions + +### Support + +- ๐ฌ **Support Chat**: https://hb3-accelerator.com/ +- ๐ง **Email**: info@hb3-accelerator.com +- ๐ **Knowledge Base**: https://hb3-accelerator.com + +--- + +## ๐ง Technical Documentation (for Developers) + +### AI System Architecture + +``` +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ AI Assistant Configuration in DLE โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ โ +โ ๐ค AI Providers: โ +โ โโโ OpenAI (GPT-4, GPT-3.5) โ +โ โโโ Anthropic (Claude) โ +โ โโโ Google (Gemini) โ +โ โโโ Ollama (local models) โ +โ โ +โ โ๏ธ AI Settings: โ +โ โโโ System Prompt โ +โ โโโ LLM Model Selection โ +โ โโโ Embedding Model Selection โ +โ โโโ RAG Table Selection โ +โ โโโ Rules โ +โ โโโ RAG Search Settings โ +โ โ +โ ๐ Rules: โ +โ โโโ JSON behavior configuration โ +โ โโโ Create/edit/delete โ +โ โโโ Link to AI assistant โ +โ โ +โ ๐ Integrations: โ +โ โโโ Email (IMAP + SMTP) โ +โ โโโ Telegram Bot โ +โ โ +โ ๐ RAG: โ +โ โโโ Table selection for search โ +โ โโโ Search settings (hybrid/semantic) โ +โ โโโ Relevance threshold โ +โ โโโ Keyword extraction โ +โ โ +โ ๐ Monitoring: โ +โ โโโ Service status (Backend, Ollama, Postgres) โ +โ โโโ RAG functionality test โ +โ โโโ Progress tracking โ +โ โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +``` + +### Database + +#### Table: `ai_providers_settings` + +```sql +CREATE TABLE IF NOT EXISTS ai_providers_settings ( + id SERIAL PRIMARY KEY, + provider_encrypted TEXT, -- Provider: openai, anthropic, google, ollama + api_key_encrypted TEXT, -- API key (encrypted) + base_url_encrypted TEXT, -- Base URL for API + selected_model_encrypted TEXT, -- Selected LLM model + embedding_model_encrypted TEXT, -- Selected Embedding model + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP NOT NULL DEFAULT NOW() +); +``` + +#### Table: `ai_assistant_settings` + +```sql +CREATE TABLE IF NOT EXISTS ai_assistant_settings ( + id SERIAL PRIMARY KEY, + system_prompt_encrypted TEXT, -- System prompt + selected_rag_tables INTEGER[], -- Array of RAG table IDs + languages TEXT[], -- Array of supported languages + model_encrypted TEXT, -- Selected LLM model + embedding_model_encrypted TEXT, -- Selected Embedding model + rules JSONB, -- Rules (DEPRECATED) + rules_id INTEGER REFERENCES ai_assistant_rules(id), -- Rule reference + telegram_settings_id INTEGER, -- Telegram bot reference + email_settings_id INTEGER, -- Email settings reference + rag_settings JSONB, -- RAG search settings + updated_at TIMESTAMP DEFAULT NOW(), + updated_by INTEGER +); +``` + +#### Table: `ai_assistant_rules` + +```sql +CREATE TABLE IF NOT EXISTS ai_assistant_rules ( + id SERIAL PRIMARY KEY, + name TEXT NOT NULL, -- Rule set name + description TEXT, -- Rule description + rules JSONB NOT NULL, -- JSON configuration + rules_encrypted TEXT, -- Encrypted version of rules + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW() +); +``` + +### Backend API + +#### AI Provider Settings + +- **GET** `/settings/ai-settings/:provider` โ Get provider settings +- **PUT** `/settings/ai-settings/:provider` โ Save provider settings +- **DELETE** `/settings/ai-settings/:provider` โ Delete provider settings +- **GET** `/settings/ai-settings/:provider/models` โ Get model list +- **POST** `/settings/ai-settings/:provider/verify` โ Verify API key + +#### AI Assistant Settings + +- **GET** `/settings/ai-assistant` โ Get assistant settings +- **PUT** `/settings/ai-assistant` โ Save assistant settings + +#### AI Rules + +- **GET** `/settings/ai-assistant-rules` โ Get all rules +- **GET** `/settings/ai-assistant-rules/:id` โ Get rule by ID +- **POST** `/settings/ai-assistant-rules` โ Create rule +- **PUT** `/settings/ai-assistant-rules/:id` โ Update rule +- **DELETE** `/settings/ai-assistant-rules/:id` โ Delete rule + +#### Ollama (Local Models) + +- **GET** `/ollama/status` โ Check Ollama status +- **GET** `/ollama/models` โ Get model list +- **POST** `/ollama/install` โ Install model +- **DELETE** `/ollama/models/:modelName` โ Delete model + +### Frontend Pages + +- **`/settings/ai`** โ Main integrations page +- **`/settings/ai/:provider`** โ AI provider settings +- **`/settings/ai/assistant`** โ AI assistant settings + +### Message Processing Flow + +``` +1. User โ Message + โ +2. UnifiedMessageProcessor + โ +3. Language Check (Russian only) + โ +4. Deduplication (message hash) + โ +5. Load Settings (aiAssistantSettingsService) + โ +6. Load Rules (aiAssistantRulesService) + โ +7. RAG Search (ragService) + โโโ Semantic Search (vector search) + โโโ Keyword Search + โโโ Hybrid Search + โ +8. Generate Answer (generateLLMResponse) + โโโ System Prompt + โโโ Conversation History + โโโ RAG Context + โโโ Rules + โ +9. Answer โ User +``` + +### Security + +- **Encryption**: All sensitive fields encrypted with AES-256 +- **Access Rights**: Only administrators can change settings +- **Validation**: All input data and API keys validated + +--- + +**ยฉ 2024-2025 Tarabanov Alexander Viktorovich. All rights reserved.** + +**Document Version**: 1.0.0 +**Creation Date**: October 25, 2025 + diff --git a/docs-en/setup-instruction.md b/docs-en/setup-instruction.md new file mode 100644 index 0000000..e856e4f --- /dev/null +++ b/docs-en/setup-instruction.md @@ -0,0 +1,196 @@ + + +# Digital Legal Entity Application Setup Instructions + +## ๐ Complete System Initialization Process + +This document describes the complete process of preparing the application for work with blockchain support, smart contracts, and access management system. + +--- + +## Step 1: Software Installation + +1. Clone the project repository to your local device +2. Run the application via Docker Compose or locally depending on configuration +3. Open the web application in browser: `http://localhost:9000` (production) or `http://localhost:5173` (dev mode) + +--- + +## Step 2: Crypto Wallet Connection + +1. Make sure you have a browser wallet installed (MetaMask, WalletConnect, or similar) +2. In the wallet, create or import an account with governance token +3. In the web application, click the **"Connect Wallet"** button +4. Select wallet type and confirm connection +5. After successful connection, you will see your account address in the top corner + +--- + +## Step 3: Adding RPC Providers (Security โ RPC Providers) + +1. Go to **Settings** โ **Security** tab +2. Find the **"RPC Providers"** section +3. Click the **"Add"** button +4. Fill out the form for each blockchain network you want to use: + - **Network Name** (e.g.: Ethereum, Polygon, BSC) + - **RPC URL** (connection link, example: `https://eth-mainnet.g.alchemy.com/v2/YOUR-API-KEY`) + - **Network ID** (Chain ID) +5. Click **"Save"** for each provider +6. The system will automatically verify connection correctness + +> โ ๏ธ **Important**: Get API keys from providers (Alchemy, Infura, Quicknode, etc.) before adding + +--- + +## Step 4: Multi-Deploy Smart Contract Setup + +1. Go to **Settings** โ **Blockchain** tab +2. Fill out the form +3. Click **"Launch Deploy"** + +--- + +## Step 5: Deploy Completion and Contract Address Saving + +1. Wait for deploy completion (depends on network, usually 30-120 seconds) +2. After successful completion, the **"Contract Management"** page will open +3. **Copy the deployed contract address** (usually looks like: `0x742d35Cc6634C0532925a3b844Bc...`) + +--- + +## Step 6: Smart Contract Authentication Setup + +1. Return to **Settings** โ **Authentication** tab +2. In the **"Smart Contract Address"** field, paste the address copied in step 5 +3. Set thresholds for access management: + - **Minimum number of tokens for editing** (e.g.: 100 tokens) + - **Minimum number of tokens for viewing** (e.g.: 1 token) + +--- + +## Step 7: AI and Database Setup + +1. Go to **Settings** โ **AI** tab +2. Open the **"Database"** subsection +3. Replace default passwords +4. Click **"Generate New Encryption Key"** + - The system will automatically create a cryptographic key + - **Save the key in a secure place** (it will be needed for data recovery) + +--- + +## Step 8: Internet Access Setup (Optional) + +**If you need access to the web application from outside via internet:** + +1. Go to **Settings** โ **Server** tab +2. On the **Server** page, select **WEB SSH** or another suitable service +3. Fill out the form to migrate local application to a virtual device with: + - **Public IP address** + - **Connection to your domain name** +4. Click **"Publish"** +5. Wait for migration process completion + +> โน๏ธ **Note**: This step requires having a registered domain name and access to DNS settings + +--- + +## Step 9: Legal Documents Setup for Personal Data Processing + +### 9.1 Filling Company Legal Information + +1. Go to **CRM** โ **Content** section +2. Find and open the **"Company Legal Information"** form +3. Fill in all necessary fields: + - **Full Organization Name** (legal name) + - **Short Name** + - **Legal Form** (LLC, sole proprietor, JSC, etc.) + - **Legal Address** + - **Actual Address** (if different) + - **INN / OGRN / KPP** (registration data) + - **Contact Information** (phone, email, website) + - **Responsible Person for Personal Data Processing** (Full Name, position) + - **Applicable Jurisdiction** (GDPR, CCPA, Russian legislation, etc.) +4. Click **"Save"** + +> ๐ก **Hint**: All entered data will automatically be inserted into all legal document templates + +### 9.2 Working with Document Templates + +1. In the **Content** section, go to the **"Templates"** subsection +2. Select necessary document templates required by regulators: + - **Privacy Policy** + - **User Agreement** + - **Personal Data Processing Consent** + - **Cookie Usage Policy** +3. For each template: + - Click **"Preview"** to check automatically filled data + - Edit specific data processing parameters if necessary + - Select action: + - **"Publish for Public Use"** โ document will be available on the site + - **"Publish for Internal Use"** โ document available only within CRM + - **"Print"** โ export to PDF for printing or signing +4. Confirm publication +5. The system will automatically add documents to corresponding application pages + +> โ ๏ธ **Important**: It is recommended to consult with a lawyer before publishing documents to ensure full compliance with legal requirements + +--- + +## โ Application Ready to Work! + +After completing all steps, your application is fully configured and ready to use. + +**Next Steps:** +- ๐ AI Assistant Setup (see document: `setup-ai-assistant.md`) +- ๐ Smart Contract Management (see document: `manage-smart-contracts.md`) + +--- + +## ๐ Security Recommendations + +โ Keep contract addresses and encryption keys in a secure place +โ Use strong passwords for DB +โ Regularly create configuration backups +โ Never share wallet private keys +โ Use HTTPS for application access in production + +--- + +## ๐ What's Next? + +After completing basic setup, you can: +1. Add users and manage their permissions +2. Create groups for collaboration +3. Configure AI assistant for task automation +4. Manage smart contracts to extend functionality +5. Integrate external services and bots + +--- + +## ๐ Additional Documentation + +### Explore DLE Capabilities +- ๐ค **[AI Assistant](./ai-assistant.md)** - learn how AI can become a second pilot for your team +- ๐ผ **[Blockchain for Business](./blockchain-for-business.md)** - how asset tokenization solves business tasks +- ๐ก๏ธ **[Security](./security.md)** - multi-level protection for your business + +### Technical Information +- ๐ **[Blockchain Technical Documentation](./blockchain-integration-technical.md)** - for developers +- ๐ **[FAQ](./FAQ.md)** - frequently asked questions +- ๐ **[Application Description](./application-description.md)** - functionality overview + +### Support +- ๐ฌ **Support Chat**: https://hb3-accelerator.com/ +- ๐ง **Email**: info@hb3-accelerator.com + diff --git a/docs-en/system-messages-management.md b/docs-en/system-messages-management.md new file mode 100644 index 0000000..6e07486 --- /dev/null +++ b/docs-en/system-messages-management.md @@ -0,0 +1,132 @@ +# Technical Specification: System Messages Management + +## 1. Goal and Context +- Provide managed display of system messages on the main page (`/`, component `HomeView.vue`) and add an administrative interface for their creation and moderation in the content section (`/content`, component `ContentListView.vue`). +- System messages must support "draft" and "published" statuses, be stored in the database, and be accessible via REST API. + +## 2. Current State +- The main page is built by component `HomeView.vue` and displays the assistant chat (`ChatInterface.vue`), in which system messages (`Message.vue`) are highlighted by the `message.role === 'system'` attribute. +- The content section (`ContentListView.vue`) contains navigation cards: "Create Page", "Templates", "Public", "Settings", "Internal". Cards lead to existing routes `content-create`, `content-templates`, `content-published`, `content-settings`, `content-internal`. +- The project lacks entities and API for system messages; current `pagesService.js` works only with pages (`/pages`). + +## 3. New User Scenarios +- **Viewing System Messages (main page, `/`):** + - Published system messages are loaded into the assistant chat and displayed as collapsed cards with clickable headers. + - When clicking the header, the message expands: the chat feed displays the full message text **or** sends a pre-prepared response from the AI assistant (the "response" content is stored with the message and selected by the `reply_type` flag). + - Messages must be explicitly marked as system (color, icon). When reopened, the user sees the last expansion state; local "read" memory is possible. +- **"System Messages" Section (`/content`):** + - On the `/content` page, a new "System Messages" card appears with a "Details" button. Navigation leads to a page with a user table (`/content/system-messages/table`), built on existing table components (see `UserTablesList.vue`), without a separate dashboard of cards. + - The table displays system messages row by row, with multiple selection via checkboxes; available bulk actions: publish, unpublish, move to drafts, delete. + - For each message, clicking "Details" (within the row) opens view/edit with a form (see below). +- **Create/Edit (`/content/system-messages/create`, `/content/system-messages/:id/edit`):** + - Form with fields: title, brief description, main text (Markdown/HTML), response type (`inline` โ show content, `assistant_reply` โ send prepared assistant response), "Assistant Reply" field (active when `assistant_reply`), importance tag (info/warning/danger), publication start date (optional), end date (optional), flag for guest display. + - Buttons: "Save as Draft", "Publish". When editing โ "Update", "Unpublish", "Delete". + - Validations: title and main text required (or assistant reply in corresponding mode); date validation (end โฅ start). +- **Working with System Messages Table:** + - Columns: selection checkbox, title (clickable), status, response type, active period, target audience (guests/authenticated/all), creation date, author. + - Bulk actions are performed for selected rows; single actions available via context menu/buttons in row (edit, publish, unpublish, delete). + +## 4. Interface Requirements +- In `ContentListView.vue`, add "System Messages" card to the `management-blocks` grid with a `Details` button. The card design should match existing blocks (header, description, button). +- System messages table page: + - Use `BaseLayout` and local styles (`scoped`). + - Table supports sorting, filtering by status, and search by title. + - Checkboxes in header and rows for bulk selection; action panel appears when selection exists. + - "Create Message" button opens creation form. +- Create/Edit Form: + - Rich-text (minimum Markdown) with preview and character/word counters. + - Display mode toggle (`inline`/`assistant_reply`) with conditional display of "Assistant Reply" field (can use ``). + - Field for icon/color selection by `severity` (static presets). +- Main Page: + - System messages are displayed in the chat block as collapsed cards (`system-message-collapsed`). Clicking the header expands the card (`system-message-expanded`) or initiates assistant sending (UI shows "message from assistant"). + - For expanded messages, provide "Collapse" button and (optionally) "Mark as Read". Store state in `localStorage`. + +## 5. Routing and Components +- Add routes in `router/index.js`: +- - `/content/system-messages/table` โ `SystemMessagesTableView.vue` +- - `/content/system-messages/create` โ `SystemMessageCreateView.vue` +- - `/content/system-messages/:id` โ `SystemMessageDetailsView.vue` (view) +- - `/content/system-messages/:id/edit` โ `SystemMessageEditView.vue` +- If needed for modal/nested routes, child routes or named views can be used. +- Create corresponding Vue components in `src/views/content/system-messages/` and a common set of reusable elements (table, form, filters, bulk actions) in `src/components/system-messages/`. +- Create service `src/services/systemMessagesService.js` with methods for the new API. + +## 6. API and Data Requirements +- **New Table** `system_messages` (PostgreSQL): + - `id` (uuid, pk) + - `title` (text, not null) + - `summary` (text, nullable) + - `content` (text, not null) + - `reply_type` (enum: inline, assistant_reply; default inline) + - `assistant_reply_content` (text, nullable; required when `reply_type = assistant_reply`) + - `severity` (enum: info, warning, danger; default info) + - `status` (enum: draft, published; not null) + - `visible_for` (enum: all, authenticated, guests; default all) + - `publish_at` (timestamp, nullable) + - `expire_at` (timestamp, nullable) + - `created_at`, `updated_at` + - `created_by`, `updated_by` (references users/identities, nullable) + - `slug` (text, unique, for addressing by link if needed) +- **REST API (Express):** + - `GET /system-messages` (pagination, filters by status, search) + - `GET /system-messages/published` (filtering by date/audience; public) + - `GET /system-messages/:id` (access only for authorized editors) + - `POST /system-messages` (creation; `MANAGE_LEGAL_DOCS` permission) + - `PATCH /system-messages/:id` (editing; status checks) + - `DELETE /system-messages/:id` (soft delete or physical) + - `POST /system-messages/:id/publish` and `POST /system-messages/:id/unpublish` (optional, if not using PATCH) +- All protected endpoints must require authorization and permissions (see `permissions.js`, `usePermissions`). +- Add new migration (`backend/scripts/run-migrations.js`) and ORM/SQL files in the project's existing format. +- Update logging and error handling `winston`, add input validation (e.g., `Joi` or custom). + +## 7. Frontend Display Logic +- `HomeView.vue`: + - On initialization, request published system messages (considering current audience) via `systemMessagesService.getPublished({ includeExpired: false })`. + - Cache response in store or local state; when subscribing to WebSocket, can provide `system_message_updated` event. + - Add expansion handler: on header click, either substitute full message text (`inline`), or initiate sending `assistant_reply_content` to chat (without user participation). + - Add message hiding handler, saving identifier in `localStorage` and filtering locally. +- `ContentListView.vue`: + - Add new "System Messages" card to the `management-blocks` grid, without breaking the adaptive grid (update `grid-template-columns` if needed). +- List Pages: + - Implement pagination (lazy loading or regular), sorting by date. + - For statuses, use color badges (info/warning/danger). +- Creation Form: + - Support submit via `yarn lint`-friendly code; client-side validation (e.g., using `computed`/`watch`). + - On successful publication, redirect to published list; when saving draft โ stay on page with notification. + +## 8. Security and Access Requirements +- Creation/editing scenarios available only to roles with `PERMISSIONS.MANAGE_LEGAL_DOCS`. +- Public list (`GET /system-messages/published`) filters by: + - `status === 'published'`. + - `publish_at <= now()` (or null). + - `expire_at > now()` (or null). + - `visible_for` is checked based on context (guest/authenticated). +- When issuing through chat, hide fields `created_by`, `updated_by`, internal tags. +- Consider CSRF, CORS, rate-limit (adopt config from existing routes). + +## 9. Testing +- **Backend:** + - Unit tests for CRUD in `tests/system-messages/*.test.js` (Mocha). + - Check publish/expire filters and role-based access. + - Test migration (rollback/apply). +- **Frontend:** + - Vue unit tests (if configured) for main components (form, list). + - E2E (if available) โ scenario: create draft โ publish โ display on main page. +- **Regression Checks:** + - Ensure existing content list and assistant chat continue to work without errors (`yarn lint`, `yarn test`). + +## 10. Integration and DevOps +- Update `docker-compose.yml` if needed (e.g., add migrations to startup process). +- Ensure new environment variables (if any, e.g., message count limits) are documented in `README.md` and `setup-instruction.md`. +- Add seeding script (optional) for test system messages. + +## 11. Open Questions +- Is publication history (auditing) needed? If yes โ provide `system_messages_history` table. +- Is multilingual support required? (If absent โ limit to one language, EN). +- Is WebSocket notification needed when new messages appear? (If yes โ add event to `wsHub.js`). + +## 12. Final Artifacts +- Backend: new routes, controllers, service, migration. +- Frontend: new pages and service, updated routes and components `HomeView`, `ContentListView`. +- Documentation: update `README.md` (launch section), `application-description.md` or `tables-system.md` when schemas change, this specification. + diff --git a/docs-en/tables-system.md b/docs-en/tables-system.md new file mode 100644 index 0000000..f64dbda --- /dev/null +++ b/docs-en/tables-system.md @@ -0,0 +1,1639 @@ +# Electronic Tables System in DLE + +> **Temporary document for internal analysis** + +--- + +## ๐ Table of Contents + +1. [System Overview](#system-overview) +2. [Database Architecture](#database-architecture) +3. [Field Types](#field-types) +4. [Functional Capabilities](#functional-capabilities) +5. [Relations Between Tables](#relations-between-tables) +6. [AI Integration (RAG)](#ai-integration-rag) +7. [API Reference](#api-reference) +8. [Usage Examples](#usage-examples) +9. [Security](#security) + +--- + +## System Overview + +### What is it? + +The electronic tables system in DLE is a **full-featured database with graphical interface**, similar to **Notion Database** or **Airtable**, built into the application. + +### Key Features + +``` +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ DLE Electronic Tables โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ โ +โ โ 6 field types (text, number, relation, lookup, etc.)โ +โ โ Relations between tables (1:1, 1:N, N:N) โ +โ โ Lookup and data substitution โ +โ โ Filtering and sorting โ +โ โ Real-time updates (WebSocket) โ +โ โ AI integration (RAG for search) โ +โ โ Encryption of all data (AES-256) โ +โ โ Placeholders for API access โ +โ โ Cascading deletion โ +โ โ Bulk operations โ +โ โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +``` + +### Differences from Excel/Google Sheets + +| Feature | Excel/Sheets | DLE Tables | +|---------|--------------|------------| +| **Data typing** | Weak | Strict (6 types) | +| **Relations between tables** | No | Yes (relation, lookup) | +| **AI search** | No | Yes (RAG, vector search) | +| **Real-time updates** | Partial | Full (WebSocket) | +| **Encryption** | No | AES-256 for all data | +| **API access** | Limited | Full REST API | +| **Access rights** | Basic | Detailed (by roles) | + +--- + +## Database Architecture + +### Table Schema (PostgreSQL) + +```sql +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ user_tables โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ id SERIAL PRIMARY KEY โ +โ name_encrypted TEXT NOT NULL โ +โ description_encrypted TEXT โ +โ is_rag_source_id INTEGER (link to is_rag_source) โ +โ created_at TIMESTAMP โ +โ updated_at TIMESTAMP โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ + โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ user_columns โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ id SERIAL PRIMARY KEY โ +โ table_id INTEGER โ user_tables(id) โ +โ name_encrypted TEXT NOT NULL โ +โ type_encrypted TEXT NOT NULL โ +โ placeholder_encrypted TEXT (for API) โ +โ placeholder TEXT (unencrypted) โ +โ options JSONB (settings) โ +โ order INTEGER (display order) โ +โ created_at TIMESTAMP โ +โ updated_at TIMESTAMP โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ + โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ user_rows โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ id SERIAL PRIMARY KEY โ +โ table_id INTEGER โ user_tables(id) โ +โ order INTEGER (row order) โ +โ created_at TIMESTAMP โ +โ updated_at TIMESTAMP โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ + โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ user_cell_values โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ id SERIAL PRIMARY KEY โ +โ row_id INTEGER โ user_rows(id) โ +โ column_id INTEGER โ user_columns(id) โ +โ value_encrypted TEXT (encrypted value) โ +โ created_at TIMESTAMP โ +โ updated_at TIMESTAMP โ +โ UNIQUE(row_id, column_id) โ One cell = one value โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ + โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ user_table_relations โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค +โ id SERIAL PRIMARY KEY โ +โ from_row_id INTEGER โ user_rows(id) โ +โ column_id INTEGER โ user_columns(id) โ +โ to_table_id INTEGER โ user_tables(id) โ +โ to_row_id INTEGER โ user_rows(id) โ +โ created_at TIMESTAMP โ +โ updated_at TIMESTAMP โ +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +``` + +### Cascading Deletion + +``` +Table deletion (user_tables) + โ + โโโ Deletes all columns (user_columns) + โโโ Deletes all rows (user_rows) + โ โโโ Deletes all cell values (user_cell_values) + โโโ Deletes all relations (user_table_relations) +``` + +**Important**: Uses `ON DELETE CASCADE` for automatic cleanup. + +### Indexes for Performance + +```sql +-- Indexes on relations (user_table_relations) +CREATE INDEX idx_user_table_relations_from_row ON user_table_relations(from_row_id); +CREATE INDEX idx_user_table_relations_column ON user_table_relations(column_id); +CREATE INDEX idx_user_table_relations_to_table ON user_table_relations(to_table_id); +CREATE INDEX idx_user_table_relations_to_row ON user_table_relations(to_row_id); +``` + +**Effect**: Fast filtering and search by related tables. + +--- + +## Field Types + +### 1. Text + +**Description**: Regular text field + +```json +{ + "type": "text", + "options": null +} +``` + +**Usage**: +- Names +- Descriptions +- Email +- URL +- Any text + +### 2. Number + +**Description**: Numeric field + +```json +{ + "type": "number", + "options": null +} +``` + +**Usage**: +- Prices +- Quantities +- Ratings +- Percentages + +### 3. Multiselect + +**Description**: Multiple value selection from list + +```json +{ + "type": "multiselect", + "options": { + "choices": ["Option 1", "Option 2", "Option 3"] + } +} +``` + +**Usage**: +- Tags +- Categories +- Statuses +- Skills + +### 4. Multiselect-Relation + +**Description**: Multiple row selection from another table + +```json +{ + "type": "multiselect-relation", + "options": { + "relatedTableId": 5, + "relatedColumnId": 12 + } +} +``` + +**Usage**: +- Relation Contacts โ Tags (N:N) +- Relation Tasks โ Assignees (N:N) +- Relation Products โ Categories (N:N) + +**Storage**: In `user_table_relations` table, multiple records created: +``` +from_row_id=100, column_id=3, to_table_id=5, to_row_id=20 +from_row_id=100, column_id=3, to_table_id=5, to_row_id=21 +from_row_id=100, column_id=3, to_table_id=5, to_row_id=22 +``` + +### 5. Relation + +**Description**: Relation with one row from another table (1:1 or 1:N) + +```json +{ + "type": "relation", + "options": { + "relatedTableId": 3, + "relatedColumnId": 8 + } +} +``` + +**Usage**: +- Task โ Project (N:1) +- Contact โ Company (N:1) +- Order โ Client (N:1) + +**Storage**: In `user_table_relations`, one record created: +``` +from_row_id=50, column_id=2, to_table_id=3, to_row_id=15 +``` + +### 6. Lookup + +**Description**: Automatic value substitution from related table + +```json +{ + "type": "lookup", + "options": { + "relatedTableId": 4, + "relatedColumnId": 10, + "lookupColumnId": 11 // Which field to substitute + } +} +``` + +**Example**: +``` +Table "Orders" +โโโ order_id (text) +โโโ product (relation โ Products) +โโโ product_price (lookup โ Products.price) + +When you select product, price is automatically substituted! +``` + +**Usage**: +- Prices from catalog +- Email from contacts +- Statuses from related tasks + +--- + +## Functional Capabilities + +### 1. CRUD Operations + +#### Create Table + +```javascript +// Frontend +await tablesService.createTable({ + name: "Contacts", + description: "Customer database", + isRagSourceId: 2 // Source for AI +}); + +// Backend: POST /tables +// Encrypts name and description with AES-256 +``` + +#### Add Column + +```javascript +await tablesService.addColumn(tableId, { + name: "Email", + type: "text", + order: 2, + purpose: "contact" // For special fields +}); + +// Backend: POST /tables/:id/columns +// Generates unique placeholder: "email", "email_1", ... +``` + +#### Add Row + +```javascript +await tablesService.addRow(tableId); + +// Backend: POST /tables/:id/rows +// Automatically indexes in vector store for AI +``` + +#### Update Cell (Upsert) + +```javascript +await tablesService.saveCell({ + row_id: 123, + column_id: 5, + value: "new@email.com" +}); + +// Backend: POST /tables/cell +// INSERT ... ON CONFLICT ... DO UPDATE +// Automatically updates vector store +``` + +#### Delete Row + +```javascript +await tablesService.deleteRow(rowId); + +// Backend: DELETE /tables/row/:rowId +// Rebuilds vector store (rebuild) +``` + +#### Delete Column + +```javascript +await tablesService.deleteColumn(columnId); + +// Backend: DELETE /tables/column/:columnId +// Cascading deletion: +// 1. All relations (user_table_relations) +// 2. All cell values (user_cell_values) +// 3. Column itself +``` + +#### Delete Table + +```javascript +await tablesService.deleteTable(tableId); + +// Backend: DELETE /tables/:id +// Required: req.session.userAccessLevel?.hasAccess +// Cascading deletion of all related data +``` + +### 2. Data Filtering + +#### By Product + +```javascript +GET /tables/5/rows?product=Premium + +// Backend filters rows: +filtered = rows.filter(r => r.product === 'Premium'); +``` + +#### By Tags + +```javascript +GET /tables/5/rows?tags=VIP,B2B + +// Backend filters rows with any of tags: +filtered = rows.filter(r => + r.userTags.includes('VIP') || r.userTags.includes('B2B') +); +``` + +#### By Relations + +```javascript +GET /tables/5/rows?relation_12=45,46 + +// Filter rows related to to_row_id = 45 or 46 +// through column column_id = 12 +``` + +#### By Multiselect + +```javascript +GET /tables/5/rows?multiselect_8=10,11,12 + +// All selected values must be present +``` + +### 3. Placeholder System + +**Automatic generation**: + +```javascript +// Function: generatePlaceholder(name, existingPlaceholders) + +"Customer Name" โ "customer_name" +"Email" โ "email" +"Email" (2nd time) โ "email_1" +"123" โ "column" (fallback) +"Price-$" โ "price" +``` + +**Transliteration**: +```javascript +const cyrillicToLatinMap = { + ะฐ: 'a', ะฑ: 'b', ะฒ: 'v', ะณ: 'g', ะด: 'd', + ะต: 'e', ั: 'e', ะถ: 'zh', ะท: 'z', ะธ: 'i', + // ... full map +}; +``` + +**Usage**: +```javascript +// API access to data via placeholder +GET /tables/5/data?fields=email,phone,customer_name +``` + +### 4. Row Order + +```javascript +// Change row order (drag-n-drop) +await tablesService.updateRowsOrder(tableId, [ + { rowId: 100, order: 0 }, + { rowId: 101, order: 1 }, + { rowId: 102, order: 2 } +]); + +// Backend: PATCH /tables/:id/rows/order +// Updates "order" field for each row +``` + +### 5. Real-Time Updates (WebSocket) + +```javascript +// Backend sends notifications on changes +broadcastTableUpdate(tableId); // Table update +broadcastTableRelationsUpdate(); // Relations update +broadcastTagsUpdate(null, rowId); // Tags update + +// Frontend subscribes to events +socket.on('table-update', (data) => { + if (data.tableId === currentTableId) { + reloadTableData(); + } +}); +``` + +### 6. Bulk Operations + +```javascript +// Select multiple rows (checkbox) +const selectedRows = [100, 101, 102]; + +// Bulk deletion +for (const rowId of selectedRows) { + await tablesService.deleteRow(rowId); +} + +// After deletion: automatic rebuild vector store +``` + +--- + +## Relations Between Tables + +### Relation Types + +#### 1. One-to-Many (N:1) - Relation + +**Example**: Tasks โ Projects + +``` +Table "Tasks" Table "Projects" +โโโ task_1 โ project_id=5 โโโ project_5 (Website) +โโโ task_2 โ project_id=5 โโโ project_6 (API) +โโโ task_3 โ project_id=6 +``` + +**Storage**: +```sql +user_table_relations +โโโ from_row_id=task_1, column_id=3, to_table_id=2, to_row_id=project_5 +โโโ from_row_id=task_2, column_id=3, to_table_id=2, to_row_id=project_5 +โโโ from_row_id=task_3, column_id=3, to_table_id=2, to_row_id=project_6 +``` + +#### 2. Many-to-Many (N:N) - Multiselect-Relation + +**Example**: Contacts โ Tags + +``` +Table "Contacts" Table "Tags" +โโโ contact_1 โ [VIP, B2B] โโโ tag_1 (VIP) +โโโ contact_2 โ [VIP] โโโ tag_2 (B2B) +โโโ contact_3 โ [B2B, Local] โโโ tag_3 (Local) +``` + +**Storage**: +```sql +user_table_relations +โโโ from_row_id=contact_1, column_id=5, to_table_id=3, to_row_id=tag_1 +โโโ from_row_id=contact_1, column_id=5, to_table_id=3, to_row_id=tag_2 +โโโ from_row_id=contact_2, column_id=5, to_table_id=3, to_row_id=tag_1 +โโโ from_row_id=contact_3, column_id=5, to_table_id=3, to_row_id=tag_2 +โโโ from_row_id=contact_3, column_id=5, to_table_id=3, to_row_id=tag_3 +``` + +#### 3. Lookup (Substitution) + +**Example**: Orders โ Product Price + +``` +Table "Orders" +โโโ order_id (text) +โโโ product (relation โ Products) +โโโ price (lookup โ Products.price) + +Table "Products" +โโโ product_name (text) +โโโ price (number) +``` + +**How it works**: +1. Select `product = "Laptop"` (relation to product) +2. `price` automatically substituted from `Products.price` +3. If product price changes, lookup updates + +### API for Working with Relations + +```javascript +// Get all row relations +GET /tables/:tableId/row/:rowId/relations + +// Add relation +POST /tables/:tableId/row/:rowId/relations +Body: { + column_id: 12, + to_table_id: 5, + to_row_id: 45 +} + +// Add multiple relations (multiselect) +POST /tables/:tableId/row/:rowId/relations +Body: { + column_id: 12, + to_table_id: 5, + to_row_ids: [45, 46, 47] +} + +// Delete relation +DELETE /tables/:tableId/row/:rowId/relations/:relationId +``` + +--- + +## AI Integration (RAG) + +### Vector Search + +Tables are used as **knowledge base for AI assistant**. + +#### Automatic Indexing + +**On row creation/modification**: + +```javascript +// Backend: POST /tables/:id/rows +const rows = await getTableRows(tableId); +const upsertRows = rows + .filter(r => r.row_id && r.text) + .map(r => ({ + row_id: r.row_id, + text: r.text, // Question (question column) + metadata: { + answer: r.answer, // Answer (answer column) + product: r.product, // Product filter + userTags: r.userTags, // Tags filter + priority: r.priority // Priority + } + })); + +if (upsertRows.length > 0) { + await vectorSearchClient.upsert(tableId, upsertRows); +} +``` + +**On row deletion**: + +```javascript +// Backend: DELETE /tables/row/:rowId +const rows = await getTableRows(tableId); +const rebuildRows = /* ... */; + +if (rebuildRows.length > 0) { + await vectorSearchClient.rebuild(tableId, rebuildRows); +} +``` + +#### Special Fields for RAG + +```javascript +// Columns with purpose +{ + "type": "text", + "options": { + "purpose": "question" // Question for AI + } +} + +{ + "type": "text", + "options": { + "purpose": "answer" // AI Answer + } +} + +{ + "type": "multiselect", + "options": { + "purpose": "product" // Product filter + } +} + +{ + "type": "multiselect", + "options": { + "purpose": "userTags" // Tags filter + } +} +``` + +#### Manual Index Rebuild + +```javascript +// Frontend (admins only) +await tablesService.rebuildIndex(tableId); + +// Backend: POST /tables/:id/rebuild-index +// Required: req.session.userAccessLevel?.hasAccess +const { questionCol, answerCol } = await getQuestionAnswerColumnIds(tableId); +const rows = await getRowsWithQA(tableId, questionCol, answerCol); + +if (rows.length > 0) { + await vectorSearchClient.rebuild(tableId, rows); +} +``` + +#### How AI Uses Tables + +``` +1. User asks AI question: + "How to return product?" + +2. AI does vector search: + vectorSearch.search(tableId, query, top_k=3) + +3. Finds similar questions in table: + - row_id: 123 + - text: "How to process product return?" + - score: -250 (close to threshold 300) + - metadata: { answer: "Return within 14 days..." } + +4. AI returns answer from metadata.answer + +5. If not found (score > 300): + AI generates answer via LLM (Ollama) +``` + +#### Filtering by Products and Tags + +```javascript +// Search only by product "Premium" +const results = await vectorSearch.search(tableId, query, 3); +const filtered = results.filter(r => r.metadata.product === 'Premium'); + +// Search only by tags "VIP" or "B2B" +const filtered = results.filter(r => + r.metadata.userTags.includes('VIP') || + r.metadata.userTags.includes('B2B') +); +``` + +--- + +## API Reference + +### Tables + +#### GET /tables + +Get list of all tables + +**Response**: +```json +[ + { + "id": 1, + "name": "Contacts", + "description": "Customer database", + "is_rag_source_id": 2, + "created_at": "2025-01-15T10:00:00Z", + "updated_at": "2025-01-15T10:00:00Z" + } +] +``` + +#### POST /tables + +Create new table + +**Request**: +```json +{ + "name": "Contacts", + "description": "Customer database", + "isRagSourceId": 2 +} +``` + +**Response**: Created table object + +#### GET /tables/:id + +Get table structure and data + +**Response**: +```json +{ + "name": "Contacts", + "description": "Customer database", + "columns": [ + { + "id": 1, + "table_id": 1, + "name": "Email", + "type": "text", + "placeholder": "email", + "options": null, + "order": 0 + } + ], + "rows": [ + { + "id": 100, + "table_id": 1, + "order": 0, + "created_at": "2025-01-15T10:00:00Z" + } + ], + "cellValues": [ + { + "id": 500, + "row_id": 100, + "column_id": 1, + "value": "user@example.com" + } + ] +} +``` + +#### PATCH /tables/:id + +Update table metadata + +**Request**: +```json +{ + "name": "Customers", + "description": "Updated description" +} +``` + +#### DELETE /tables/:id + +Delete table (admins only) + +**Requirements**: `req.session.userAccessLevel?.hasAccess === true` + +### Columns + +#### POST /tables/:id/columns + +Add column + +**Request**: +```json +{ + "name": "Email", + "type": "text", + "order": 2, + "purpose": "contact" +} +``` + +#### PATCH /tables/column/:columnId + +Update column + +**Request**: +```json +{ + "name": "New name", + "type": "text", + "order": 5 +} +``` + +#### DELETE /tables/column/:columnId + +Delete column (cascading deletion of all values) + +### Rows + +#### POST /tables/:id/rows + +Add row + +**Response**: Created row object + +#### DELETE /tables/row/:rowId + +Delete row + +#### PATCH /tables/:id/rows/order + +Change row order + +**Request**: +```json +{ + "order": [ + { "rowId": 100, "order": 0 }, + { "rowId": 101, "order": 1 } + ] +} +``` + +### Cells + +#### POST /tables/cell + +Create or update cell value (upsert) + +**Request**: +```json +{ + "row_id": 100, + "column_id": 5, + "value": "new@email.com" +} +``` + +**Logic**: +```sql +INSERT INTO user_cell_values (row_id, column_id, value_encrypted) +VALUES ($1, $2, encrypt_text($3, $4)) +ON CONFLICT (row_id, column_id) +DO UPDATE SET value_encrypted = encrypt_text($3, $4), updated_at = NOW() +``` + +### Filtering + +#### GET /tables/:id/rows + +Get filtered rows + +**Parameters**: +``` +?product=Premium // Filter by product +&tags=VIP,B2B // Filter by tags +&relation_12=45,46 // Filter by relation (column_id=12) +&multiselect_8=10,11 // Filter by multiselect (column_id=8) +&lookup_15=100 // Filter by lookup (column_id=15) +``` + +### RAG Index + +#### POST /tables/:id/rebuild-index + +Rebuild vector index (admins only) + +**Requirements**: `req.session.userAccessLevel?.hasAccess === true` + +**Response**: +```json +{ + "success": true, + "count": 150 +} +``` + +### Relations + +#### GET /tables/:tableId/row/:rowId/relations + +Get all row relations + +**Response**: +```json +[ + { + "id": 1000, + "from_row_id": 100, + "column_id": 12, + "to_table_id": 5, + "to_row_id": 45 + } +] +``` + +#### POST /tables/:tableId/row/:rowId/relations + +Add relation or relations + +**Single relation**: +```json +{ + "column_id": 12, + "to_table_id": 5, + "to_row_id": 45 +} +``` + +**Multiple relations** (multiselect): +```json +{ + "column_id": 12, + "to_table_id": 5, + "to_row_ids": [45, 46, 47] +} +``` + +**Logic**: +- Deletes old relations for column_id +- Adds new relations + +#### DELETE /tables/:tableId/row/:rowId/relations/:relationId + +Delete relation + +### Placeholders + +#### GET /tables/:id/placeholders + +Get placeholders for table columns + +**Response**: +```json +[ + { + "id": 1, + "name": "Email", + "placeholder": "email" + }, + { + "id": 2, + "name": "Customer Name", + "placeholder": "customer_name" + } +] +``` + +#### GET /tables/placeholders/all + +Get all placeholders across all tables + +**Response**: +```json +[ + { + "column_id": 1, + "column_name": "Email", + "placeholder": "email", + "table_id": 1, + "table_name": "Contacts" + } +] +``` + +--- + +## Usage Examples + +### Example 1: FAQ Knowledge Base for AI + +#### Create Table + +```javascript +const table = await tablesService.createTable({ + name: "FAQ", + description: "Frequently asked questions for AI", + isRagSourceId: 2 // RAG source +}); +``` + +#### Add Columns + +```javascript +// Question (for vector search) +await tablesService.addColumn(table.id, { + name: "Question", + type: "text", + order: 0, + purpose: "question" +}); + +// Answer (for AI) +await tablesService.addColumn(table.id, { + name: "Answer", + type: "text", + order: 1, + purpose: "answer" +}); + +// Product (for filtering) +await tablesService.addColumn(table.id, { + name: "Product", + type: "multiselect", + order: 2, + purpose: "product", + options: { + choices: ["Basic", "Premium", "Enterprise"] + } +}); + +// Tags (for filtering) +await tablesService.addColumn(table.id, { + name: "Tags", + type: "multiselect", + order: 3, + purpose: "userTags", + options: { + choices: ["Payment", "Delivery", "Return", "Warranty"] + } +}); +``` + +#### Add Data + +```javascript +// Add row +const row = await tablesService.addRow(table.id); + +// Fill cells +await tablesService.saveCell({ + row_id: row.id, + column_id: 1, // Question + value: "How to return product?" +}); + +await tablesService.saveCell({ + row_id: row.id, + column_id: 2, // Answer + value: "Product return is possible within 14 days of purchase..." +}); + +// Automatically indexed in vector store! +``` + +#### Search via AI + +```javascript +// User asks AI +const userQuestion = "can I return my purchase?"; + +// AI does vector search +const results = await vectorSearch.search(table.id, userQuestion, 3); + +// Finds similar question "How to return product?" (score: -200) +// Returns answer from metadata.answer +``` + +### Example 2: CRM System + +#### Structure + +```javascript +// Table "Companies" +const companies = await tablesService.createTable({ + name: "Companies", + description: "Company database" +}); + +await tablesService.addColumn(companies.id, { + name: "Name", + type: "text", + order: 0 +}); + +await tablesService.addColumn(companies.id, { + name: "Website", + type: "text", + order: 1 +}); + +await tablesService.addColumn(companies.id, { + name: "Industry", + type: "multiselect", + order: 2, + options: { choices: ["IT", "Finance", "Retail", "Manufacturing"] } +}); + +// Table "Contacts" +const contacts = await tablesService.createTable({ + name: "Contacts", + description: "Contact database" +}); + +await tablesService.addColumn(contacts.id, { + name: "Name", + type: "text", + order: 0 +}); + +await tablesService.addColumn(contacts.id, { + name: "Email", + type: "text", + order: 1 +}); + +// Relation: Contact โ Company +await tablesService.addColumn(contacts.id, { + name: "Company", + type: "relation", + order: 2, + options: { + relatedTableId: companies.id, + relatedColumnId: 1 // Company name + } +}); + +// Lookup: Company Website +await tablesService.addColumn(contacts.id, { + name: "Company Website", + type: "lookup", + order: 3, + options: { + relatedTableId: companies.id, + relatedColumnId: 2, // Relation through "Company" + lookupColumnId: 2 // Substitute "Website" + } +}); +``` + +#### Usage + +```javascript +// Add company +const company = await tablesService.addRow(companies.id); +await tablesService.saveCell({ + row_id: company.id, + column_id: 1, + value: "Microsoft" +}); +await tablesService.saveCell({ + row_id: company.id, + column_id: 2, + value: "https://microsoft.com" +}); + +// Add contact +const contact = await tablesService.addRow(contacts.id); +await tablesService.saveCell({ + row_id: contact.id, + column_id: 1, + value: "John Doe" +}); + +// Link contact to company +await api.post(`/tables/${contacts.id}/row/${contact.id}/relations`, { + column_id: 3, // "Company" + to_table_id: companies.id, + to_row_id: company.id +}); + +// Lookup automatically substitutes "https://microsoft.com"! +``` + +### Example 3: Task Management + +#### Structure + +```javascript +// Table "Projects" +const projects = await tablesService.createTable({ + name: "Projects", + description: "Active projects" +}); + +await tablesService.addColumn(projects.id, { + name: "Name", + type: "text", + order: 0 +}); + +await tablesService.addColumn(projects.id, { + name: "Status", + type: "multiselect", + order: 1, + options: { choices: ["Planning", "In Progress", "Completed"] } +}); + +// Table "Tasks" +const tasks = await tablesService.createTable({ + name: "Tasks", + description: "Project tasks" +}); + +await tablesService.addColumn(tasks.id, { + name: "Name", + type: "text", + order: 0 +}); + +await tablesService.addColumn(tasks.id, { + name: "Project", + type: "relation", + order: 1, + options: { + relatedTableId: projects.id, + relatedColumnId: 1 + } +}); + +await tablesService.addColumn(tasks.id, { + name: "Priority", + type: "number", + order: 2 +}); + +await tablesService.addColumn(tasks.id, { + name: "Status", + type: "multiselect", + order: 3, + options: { choices: ["To Do", "In Progress", "Review", "Done"] } +}); +``` + +#### Filter Tasks by Project + +```javascript +// Get all tasks for project with ID = 5 +const tasks = await api.get(`/tables/${tasks.id}/rows?relation_2=5`); + +// Get tasks with priority > 5 +const highPriority = tasks.filter(task => { + const priority = cellValues.find( + cell => cell.row_id === task.id && cell.column_id === 3 + )?.value; + return parseInt(priority) > 5; +}); +``` + +--- + +## Security + +### Data Encryption + +**All sensitive data encrypted with AES-256**: + +```javascript +// Encrypted: +name_encrypted // Table name +description_encrypted // Description +value_encrypted // Cell values +placeholder_encrypted // Placeholders + +// NOT encrypted (for indexes and performance): +placeholder // Unencrypted placeholder +options // JSONB settings +order // Order +``` + +**Encryption functions in PostgreSQL**: + +```sql +-- Encryption +encrypt_text(plain_text, encryption_key) + +-- Decryption +decrypt_text(encrypted_text, encryption_key) + +-- Usage example +INSERT INTO user_tables (name_encrypted) +VALUES (encrypt_text('Contacts', $1)); + +SELECT decrypt_text(name_encrypted, $1) as name +FROM user_tables; +``` + +### Access Rights + +```javascript +// View: all authorized users +GET /tables +GET /tables/:id +GET /tables/:id/rows + +// Editing: users with rights +if (!canEditData) { + return res.status(403).json({ error: 'Access denied' }); +} +POST /tables/:id/columns +POST /tables/:id/rows +POST /tables/cell +PATCH /tables/column/:columnId + +// Deletion: administrators only +if (!req.session.userAccessLevel?.hasAccess) { + return res.status(403).json({ error: 'Administrators only' }); +} +DELETE /tables/:id +DELETE /tables/column/:columnId +DELETE /tables/row/:rowId +POST /tables/:id/rebuild-index +``` + +### Token-Based Rights Verification + +```javascript +// Backend checks token balance +const address = req.session.address; +const dleContract = new ethers.Contract(dleAddress, dleAbi, provider); +const balance = await dleContract.balanceOf(address); + +if (balance === 0n) { + return res.status(403).json({ + error: 'Access denied: no tokens' + }); +} + +// Determine access level +const accessLevel = determineAccessLevel(balance); +req.session.userAccessLevel = accessLevel; +``` + +### SQL Injection Protection + +**Parameterized queries**: + +```javascript +// โ Safe (parameters) +await db.getQuery()( + 'SELECT * FROM user_tables WHERE id = $1', + [tableId] +); + +// โ DANGEROUS (concatenation) +await db.getQuery()( + `SELECT * FROM user_tables WHERE id = ${tableId}` +); +``` + +### Input Validation + +```javascript +// Type check +if (typeof name !== 'string') { + return res.status(400).json({ error: 'Invalid name' }); +} + +// Existence check +const exists = await db.getQuery()( + 'SELECT id FROM user_tables WHERE id = $1', + [tableId] +); +if (!exists.rows[0]) { + return res.status(404).json({ error: 'Table not found' }); +} + +// Uniqueness check (placeholder) +const duplicate = await db.getQuery()( + 'SELECT id FROM user_columns WHERE placeholder = $1 AND id != $2', + [placeholder, columnId] +); +if (duplicate.rows.length > 0) { + placeholder = generateUniquePlaceholder(); +} +``` + +### Cascading Deletion (Protection from Orphaned Data) + +```sql +-- All relations with ON DELETE CASCADE +CREATE TABLE user_columns ( + table_id INTEGER NOT NULL + REFERENCES user_tables(id) ON DELETE CASCADE +); + +CREATE TABLE user_rows ( + table_id INTEGER NOT NULL + REFERENCES user_tables(id) ON DELETE CASCADE +); + +CREATE TABLE user_cell_values ( + row_id INTEGER NOT NULL + REFERENCES user_rows(id) ON DELETE CASCADE, + column_id INTEGER NOT NULL + REFERENCES user_columns(id) ON DELETE CASCADE +); + +-- Result: table deletion automatically deletes EVERYTHING +``` + +### Rate Limiting + +```javascript +// Can be added in backend/routes/tables.js +const rateLimit = require('express-rate-limit'); + +const tablesLimiter = rateLimit({ + windowMs: 15 * 60 * 1000, // 15 minutes + max: 100, // 100 requests + message: 'Too many requests to tables' +}); + +router.use(tablesLimiter); +``` + +--- + +## Performance + +### Optimizations + +#### 1. Parallel Queries + +```javascript +// Instead of sequential queries: +const tableMeta = await db.query('SELECT ...'); +const columns = await db.query('SELECT ...'); +const rows = await db.query('SELECT ...'); +const cellValues = await db.query('SELECT ...'); + +// Use parallel: +const [tableMeta, columns, rows, cellValues] = await Promise.all([ + db.query('SELECT ...'), + db.query('SELECT ...'), + db.query('SELECT ...'), + db.query('SELECT ...') +]); + +// Speedup: 4x +``` + +#### 2. Indexes on Relations + +```sql +CREATE INDEX idx_user_table_relations_from_row + ON user_table_relations(from_row_id); + +CREATE INDEX idx_user_table_relations_to_table + ON user_table_relations(to_table_id); + +-- Result: fast filtering by relations +``` + +#### 3. UNIQUE Constraint + +```sql +CREATE TABLE user_cell_values ( + ... + UNIQUE(row_id, column_id) +); + +-- Advantages: +-- 1. Prevents duplicate cells +-- 2. Speeds up upsert (ON CONFLICT) +-- 3. Automatic index +``` + +#### 4. WebSocket Instead of Polling + +```javascript +// โ Polling (slow) +setInterval(async () => { + const data = await fetchTableData(); + updateUI(data); +}, 5000); + +// โ WebSocket (instant) +socket.on('table-update', (data) => { + if (data.tableId === currentTableId) { + updateUI(data); + } +}); + +// Result: real-time updates, no server load +``` + +#### 5. Caching + +```javascript +// Backend can add cache for frequently requested tables +const NodeCache = require('node-cache'); +const tableCache = new NodeCache({ stdTTL: 300 }); // 5 minutes + +router.get('/:id', async (req, res) => { + const cacheKey = `table_${req.params.id}`; + const cached = tableCache.get(cacheKey); + + if (cached) { + return res.json(cached); + } + + const data = await fetchTableData(req.params.id); + tableCache.set(cacheKey, data); + res.json(data); +}); +``` + +### Metrics + +**Typical response times**: +``` +GET /tables โ 50-100ms (all tables) +GET /tables/:id โ 150-300ms (with data, Promise.all) +POST /tables/cell โ 100-200ms (upsert + vector update) +DELETE /tables/row/:id โ 200-400ms (deletion + rebuild vector) +POST /tables/:id/rebuild-index โ 1-5s (depends on size) +``` + +**Optimal table sizes**: +``` +Rows: up to 10,000 โ Excellent +Rows: 10,000-50,000 โ Good +Rows: >50,000 โ Need additional optimizations (pagination, lazy load) +``` + +--- + +## Limitations and Future Improvements + +### Current Limitations + +1. **No pagination**: All rows loaded at once + - For large tables (>1000 rows) may be slow + +2. **No formulas**: Cannot create calculated fields + - Workaround: use lookup + +3. **No grouping**: Cannot group rows + - Workaround: filtering on frontend + +4. **No change history**: Not tracked who and when changed + - Can add audit trail + +5. **Limited sorting**: Only through order field + - No column sorting on backend + +### Possible Improvements + +```javascript +// 1. Pagination +GET /tables/:id/rows?page=1&limit=50 + +// 2. Sorting +GET /tables/:id/rows?sort_by=column_id&order=asc + +// 3. Formulas +{ + "type": "formula", + "options": { + "formula": "{{price}} * {{quantity}}" + } +} + +// 4. Change history +CREATE TABLE user_cell_history ( + id SERIAL PRIMARY KEY, + cell_id INTEGER REFERENCES user_cell_values(id), + old_value TEXT, + new_value TEXT, + changed_by INTEGER, + changed_at TIMESTAMP +); + +// 5. Export/import +POST /tables/:id/export โ CSV/Excel +POST /tables/:id/import โ CSV/Excel + +// 6. Table templates +POST /tables/templates/crm โ Create CRM from template +POST /tables/templates/tasks โ Create Kanban from template +``` + +--- + +## Conclusion + +The electronic tables system in DLE is a **powerful tool** for managing structured data with: + +โ **Flexible structure** (6 field types) +โ **Relations between tables** (relation, lookup) +โ **AI integration** (RAG, vector search) +โ **Real-time updates** (WebSocket) +โ **Security** (AES-256, access rights) +โ **Performance** (indexes, parallel queries) + +This is **not just Excel**, but a **full-featured database** with convenient interface and AI assistant! + +--- + +**ยฉ 2024-2025 Tarabanov Alexander Viktorovich. All rights reserved.** + +**Document version**: 1.0.0 +**Creation date**: October 25, 2025 +**Status**: Temporary (for internal use) + diff --git a/docs/README.md b/docs/README.md index 24a749a..c224d66 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,7 @@ # ๐ ะะพะบัะผะตะฝัะฐัะธั Digital Legal Entity +**๐ Language / ะฏะทัะบ:** [๐ท๐บ ะ ัััะบะธะน](README.md) | [๐ฌ๐ง English](../docs-en/README.md) + ะญัะพั ัะฐะทะดะตะป ัะพะดะตัะถะธั ะผะฐัะตัะธะฐะปั ะฟะพ ะฟัะพะดัะบัั DLE: ะพะฑะทะพั, ะฑะธะทะฝะตั-ะบะตะนัั, ัะตั ะฝะธัะตัะบะธะต ัะฟะตัะธัะธะบะฐัะธะธ ะธ ะธะฝััััะบัะธะธ ะฟะพ ะฒะฝะตะดัะตะฝะธั. ะัะฟะพะปัะทัะนัะต ัะฟะธัะพะบ ะฝะธะถะต, ััะพะฑั ะฑััััะพ ะฝะฐะนัะธ ะฝัะถะฝัะน ะดะพะบัะผะตะฝั. ## ๐ ะะพัััะฟะฝัะต ะดะพะบัะผะตะฝัั diff --git a/legal-en/ATTRIBUTION_REQUIREMENTS.md b/legal-en/ATTRIBUTION_REQUIREMENTS.md new file mode 100644 index 0000000..af6e7d5 --- /dev/null +++ b/legal-en/ATTRIBUTION_REQUIREMENTS.md @@ -0,0 +1,113 @@ +# Attribution Requirements + +## Mandatory Attribution + +When using any code from the DLE (Digital Legal Entity) project, including individual functions, modules, or algorithms, you must indicate the source. + +## Attribution Formats + +### In code comments +```javascript +/** + * Source: DLE (Digital Legal Entity) + * Author: Tarabanov Alexander Viktorovich + * License: Proprietary + * Link: https://github.com/VC-HB3-Accelerator/DLE + */ +``` + +### In documentation +```markdown +## Used Components + +- **DLE Authentication Module** - Tarabanov Alexander Viktorovich + - License: Proprietary + - Source: https://github.com/VC-HB3-Accelerator/DLE +``` + +### In configuration files +```json +{ + "attributions": { + "DLE": { + "author": "Tarabanov Alexander Viktorovich", + "license": "Proprietary", + "source": "https://github.com/VC-HB3-Accelerator/DLE", + "contact": "info@hb3-accelerator.com" + } + } +} +``` + +## What Requires Attribution + +### Must indicate source: +- Any functions or methods +- Algorithms and logic +- Data structures +- Configuration files +- Styles and UI components +- Documentation and comments + +### Does not require attribution: +- Standard libraries and frameworks +- Well-known algorithms +- Basic programming patterns + +## Attribution Violations + +### Considered a violation: +- Using code without indicating source +- Removing or modifying attribution +- Incorrect author indication + +### Consequences: +- Automatic license termination +- Possibility of legal action +- Requirement to immediately cease use + +## Examples of Proper Attribution + +### In JavaScript file +```javascript +// Document validation function +// Source: DLE (Digital Legal Entity) - Tarabanov Alexander Viktorovich +// License: Proprietary +function validateDocument(doc) { + // implementation +} +``` + +### In Python file +```python +# Blockchain transaction processing module +# Source: DLE (Digital Legal Entity) - Tarabanov Alexander Viktorovich +# License: Proprietary +class BlockchainProcessor: + # implementation +``` + +### In README file +```markdown +## Used Components + +This project uses components from DLE (Digital Legal Entity): + +- **Authentication System** - Tarabanov Alexander Viktorovich +- **Document Processing** - Tarabanov Alexander Viktorovich +- **Blockchain Integration** - Tarabanov Alexander Viktorovich + +**License:** Proprietary +**Contacts:** info@hb3-accelerator.com +``` + +## Contacts for Questions + +**Tarabanov Alexander Viktorovich** +Email: info@hb3-accelerator.com +Website: https://hb3-accelerator.com + +--- + +**ยฉ 2024-2025 Tarabanov Alexander Viktorovich. All rights reserved.** + diff --git a/legal-en/AUTHORS.md b/legal-en/AUTHORS.md new file mode 100644 index 0000000..4d8db7b --- /dev/null +++ b/legal-en/AUTHORS.md @@ -0,0 +1,35 @@ +# DLE Project Authors (Digital Legal Entity) + +## Main Developer + +**Tarabanov Alexander Viktorovich** +- **GitHub:** [@VC-HB3-Accelerator](https://github.com/VC-HB3-Accelerator) +- **Organization:** HB3 Accelerator +- **Email:** info@hb3-accelerator.com +- **Website:** [hb3-accelerator.com](https://hb3-accelerator.com) + +## Contributors + +- **Limited Liability Company "ERAITI" (LLC "ERAITI")** + - **Role:** Official seller and licensing partner for clients from the Russian Federation + - **Contacts:** 18900@ััะฐะนัะธ.ัั, +7 (968) 269-92-64 + +## Contact Information + +### For copyright and licensing questions: +- **Email:** info@hb3-accelerator.com +- **GitHub Issues:** [Create issue](https://github.com/VC-HB3-Accelerator/DLE/issues) +- **Website:** [hb3-accelerator.com](https://hb3-accelerator.com) + + +## Project History + +- **2024-2025:** Development and release of the first version of DLE +- **Author:** Tarabanov Alexander Viktorovich +- **License:** Proprietary Software License +- **Status:** Active development + +--- + +**All rights reserved.** See the [LICENSE.md](LICENSE.md) file for details. + diff --git a/legal-en/CONTRIBUTING.md b/legal-en/CONTRIBUTING.md new file mode 100644 index 0000000..580c157 --- /dev/null +++ b/legal-en/CONTRIBUTING.md @@ -0,0 +1,76 @@ +# Contributor Guide + +## Licensing + +When contributing to the DLE (Digital Legal Entity) project, you agree that your code will be distributed under the **Proprietary Software License**. + +## Copyright + +All contributors must: +- Indicate their name in commits +- Agree to transfer code rights to the project author +- Not violate third-party copyrights + +## Contribution Process + +### 1. Preparation +- Fork the repository +- Clone your fork locally +- Create a feature branch for your changes + +### 2. Development +- Follow the project's coding standards +- Add code comments in English +- Test your changes + +### 3. Commits +- Use clear commit messages +- Indicate your name in commits +- Break large changes into logical parts + +### 4. Pull Request +- Create a Pull Request with a description of changes +- Indicate what problems your code solves +- Wait for review from the project author + +## Code Standards + +### Naming +- Files and folders: kebab-case +- Variables and functions: camelCase +- Constants: UPPER_SNAKE_CASE +- Classes: PascalCase + +### Comments +```javascript +/** + * @copyright 2024-2025 Tarabanov Alexander Viktorovich + * @license Proprietary + * @author [Your name] + */ +``` + +### Git Messages +``` +feat: add new authentication function +fix: fix data validation error +docs: update API documentation +style: code formatting +refactor: refactor user module +test: add tests for new functionality +``` + +## Contacts + +### For questions about project participation: +- **Email:** info@hb3-accelerator.com +- **GitHub Issues:** [Create issue](https://github.com/VC-HB3-Accelerator/DLE/issues) + +### Project Author: +**Tarabanov Alexander Viktorovich** +Email: info@hb3-accelerator.com + +--- + +**Thank you for your contribution to the DLE project development!** + diff --git a/legal-en/COPYRIGHT_NOTICE.md b/legal-en/COPYRIGHT_NOTICE.md new file mode 100644 index 0000000..0b15afd --- /dev/null +++ b/legal-en/COPYRIGHT_NOTICE.md @@ -0,0 +1,101 @@ +# Copyright Notice + +## For use in code file headers + +Add the following header to the beginning of each source code file: + +```javascript +/** + * @copyright 2024-2025 Tarabanov Alexander Viktorovich + * @license Proprietary + * @author Tarabanov Alexander Viktorovich + * @see https://github.com/VC-HB3-Accelerator + * @see https://hb3-accelerator.com + */ +``` + +## For Python files + +```python +""" +@copyright 2024-2025 Tarabanov Alexander Viktorovich +@license Proprietary +@author Tarabanov Alexander Viktorovich +@see https://github.com/VC-HB3-Accelerator +@see https://hb3-accelerator.com +""" +``` + +## For Vue files + +```vue + +``` + +## For CSS/SCSS files + +```css +/* +@copyright 2024-2025 Tarabanov Alexander Viktorovich +@license Proprietary +@author Tarabanov Alexander Viktorovich +@see https://github.com/VC-HB3-Accelerator +@see https://hb3-accelerator.com +*/ +``` + +## For HTML files + +```html + +``` + +## For configuration files + +```json +{ + "_copyright": "2024-2025 Tarabanov Alexander Viktorovich", + "_license": "Proprietary", + "_author": "Tarabanov Alexander Viktorovich ", + "_website": "https://hb3-accelerator.com", + "_github": "https://github.com/VC-HB3-Accelerator" +} +``` + +## Important files for adding headers + +### Frontend +- `frontend/src/main.js` +- `frontend/src/App.vue` +- All Vue components +- All CSS/SCSS styles + +### Backend +- `backend/src/index.js` +- All modules and controllers +- Configuration files + +### Documentation +- `README.md` +- `docs/` - all documentation files + +## Automation + +It is recommended to set up pre-commit hooks for automatically adding copyright headers to new files. + +--- + +**All rights reserved.** See the [LICENSE.md](LICENSE.md) file for details. + diff --git a/legal-en/README.md b/legal-en/README.md new file mode 100644 index 0000000..3e7f4a5 --- /dev/null +++ b/legal-en/README.md @@ -0,0 +1,141 @@ +# DLE LEGAL DOCUMENTATION +## Intellectual Property Protection + +**๐ Language / ะฏะทัะบ:** [๐ท๐บ ะ ัััะบะธะน](../legal/README.md) | [๐ฌ๐ง English](README.md) + +### ๐ **DOCUMENT OVERVIEW** + +This section contains all legal documentation for protecting the intellectual property of the DLE (Digital Legal Entity) project. + +### ๐ **CONFIDENTIAL DOCUMENTS** + +#### **Patent documents (DO NOT PUBLISH):** +- [patents/](patents/) - Patent applications and innovative processes + - Russian Federation patent applications + - Technical specifications + - Innovative processes + - Strategic plans + +**โ ๏ธ IMPORTANT:** Patent documents contain confidential information and MUST NOT be published in public repositories. + +### โ **PUBLIC DOCUMENTS** + +#### **Copyright and licenses:** +- [AUTHORS.md](AUTHORS.md) - Author information +- [CONTRIBUTING.md](CONTRIBUTING.md) - Contributor guidelines +- [COPYRIGHT_NOTICE.md](COPYRIGHT_NOTICE.md) - Copyright templates + +#### **Licensing and terms:** +- [service-terms.md](service-terms.md) - Terms of use and licensing +- [ATTRIBUTION_REQUIREMENTS.md](ATTRIBUTION_REQUIREMENTS.md) - Attribution requirements +- [USAGE_NOTIFICATION.md](USAGE_NOTIFICATION.md) - Usage notifications + +#### ๐ **File Overview** + +| File | Purpose | +| --- | --- | +| [AUTHORS.md](AUTHORS.md) | Author information and contact details. | +| [CONTRIBUTING.md](CONTRIBUTING.md) | Participation rules for project contributors. | +| [COPYRIGHT_NOTICE.md](COPYRIGHT_NOTICE.md) | Copyright notice templates for source files. | +| [service-terms.md](service-terms.md) | Detailed licensing and maintenance terms. | +| [ATTRIBUTION_REQUIREMENTS.md](ATTRIBUTION_REQUIREMENTS.md) | Formats and examples of mandatory attribution. | +| [USAGE_NOTIFICATION.md](USAGE_NOTIFICATION.md) | Instructions and template for usage notification. | + +#### **Complete service terms:** +- ๐ [../docs-en/service-terms.md](../docs-en/service-terms.md) - **Detailed purchase and maintenance terms** + - Licensing model (Perpetual License) + - Service term types (Standard & Priority) + - Smart contract voting system + - 70% refund program + - Technical support via https://hb3-accelerator.com/ + +--- + +## ๐ **LICENSING MODEL** + +### Perpetual License + +- **๐ฐ Price:** $1,000 USDT (Standard) or $10,000 USDT (Priority) +- **โณ Term:** Lifetime (no time limit) +- **๐ Updates:** Free for 5 years for license token holders (see [service-terms](./service-terms.md)) +- **๐ณ๏ธ Voting:** Blockchain voting for new feature development + +### Management via DLE Smart Contract + +Application development is managed through a blockchain smart contract (tokenized joint-stock company): + +- **1 token = 1 vote** regardless of quantity +- **51%+ for approval** majority decision +- **Multi-chain** support for voting and execution +- **Transparency** - all decisions on blockchain + +### Portal for Licensees + +- ๐ณ๏ธ **Voting portal**: https://hb3-accelerator.com/ +- ๐ฅ **Download updates**: https://hb3-accelerator.com/ +- ๐ฌ **Support**: https://hb3-accelerator.com/ + +### ๐ **PROTECTION STRUCTURE** + +``` +legal-en/ +โโโ AUTHORS.md # โ PUBLISH - Project authors +โโโ CONTRIBUTING.md # โ PUBLISH - Contribution guidelines +โโโ COPYRIGHT_NOTICE.md # โ PUBLISH - Copyright templates +โโโ service-terms.md # โ PUBLISH - Terms of use +โโโ ATTRIBUTION_REQUIREMENTS.md # โ PUBLISH - Attribution requirements +โโโ USAGE_NOTIFICATION.md # โ PUBLISH - Usage notifications +โโโ README.md # โ PUBLISH - This file +``` + +### ๐ก๏ธ **PROTECTION MECHANISMS** + +#### **1. Copyright:** +- All files contain copyright by Tarabanov A.V. +- Proprietary license used +- Copying without permission prohibited + +#### **2. Patent protection:** +- Confidential documents in `patents/` folder +- Folder added to `.gitignore` +- Documents not published in repositories + +#### **3. Licensing:** +- Strict proprietary license +- Mandatory attribution when using + +#### **4. Monitoring:** +- Code usage notifications +- Attribution requirements + +### ๐ฏ **USAGE RECOMMENDATIONS** + +#### **For developers:** +1. Review the main [LICENSE](../LICENSE) before use +2. Follow [ATTRIBUTION_REQUIREMENTS.md](ATTRIBUTION_REQUIREMENTS.md) +3. Notify the author according to [USAGE_NOTIFICATION.md](USAGE_NOTIFICATION.md) + +#### **For use:** +1. Respect copyright +2. Indicate source when using +3. Do not transfer to third parties + +### ๐ **CONTACTS** + +**Author:** Tarabanov Alexander Viktorovich +**Email:** info@hb3-accelerator.com +**Website:** https://hb3-accelerator.com +**GitHub:** https://github.com/VC-HB3-Accelerator + +### โ๏ธ **LEGAL INFORMATION** + +All documents in this section are protected by copyright. Unauthorized use, copying, or distribution is prohibited. + +For usage permissions, contact the author at the provided contacts. + +--- + +**Creation date:** 2024-2025 +**Last update:** 2024-2025 +**Status:** Actively maintained + diff --git a/legal-en/USAGE_NOTIFICATION.md b/legal-en/USAGE_NOTIFICATION.md new file mode 100644 index 0000000..ab20b13 --- /dev/null +++ b/legal-en/USAGE_NOTIFICATION.md @@ -0,0 +1,131 @@ +# Usage Notification Requirements + +## Mandatory Notifications + +When using code from the DLE (Digital Legal Entity) project in any form, including private repositories, you must notify the author. + +## When Notification is Required + +### Must notify: +- Use in private repositories +- Integration into existing systems +- Creation of derivative works +- Use for educational purposes + +### Does not require notification: +- Personal code study +- Functionality testing +- Capability demonstration + +## Notification Form + +### Email notification +``` +Subject: DLE Usage Notification + +Dear Tarabanov Alexander Viktorovich, + +We notify you of the use of code from the DLE (Digital Legal Entity) project: + +## Project Information: +- Project name: [NAME] +- Description: [DESCRIPTION] +- Type of use: [EDUCATIONAL/PERSONAL] + +## Used Components: +- [LIST OF USED MODULES/FUNCTIONS] + +## Contact Information: +- Name: [FULL NAME] +- Email: [EMAIL] +- Organization: [ORGANIZATION] + +## Usage Plans: +- [DESCRIPTION OF PLANS] + +Best regards, +[FULL NAME] +[EMAIL] +``` + +### GitHub Issue +Create an issue in the repository with the `usage-notification` tag: +- Project description +- List of used components +- Contact information +- Usage plans + +## Notification Deadlines + +- **Before starting use** - for commercial projects +- **Within 30 days** - for educational projects +- **Within 90 days** - for personal projects + +## Consequences of Missing Notification + +### License violation: +- Automatic termination of usage rights +- Possibility of requiring cessation of use +- Potential legal consequences + +### Exceptions: +- Use for demonstration purposes +- Short-term testing +- Study of architecture and algorithms + +## Usage Monitoring + +### Automatic monitoring: +- Tracking repository forks +- Monitoring code mentions +- Analysis of dependencies in npm/pip + +### Manual monitoring: +- Search on GitHub/GitLab +- Monitoring technical blogs +- Tracking conferences and presentations + +## Contacts for Notifications + +**Tarabanov Alexander Viktorovich** +- **Email:** info@hb3-accelerator.com +- **GitHub Issues:** [Create issue](https://github.com/VC-HB3-Accelerator/DLE/issues) +- **Subject:** "DLE Usage Notification" + +## Notification Templates + +### For commercial use +``` +Subject: Commercial DLE Usage Notification + +We notify you of commercial use of DLE in the project [NAME]. +Licensing is required to continue use. + +Project details are attached. +``` + +### For educational use +``` +Subject: Educational DLE Usage Notification + +We notify you of the use of DLE for educational purposes. +Project: [NAME] +Educational institution: [NAME] + +Permission is required for use in courses. +``` + +### For personal use +``` +Subject: Personal DLE Usage Notification + +We notify you of personal use of DLE in the project [NAME]. +Usage: [DESCRIPTION] + +Thank you for creating an excellent tool! +``` + +--- + +**ยฉ 2024-2025 Tarabanov Alexander Viktorovich. All rights reserved.** + diff --git a/legal-en/service-terms.md b/legal-en/service-terms.md new file mode 100644 index 0000000..bca614a --- /dev/null +++ b/legal-en/service-terms.md @@ -0,0 +1,625 @@ +# Digital Legal Entity Purchase and Service Terms + +## 1. Licensing Model + +### 1.1. Basic Principles + +- **๐ License Type**: Single type - **Perpetual License** +- **โณ Term**: Lifetime (no time limit) +- **๐ฐ Price**: Depends on **number of tokens** in the license (see section 2) +- **๐ Updates**: FREE for 5 years for license token holders +- **๐ซ Cancellation**: License cannot be canceled by the company +- **โ๏ธ Service Terms**: Same for all licenses (difference only in number of votes) + +### 1.2. Connection: Tokens โ Licenses + +Each Digital Legal Entity license is linked to a **blockchain governance token**. + +#### ๐ Token and Rights Ratio + +| Parameter | For 1 token | For 10 tokens | +|----------|-----------|--------------| +| **Number of licenses** | 1 | 1 | +| **Types of activity** | 1 | 1 | +| **Votes in voting** | 1 | 10 | +| **Service terms** | Same | Same | +| **Influence on development** | 1 vote | 10 votes | + +#### ๐ณ๏ธ Community Voting + +- **Vote = 1 token** (regardless of number of tokens per owner) +- Voting occurs on **blockchain** (governance smart contract) +- Tokens give voting rights for **new features and development priorities** +- **Democracy**: Decisions are made by majority vote (51%+) + +### 1.3. Type of Activity and Usage + +- Each license is tied to **one type of activity/business** +- Owner can redefine the type of activity, but can only maintain one at a time +- For multiple types of activity, separate licenses and tokens are needed + +--- + +## 2. License Types + +### 2.1. License with 1 Token + +- **๐ฐ License price**: **$1,000 USDT** (one-time, perpetual, excluding taxes) +- **๐ช Number of tokens**: **1 token** = **1 vote** in voting +- **๐ณ๏ธ Development influence**: Basic (1 vote for new features) + +### 2.2. License with 10 Tokens + +- **๐ฐ License price**: **$10,000 USDT** (one-time, perpetual, excluding taxes) +- **๐ช Number of tokens**: **10 tokens** = **10 votes** in voting +- **๐ณ๏ธ Development influence**: Enhanced (10 votes for new features) + +### 2.3. Service Terms (same for all licenses) + +**๐ง All license token holders receive (within 5 years from on-chain transfer date):** + +- โ All web application updates (free, 5 years) +- โ Access to documentation and knowledge base +- โ Technical support through the application: https://hb3-accelerator.com/ +- โ Response time: according to problem priority (see section 6.3) +- โ ๐ค **24/7 AI Assistant** - built-in assistant for consultations +- โ All integrations and deployment capabilities +- โ Participation in voting for new features (by number of tokens) +- โ Early access to beta features (if desired) +- โ 99% uptime SLA guarantee +- โ ๐ **Online training and implementation sessions**: + - Group online sessions (quarterly - 4 times per year) + - Individual online sessions (on request) + - Application setup training + - Business integration strategies + - ROI maximization consultations + - Access to library of all session recordings + +**โ๏ธ The only difference between licenses:** +- Number of governance tokens (1 vs 10) +- Number of votes in voting (1 vs 10) +- Influence on prioritization of new feature development + +--- + +## 3. Voting System and Product Development + +### 3.1. How Voting Works + +1. **Feature proposal**: Community proposes new features +2. **Blockchain registration**: Voting is created in smart contract +3. **Token holder voting**: Each token = 1 vote +4. **Implementation**: If 51%+ tokens vote - feature goes into development + +### 3.2. Voting Frequency + +- **Voting window**: Open continuously (asynchronous voting) +- **Quarterly analysis**: Each quarter votes are summed, decisions analyzed +- **Prioritization**: Development follows priority (number of votes) + +### 3.3. "Non-compliance Complaint" Mechanism + +โ ๏ธ **Refund mechanism (see section 4.2)** + +### 3.4. ๐ Web Application for Voting + +**Address**: https://hb3-accelerator.com/ + +Token holders can: +- ๐ Create proposals for new features and prioritization +- ๐ณ๏ธ Vote for or against proposals +- ๐ View voting results +- ๐ Track development status of approved features +- โฑ๏ธ See history of all blockchain votes + +**Requirements:** +- Wallet connection with tokens (MetaMask, WalletConnect, etc.) +- Your number of tokens = number of votes + +--- + +## 4. Refunds and Guarantees + +### 4.1. General Terms + +- **๐ Principle**: License is perpetual - no refund (except exceptional cases) +- **๐ Exception**: Special refund program (see section 4.2) + +### 4.2. 70% Refund Program + +**Refund Conditions:** + +You can request a refund of **70% of the license cost** within **5 years** from purchase date, if: + +1. โ **Complaint threshold**: Accumulated more than **51% negative votes** +2. ๐ **Reason**: Complaints concern **lack of update releases** +3. ๐ณ๏ธ **Voting**: Complaints were **accepted through token holder voting mechanism on blockchain** +4. โฑ๏ธ **Deadline**: Request submitted within **5 years** from licensing date + +**Refund Process:** + +1. Request submitted to hb3-accelerator.com with blockchain proof attached +2. Condition confirmation on smart contract (51%+ votes for refund) +3. Refund of **70% of purchase amount** within 30 days + +**Example:** +- License with 10 tokens purchased for $10,000 USDT +- Refund: $10,000 ร 70% = $7,000 USDT +- Valid until: 5 years from purchase date + +### 4.3. Liability Limitations + +โ **What is guaranteed:** +- License is perpetual (usage right not limited by term) +- Updates and basic maintenance provided free for 5 years +- Basic functionality remains available +- Ability to vote for product development + +โ **NOT guaranteed:** +- Specific new features (depends on voting) +- Specific release schedule (depends on votes) +- Support when modifying source code +- Performance when exceeding limits + +### 4.4. What the Author is NOT Liable For + +โ **Author is exempt from liability for:** + +- **Lost profits** - income losses due to application failures +- **Indirect damages** - secondary consequences of use +- **Data loss** - user is responsible for backups +- **Business interruption** - downtime and service disruptions +- **Reputation loss** - reputational damage to business +- **Special damages** - fines, penalties, sanctions, punitive payments +- **Educational use** - without permission +- **Use in accordance with terms** - if terms are violated + +### 4.5. Maximum Liability + +- **Liability limit**: Size of paid license (no more) +- **Example**: If license cost $1,000 USDT, maximum refund $1,000 USDT +- **Direct damages**: Only for direct contract violation +- **Exceptions**: Indirect, special, or punitive damages not covered + +### 4.6. User Responsibility + +โ **User is responsible for:** +- Backing up own data (weekly minimum) +- Use in accordance with license terms +- Protecting wallet private keys and access +- Compliance with all applicable laws and regulations +- Updating application within reasonable timeframes +- Checking compatibility with environment before updating + +--- + +## 5. Updates and Maintenance + +### 5.1. Free Updates and Basic Maintenance (5 years) + +๐ **Updates and basic maintenance are FREE for 5 years for license token holders (from on-chain token transfer date):** +- Bug fixes +- Performance improvements +- New features (approved by voting) +- Security updates + +**Frequency:** +- Security Patches: Immediately (upon discovery) +- Regular Updates: Weekly (on Wednesdays) within 5-year period +- Major Features: Based on voting results + +### 5.2. ๐ฅ Update Download Platform + +**Address**: https://hb3-accelerator.com/ + +All license holders can: +- โ Download all released application versions +- ๐ Read detailed release notes +- ๐ View scheduled update calendar +- ๐ Receive automatic notifications about new versions +- ๐ Study migration documentation between versions +- ๐ชต See change logs + +**Access Requirements:** +- Wallet connection with license token on address +- License token must be on address at time of update request + +## 6. Technical Support + +### 6.1. Unified Support Portal + +**All types of support available ONLY through the application:** + +๐ **https://hb3-accelerator.com/** + +- ๐ Creating and tracking support tickets +- ๐ฌ Direct chat with support team +- ๐ History of all requests +- ๐ Response time tracking + +### 6.2. Available Support Channels + +**All license holders have access to:** + +| Function | Availability | +|--------|-------------| +| ๐ Support portal | โ All licenses | +| ๐ฌ Chat with support team | โ All licenses | +| ๐ค 24/7 AI assistant | โ All licenses | +| ๐ Online training sessions | โ Group + individual (all licenses) | +| ๐ Recording library | โ All licenses | +| ๐ง Email support | โ All licenses | + +### 6.3. Problem Classification and SLA + +**Response time depends on problem priority, not license type:** + +| Priority | Description | SLA (first response time) | +|-----------|---------|-----| +| ๐ด Critical | Service completely unavailable | 4 hours | +| ๐ High | Loss of main function | 8 hours | +| ๐ก Medium | Performance degradation | 24 hours | +| ๐ข Low | Questions, documentation | 48 hours | + +### 6.4. Support Request Process + +1. Log into application: https://hb3-accelerator.com/ +2. Go to "Proposals" section +3. Create new ticket with problem description +4. Indicate priority (system automatically classifies) +5. Attach logs, screenshots, and reproduction steps +6. Receive ticket number for tracking +7. Wait for response according to SLA (by problem priority) + +### 6.5. ๐ Online Training and Implementation Sessions + +**All license holders** (regardless of type) receive access to **online training sessions**, where experts help maximize the effective use of Digital Legal Entity. + +#### Group Online Sessions + +**๐ Frequency**: Quarterly (4 times per year) + +**๐ Training Topics:** +- ๐ง **Application Setup** - step-by-step guide for initial configuration +- ๐ข **Business Integration** - how to integrate DLE into existing business processes +- ๐ฐ **ROI Maximization** - best practices for using features +- ๐ **Analytics and Reporting** - how to use data for decision-making +- ๐ **Security and Compliance** - security setup and regulatory compliance +- ๐ณ๏ธ **Voting and Governance** - how to effectively use your tokens + +**โฑ๏ธ Format:** +- Duration: 1-2 hours +- Webinar with presentation and demonstration +- Q&A session at end (30-40 minutes) +- Recording available after session + +**๐ฅ Participation Format:** +- Online meetings +- Chat for questions during session +- Ability to ask questions in advance + +#### Individual Online Sessions + +**Available for all licenses** + +**๐ Frequency**: (on request) + +**๐ฏ Personalized Topics:** +- ๐๏ธ **Individual Architecture** - setup for your business specifics +- ๐ **Integration Strategy** - step-by-step DLE integration plan +- ๐ก **ROI Optimization** - how to get maximum return on investment +- ๐ **Data Migration** - transfer from existing systems +- ๐ ๏ธ **Customization and Integrations** - setup for your requirements +- ๐ **Efficiency Analysis** - metrics and improvements overview +- ๐ณ๏ธ **Voting Strategy** - how to use your tokens to influence development + +**โฑ๏ธ Format:** +- Duration: 1-2 hours (as needed) +- Individual video meeting +- Personal expert familiar with your case +- Session recording for your team +- Materials and documentation after session +- Ability to invite your team (up to 10 people) + +#### Registration for Online Sessions + +**How to register:** +1. Log into application: https://hb3-accelerator.com/ +2. Go to group +3. Select available session from calendar (group or individual) +4. Click "Register" and receive connection link + +#### Recording Library + +All past online sessions are available in the library for all license holders: + +**๐ Address**: https://hb3-accelerator.com/ + +- ๐ฅ Video recordings of all group sessions +- ๐ Presentations and materials +- ๐ฌ Q&A session transcripts +- ๐ Search by topics and keywords +- ๐ฅ Download materials for offline viewing + +--- + +## 7. Terms of Use + +### 7.1. Permissible Use + +โ **Permitted:** +- Use for managing own business +- Deployment on own infrastructure +- Use of selected type of activity (1 type per license) +- Data backup +- Local configuration modification +- Voting for new feature development +- License transfer to heirs (for perpetual license) + +โ **Prohibited:** +- Resale or sublicensing +- Use of more than one type of activity with one license +- Reverse engineering and source code modification +- Removal of copyright and license notices +- Shared use between independent organizations +- Educational use without permission +- SaaS deployment based on application +--- + +## 8. Security and Privacy + +### 8.1. Data Encryption + +- **TLS 1.3**: For all connections +- **AES-256**: For critical data in storage +- **Key Management**: User controls encryption keys + +### 8.2. Standards Compliance + +- **GDPR**: Compliance (with DPA) +- **SOC 2 Type II**: Certification obtained +- **ISO 27001**: Planned +--- + +## 9. License Management Smart Contract + +### 9.1. Management System Architecture + +DLE uses a **smart contract** on blockchain for license management and voting: + +- **ERC20 tokens**: Each license is represented by governance tokens (1 or 10) +- **ERC20Votes**: Built-in voting system through smart contract +- **ERC20Permit**: Signatures for token transfers without gas fees (meta-transactions) +- **Multi-chain architecture**: Support for voting and execution in multiple networks simultaneously + +### 9.2. Proposal and Voting System + +**Creating a proposal:** +- Only token holders (licenses) can create proposals +- Description: Text of proposal for new feature +- Voting duration: From 1 hour to 30 days +- Target networks: Can be executed in one or multiple networks simultaneously + +**Voting Process:** +1. Proposal is created and receives unique ID +2. Token holders vote "For" or "Against" +3. Each token = 1 vote (regardless of holder) +4. Quorum is checked at deadline or when 51%+ is reached + +**Proposal Execution:** +- If "For" > "Against" AND quorum reached โ proposal accepted +- Execution can be through: + - Direct call (in voting chain) + - Through signatures (in other networks) + + +### 9.3. Security and Limitations + +โ **Reentrancy Protection** - ReentrancyGuard in all critical operations +โ **Direct Transfer Blocking** - tokens transferred only through governance +โ **Vote Snapshots** - past values used to protect against flash-loans +โ **EIP-712 Signatures** - support for contract wallets and meta-transactions +โ **Operation Validation** - all parameters checked before execution + +### 9.4. License Transfer + +- License = governance tokens tied to wallet address +- Transfer: Simply transfer tokens to new address (possible through governance) +- Rights: New owner automatically receives voting rights + +--- + +## 10. Contact Information and Support + +### ๐ Support Service + +๐ **ONLY through application**: https://hb3-accelerator.com/ +- **GitHub**: https://github.com/VC-HB3-Accelerator/DLE + +### โ๏ธ Legal Information +- **Legal Status**: Proprietary Software (see [LICENSE](../LICENSE)) +- **Full Documentation**: [legal-en/README.md](README.md) + +--- + +## 11. Terms Change Policy + +### 11.1. Changes for New Licenses + +- We may change service terms **for new purchases** +- Notification: 60 days before taking effect +- Application: Only for new licenses purchased after change date + +### 11.2. Protection of Existing Licenses + +- **Guarantee**: Your license terms **DO NOT change** after purchase +- **Fixed Rights**: Remain forever with current terms +- **Backward Compatibility**: Old terms are supported +--- + +**ยฉ 2024-2025 Tarabanov Alexander Viktorovich. All rights reserved.** + +**Last update**: October 2025 + +### ๐ Blockchain Note + +This license management model uses blockchain to ensure **transparency**, **democracy**, and **immutability** of the product development voting process. All token holders have equal votes and control over the future development of Digital Legal Entity. + +## 5. Pricing and Payment Terms + +### 5.1. Payment Methods + +- ๐ต **Cryptocurrency (USDT)**: Directly to addresses of authorized partner companies +- ๐ณ **Local Currency Transfer**: Equivalent in buyer's country local currency +- ๐ฆ **Bank Transfer**: Through authorized dealers +- ๐ณ **Credit Cards**: Through partner payment systems + +### 5.2. Prices and Taxes + +#### โ ๏ธ IMPORTANT: All prices are EXCLUDING TAXES + +**Prices in USDT:** +- **License with 1 token**: $1,000 USDT (excluding taxes) +- **License with 10 tokens**: $10,000 USDT (excluding taxes) + +**Equivalent in other currencies (examples, depends on exchange rate):** +- EUR: โฌ899 (1 token) or โฌ8,991 (10 tokens) +- RUB: โฝ99,000 (1 token) or โฝ990,000 (10 tokens) +- Other currencies at current exchange rate at time of payment + +#### Taxes - Buyer's Responsibility + +Buyer is independently responsible for paying all applicable taxes: +- **VAT** - in EU countries and others (usually 15-25%) +- **Sales Tax** - in USA and other countries +- **Income Tax** - depends on tax status +- **Customs Duties** - when importing to certain countries +- **Any other taxes** - depending on local jurisdiction + +**Tax rate is determined by:** +- Buyer's jurisdiction (country, city, region) +- Tax status (individual, sole proprietor, LLC, JSC, etc.) +- International trade specifics + +#### ๐ธ Payment Fees - FULLY ON BUYER + +All fees for transfers, conversion, and payment processing are borne by the **BUYER**: + +**๐ Currency Conversion Fees:** +- Bank/payment system commission: 1-5% of amount +- Inter-market spread commission (rate): +1-2% above market +- Hidden conversion fees: often 2-3% + +**๐ฆ Bank Transfer Fees:** +- **SWIFT transfers** (international): $10-50+ per transaction +- **SEPA transfers** (within EU): โฌ0-3 or free +- **Other systems** (Wise, Payoneer): 1-2.5% + fixed fee +- **Recipient side commission**: additional $0-50 (may be) + +**โ๏ธ Blockchain Fees (cryptocurrency - USDT):** +- **Gas fees (network commission)**: + - Ethereum: $1-50+ depending on load + - Polygon: $0.01-1 + - BSC: $0.10-5 + - Other networks: varies +- **Wallet commission**: 0-2% (if payment provider used) +- **Exchange/platform commission**: 1-3% for fiat to USDT exchange + +**๐ณ Payment System Fees (credit cards):** +- **Processing commission**: 2-5% of amount +- **Currency conversion commission**: 1-3% (if payment in other currency) +- **Issuing bank commission**: 0-2% (rare, but may be) +- **Dynamic Currency Conversion (DCC) commission**: 2-4% (if available) + +**Real Examples of Total Costs:** + +| Option | Stated Price | Fees | Total to Pay | +|---------|-----------------|----------|-----------------| +| USDT directly | $1,000 | $15-80 (gas + fees) | $1,015-1,080 | +| SWIFT transfer USD | $1,000 | $25-80 (bank fees) | $1,025-1,080 | +| Card in EUR | โฌ899 | โฌ30-45 (conversion + fees) | โฌ929-944 | +| Crypto exchange | $1,000 | $30-150 (all fees) | $1,030-1,150 | + +**๐ก Tip:** Choose payment method with minimum fees! + +**โ ๏ธ Total Amount = License Price + Taxes + All Transfer and Conversion Fees** + +### 5.3. Authorized Sellers and Dealers + +#### Official Sales Terms + +Licenses may be sold **ONLY through companies** that have **official written permission from the author**: + +**Requirements for authorized seller:** +- โ Legal entity (LLC, JSC, sole proprietor, corporation, etc.) +- โ Signed contract/agreement for dealership with author +- โ Inclusion in official list at https://hb3-accelerator.com/ +- โ Compliance with all licensing terms +- โ Record keeping of all sales +- โ Timely transfer of funds to author + +**Payment Structure Through Dealer:** +- ๐ฐ Buyer pays โ Authorized seller +- ๐ค Seller receives commission (% determined by contract) +- ๐ค Remainder transferred to author within established terms +- ๐ All payments documented officially and tracked + +#### Official Seller for Clients from Russian Federation + +For clients from the Russian Federation, the official seller of licenses is **Limited Liability Company "ERAITI" (LLC "ERAITI")** with the following details: +- **OGRN:** 1222600014383 +- **INN:** 2636220809 +- **Address:** 355007, Stavropol Territory, Stavropol, Burmistrova St., 65B, room 2 +- **Contacts:** 18900@ััะฐะนัะธ.ัั, +7 (968) 269-92-64 + +LLC "ERAITI" has official rights to sell and support Digital Legal Entity licenses in the Russian Federation. + +#### Direct Purchase from Author + +Can be purchased directly from author without intermediaries: + +- ๐ง **Email**: info@hb3-accelerator.com +- ๐ **Website**: https://hb3-accelerator.com +- ๐ **GitHub**: https://github.com/VC-HB3-Accelerator + + +### 5.4. Payment Process and Confirmation + +1. **Seller Selection**: Authorized dealer or directly from author +2. **Price Agreement**: In USDT or equivalent local currency +3. **Receiving Details**: From seller or author +4. **Sending Payment**: Cryptocurrency, bank transfer, or other method +5. **Confirmation**: Receiving payment number and payment document +6. **License Activation**: Receiving NFT token or portal access + +### 5.5. Refund and Claims + +- **Claim Period**: 30 days from payment date +- **Process**: Contact seller or author with payment confirmation +- **Refund**: Maximum 70% of amount in accordance with refund program +- **Refund Reasons**: + - Calculation error + - Double payment + - Other justified reasons + +--- + +## ๐ Additional Documentation + +### Explore DLE Capabilities +- ๐ค **[AI Assistant](../docs-en/ai-assistant.md)** - second pilot for team, frees time for strategy +- ๐ผ **[Blockchain for Business](../docs-en/blockchain-for-business.md)** - asset tokenization and business solutions +- ๐ก๏ธ **[DLE Security](../docs-en/security.md)** - multi-level protection for your business + +### Technical Documentation +- ๐ **[Blockchain Technical Documentation](../docs-en/blockchain-integration-technical.md)** - for developers +- ๐ง **[Installation Instructions](../docs-en/setup-instruction.md)** - step-by-step setup +- ๐ **[Application Description](../docs-en/application-description.md)** - functionality overview +- ๐ **[FAQ](../docs-en/FAQ.md)** - frequently asked questions + +### Contacts and Support +- ๐ง **Email**: info@hb3-accelerator.com +- ๐ **Website**: https://hb3-accelerator.com +- ๐ฌ **Support Chat**: https://hb3-accelerator.com/ +- ๐ **GitHub**: https://github.com/VC-HB3-Accelerator + diff --git a/legal/README.md b/legal/README.md index c7be73c..be503d3 100644 --- a/legal/README.md +++ b/legal/README.md @@ -1,6 +1,8 @@ # ะฎะ ะะะะงะะกะะะฏ ะะะะฃะะะะขะะฆะะฏ DLE ## ะะฐัะธัะฐ ะธะฝัะตะปะปะตะบััะฐะปัะฝะพะน ัะพะฑััะฒะตะฝะฝะพััะธ ะฟัะพะตะบัะฐ +**๐ Language / ะฏะทัะบ:** [๐ท๐บ ะ ัััะบะธะน](README.md) | [๐ฌ๐ง English](../legal-en/README.md) + ### ๐ **ะะะะะ ะะะะฃะะะะขะะ** ะญัะพั ัะฐะทะดะตะป ัะพะดะตัะถะธั ะฒัั ััะธะดะธัะตัะบัั ะดะพะบัะผะตะฝัะฐัะธั ะดะปั ะทะฐัะธัั ะธะฝัะตะปะปะตะบััะฐะปัะฝะพะน ัะพะฑััะฒะตะฝะฝะพััะธ ะฟัะพะตะบัะฐ DLE (Digital Legal Entity).