# OSchema for freezone/main # ═══════════════════════════════════════════════════════════════════════════════ # OSIS Schema Definition # ═══════════════════════════════════════════════════════════════════════════════ # # RPC Endpoint: POST /{context}/{domain}/rpc # Content-Type: application/json # # Request format (JSON-RPC 2.0): # {"jsonrpc": "2.0", "method": "TypeName.method", "params": {...}, "id": 1} # # Available CRUD methods for root objects: # - TypeName.new -> Create new object (returns empty template) # - TypeName.get -> Get by sid: {"sid": "..."} # - TypeName.set -> Create/update: {"data": ""} # - TypeName.delete -> Delete by sid: {"sid": "..."} # - TypeName.list -> List all sids # - TypeName.find -> Search: {"query": "..."} # # ═══════════════════════════════════════════════════════════════════════════════ # ===SCHEMA=== # ─────────────────────────────────────────────────────────────────────────────── # ROOT OBJECTS - Storable entities with CRUD operations # ─────────────────────────────────────────────────────────────────────────────── # ─────────────────────────────────────────────────────────────────────────────── # ROOT OBJECTS - Storable entities with CRUD operations # ─────────────────────────────────────────────────────────────────────────────── # API key for reseller access [rootobject] ApiKey = { sid: str # SmartID for storage key_hash: str @index # Hashed API key name: str @index # Key name/description user_id?: str # Optional user reference is_active: bool # Key active status last_used_at?: otime # Last usage timestamp created_at: otime expires_at?: otime # Optional expiration } # ─────────────────────────────────────────────────────────────────────────────── # BUSINESS DOCUMENTS # ─────────────────────────────────────────────────────────────────────────────── # Uploaded or generated business document [rootobject] BusinessDocument = { sid: str # SmartID for storage (doc_id) company_id: str @index # Reference to FreeZoneCompany document_type: BusinessDocumentType # Certificate, License, Memorandum, etc. name: str @index # Document name description?: str # Document description file_url?: str # URL to file content?: str # Content for generated docs is_official: bool # Whether issued by FreeZone issued_date?: otime # When document was issued expiry_date?: otime # When document expires uploaded_by?: str # Resident ID who uploaded created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # Company message entity [rootobject] CompanyMessage = { sid: str # SmartID for storage company_id: str @index # Reference to FreeZoneCompany title: str @index # Message title body: str @index # Message body/content message_type: MessageType # Type (system/notification/alert) category?: MessageCategory # Category action_url?: str # URL for action button action_label?: str # Label for action button is_read: bool # Read status created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # Business Contract entity [rootobject] Contract = { sid: str # SmartID for storage fzc_id: str @index # Reference to FreeZoneCompany name: str @index # Contract name contract_type: str @index # Contract type counterparty: str @index # Other party name status: ContractStatus # Contract status start_date: otime # Start date end_date?: otime # End date total_value?: f64 # Contract value created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # Contract Signature entity [rootobject] ContractSignature = { sid: str # SmartID for storage (signature_id) user_id: str @index # Reference to User contract_id: str @index # Reference to RegistrationContract contract_version: str # Version that was signed signature: str # JWS compact serialization public_key_id: str # Public key used for signing keypair_version: i32 # Keypair version from JWS kid signed_at: otime # Signature timestamp ip_address?: str # IP address at signing created_at: otime # Creation timestamp } # Contract Template entity [rootobject] ContractTemplate = { sid: str # SmartID for storage name: str @index # Template name description: str @index # Template description category: str @index # Template category content: str # Template content created_at: otime # Creation timestamp } # Digital Resident entity [rootobject] DigitalResident = { sid: str # SmartID for storage (internal ID) resident_id: str @index # Formatted ID like ZDFZ-2026-RA000001 user_id: str @index # Owner user reference email: str @index # Email address first_name: str @index # First name last_name: str @index # Last name kyc_provider_id: str # ID from KYC provider (iDenfy) phone: str # Phone number status: ResidentStatus # Current status public_key?: str # Ed25519 public key encrypted_private_key?: str # AES-256-GCM encrypted private key keypair_version: i32 # Keypair version number subscription_plan?: str # Subscription plan: 6_months, 1_year, 2_years, 3_years auto_renewal: bool # Whether auto-renewal is enabled subscription_start_date?: otime # When the current subscription period started subscription_end_date?: otime # When the current subscription period ends created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # Dividend distribution [rootobject] DividendDistribution = { sid: str # SmartID for storage (dividend_id) company_id: str @index # Reference to FreeZoneCompany total_amount: f64 # Total amount to distribute currency: str # Currency code source_account_id: str # Treasury account to pay from distribution_date: otime # When dividends will be paid status: DividendStatus # Proposed, Approved, Processing, Completed, Cancelled requires_vote: bool # Whether distribution requires vote proposal_id?: str # Reference to Proposal if vote required initiated_by: str # Resident ID who initiated approved_at?: otime # When distribution was approved completed_at?: otime # When distribution completed created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # Individual dividend payment [rootobject] DividendPayment = { sid: str # SmartID for storage (payment_id) distribution_id: str @index # Reference to DividendDistribution company_id: str @index # Reference to FreeZoneCompany recipient_id: str @index # Recipient resident ID ownership_percentage: f64 # Ownership % at time of distribution amount: f64 # Amount to receive currency: str # Currency code destination_account_id?: str # Treasury account to receive funds transaction_id?: str # Reference to TreasuryTransaction paid_at?: otime # When payment was made created_at: otime # Creation timestamp } # Email verification token [rootobject] EmailVerificationToken = { sid: str # SmartID for storage user_id: str @index # Reference to User token: str @index # Verification token expires_at: otime # Token expiration used: bool # Whether token was used created_at: otime } # Crypto exchange transaction [rootobject] ExchangeTransaction = { sid: str # SmartID for storage (exchange_id) owner_type: EntityType # Resident or company owner_id: str @index # Owner ID from_account_id: str @index # Source account to_account_id: str @index # Destination account from_amount: f64 # Amount being exchanged from_currency: str # Source currency to_amount: f64 # Amount received to_currency: str # Destination currency exchange_rate: f64 # Exchange rate used fee_percentage: f64 # Fee percentage fee_amount: f64 # Fee amount in from_currency status: ExchangeStatus # Pending, Processing, Completed, Failed, Expired rate_expires_at: otime # When quoted rate expires initiated_by: str @index # Resident ID who initiated completed_at?: otime # When exchange completed created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # ─────────────────────────────────────────────────────────────────────────────── # FINANCIAL REPORTS # ─────────────────────────────────────────────────────────────────────────────── # Generated financial report [rootobject] FinancialReport = { sid: str # SmartID for storage (report_id) company_id: str @index # Reference to FreeZoneCompany report_type: FinancialReportType # Balance sheet, Income statement, Cash flow, Trial balance title: str @index # Report title period_start?: otime # Start of reporting period period_end?: otime # End of reporting period as_of_date?: otime # Point-in-time date (for balance sheet) content: str # Report content (JSON or markdown) generated_by: str # Resident ID who generated created_at: otime # Creation timestamp } # Free Zone Company entity [rootobject] FreeZoneCompany = { sid: str # SmartID for storage (internal ID) company_id: str @index # Formatted ID like ZDFZ-2026-CA000001 user_id: str @index # Owner user reference name: str @index # Company name company_type: CompanyType # Type of company voting_model: VotingModel # Standard (by shares) or Cooperative (1 vote each) description: str @index # Company description registration_number: str # Official registration number tax_id: str # Tax ID address: Address # Company address (embedded) shareholders: [ShareholderData] # Rich shareholder data crypto_wallets: [CryptoWallet] # Company crypto wallets status: CompanyStatus # Company status email?: str # Contact email phone?: str # Contact phone website?: str # Company website URL industry?: str # Business sector public_key?: str # Ed25519 public key encrypted_private_key?: str # AES-256-GCM encrypted private key keypair_version: i32 # Keypair version number # Subscription fields subscription_plan?: CompanySubscriptionPlan # Monthly, 1yr, or 2yr subscription_start_date?: otime # When subscription started subscription_end_date?: otime # When subscription ends auto_renewal: bool # Whether to auto-renew # Pricing snapshot at registration setup_fee_paid: f64 # Setup fee paid (after discounts) monthly_fee_rate: f64 # Base monthly fee rate shareholder_fee_rate: f64 # Per-shareholder fee rate (0 if N/A) prepaid_discount_applied: f64 # Discount percentage applied (0.0, 0.2, or 0.4) early_bird_applied: bool # Whether early bird discount was applied created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # Free Zone Expense entity [rootobject] FreeZoneExpense = { sid: str # SmartID for storage (fz_expense_id) fzc_id: str @index # Reference to FreeZoneCompany receipt_number: str @index # Receipt number vendor_name: str @index # Vendor name description: str @index # Expense description amount: f64 # Expense amount currency: str # Currency code category: str # Expense category receipt_url?: str # URL to receipt image expense_date: otime # Expense date status: ExpenseStatus # Expense status created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # Free Zone Invoice entity [rootobject] FreeZoneInvoice = { sid: str # SmartID for storage (fz_invoice_id) fzc_id: str @index # Reference to FreeZoneCompany reseller_invoice_id: str # Reference to reseller system invoice_number: str @index # Invoice number for display amount: f64 # Total invoice amount currency: str # Currency code (USD, EUR, etc.) tax_amount: f64 # Tax amount description: str @index # Invoice description line_items: [LineItem] # List of invoice items issue_date: otime # Issue date due_date: otime # Due date status: InvoiceStatus # Invoice status created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # ─────────────────────────────────────────────────────────────────────────────── # TREASURY OPERATIONS # ─────────────────────────────────────────────────────────────────────────────── # Fund transfer between accounts [rootobject] FundTransfer = { sid: str # SmartID for storage (transfer_id) from_account_id: str @index # Source treasury account to_account_id?: str @index # Destination treasury account (internal) to_external_address?: str # External bank/wallet address to_external_name?: str # External recipient name amount: f64 # Transfer amount currency: str # Currency code reference?: str # Payment reference status: FundTransferStatus # Pending, Processing, Completed, Failed, Cancelled requires_approval: bool # Whether transfer needs approval approval_threshold: f64 # Amount above which approval is needed approved_by?: str # Resident ID who approved initiated_by: str @index # Resident ID who initiated transaction_id?: str # External transaction ID fee_amount?: f64 # Transfer fee completed_at?: otime # When transfer completed created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # KYC Session entity [rootobject] KycSession = { sid: str # SmartID for storage (session_id) user_id: str @index # Reference to User resident_id: str @index # Reference to DigitalResident public_key: str # Public key used for verification kyc_url: str # URL to KYC service status: KycStatus # Verification status idenfy_scan_ref?: str # iDenfy scan reference identity_verified: bool # Identity verification result document_verified: bool # Document verification result liveness_verified: bool # Liveness check result verification_level?: str # Verification level (basic, full, etc.) callback_url?: str # Callback URL for completion expires_at: otime # Session expiration verified_at?: otime # When verification completed created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # Payment entity for crypto/ClickPesa [rootobject] Payment = { sid: str # SmartID for storage (payment_id) user_id: str @index # Reference to User entity_id: str @index # Resident or Company ID entity_type: EntityType # Resident or Company (enum) payment_type: PaymentType # Bitcoin, Ethereum, ClickPesa amount: f64 # Amount in currency currency: str # Currency code (USD, etc.) crypto_amount?: str # Formatted crypto amount exchange_rate?: str # Exchange rate at time of payment wallet_address?: str # Destination wallet address sender_address?: str # Sender's address transaction_hash?: str # Blockchain transaction hash confirmation_count?: i32 # Block confirmations external_id: str # External payment provider ID clickpesa_order_id?: str @index # ClickPesa order ID (indexed for webhook lookup) payment_purpose: str # Purpose (resident_subscription, company_registration) subscription_plan?: str # Subscription plan if applicable auto_renewal: bool # Whether auto-renewal was requested status: PaymentStatus # Payment status expires_at: otime # Payment expiration confirmed_at?: otime # When payment was confirmed created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # ─────────────────────────────────────────────────────────────────────────────── # GOVERNANCE & VOTING # ─────────────────────────────────────────────────────────────────────────────── # Governance proposal [rootobject] Proposal = { sid: str # SmartID for storage (proposal_id) company_id: str @index # Reference to FreeZoneCompany title: str @index # Proposal title description: str # Full proposal description (markdown) category: ProposalCategory # Financial, Strategic, Operational, Governance, Personnel status: ProposalStatus # Draft, Active, Passed, Rejected, Expired, Executed proposer_id: str @index # Resident ID who created proposal voting_starts_at: otime # When voting begins voting_ends_at: otime # When voting ends quorum_percentage: i32 # Required participation percentage (0-100) passing_threshold: i32 # Required "for" percentage to pass (0-100) allow_abstention: bool # Whether abstention counts toward quorum votes_for: f64 # Total voting power for votes_against: f64 # Total voting power against votes_abstain: f64 # Total voting power abstained total_voted: f64 # Total voting power that voted resolution_id?: str # Reference to Resolution if executed created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # Historical public key for signature verification [rootobject] PublicKeyHistory = { sid: str # SmartID for storage user_id: str @index # Reference to User entity_type: EntityType # Which entity this key belonged to entity_id: str @index # Resident or Company ID public_key: str # The historical public key keypair_version: i32 # Version number of this key valid_from: otime # When this key became active valid_until: otime # When this key was replaced created_at: otime # Record creation timestamp } # Registration Contract entity [rootobject] # Note: category_str is indexed for Tantivy search; category enum provides type safety RegistrationContract = { sid: str # SmartID for storage (contract_id) name: str @index # Contract name version: str # Contract version content: str # Full contract text content_hash: str # SHA-256 hash of content required: bool # Must be signed category: RegistrationContractCategory # Contract category (enum for type safety) category_str: str @index # Category as string for Tantivy search (e.g., "digital_residency") created_at: otime # Creation timestamp } # Executed resolution from passed proposal [rootobject] Resolution = { sid: str # SmartID for storage (resolution_id) company_id: str @index # Reference to FreeZoneCompany proposal_id: str @index # Reference to original Proposal title: str @index # Resolution title description: str # Resolution description category: ProposalCategory # Category from proposal votes_for: f64 # Final votes for votes_against: f64 # Final votes against votes_abstain: f64 # Final abstentions quorum_reached: bool # Whether quorum was reached passed: bool # Whether resolution passed executed_at?: otime # When resolution was executed executed_by?: str # Who executed the resolution execution_notes?: str # Notes about execution created_at: otime # Creation timestamp } # Share transfer between shareholders [rootobject] ShareTransfer = { sid: str # SmartID for storage (transfer_id) company_id: str @index # Reference to FreeZoneCompany from_resident_id: str @index # Seller resident ID to_resident_id: str @index # Buyer resident ID percentage: f64 # Percentage being transferred reason?: str # Reason for transfer status: ShareTransferStatus # Pending, Approved, Rejected, Completed, Cancelled requires_vote: bool # Whether transfer requires shareholder vote proposal_id?: str # Reference to Proposal if vote required from_signature?: str # Seller's digital signature to_signature?: str # Buyer's digital signature approved_at?: otime # When transfer was approved completed_at?: otime # When transfer completed created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # ─────────────────────────────────────────────────────────────────────────────── # SHAREHOLDER MANAGEMENT # ─────────────────────────────────────────────────────────────────────────────── # Invitation to become shareholder [rootobject] ShareholderInvite = { sid: str # SmartID for storage (invite_id) company_id: str @index # Reference to FreeZoneCompany inviter_id: str @index # Resident ID who sent invite invitee_email: str @index # Email of invitee invitee_resident_id?: str @index # Resident ID if already a resident proposed_percentage: f64 # Proposed ownership percentage message?: str # Personal message status: ShareholderInviteStatus # Pending, Accepted, Rejected, Expired token: str @index # Unique invite token expires_at: otime # When invite expires responded_at?: otime # When invitee responded created_at: otime # Creation timestamp } # Tax document [rootobject] TaxDocument = { sid: str # SmartID for storage (doc_id) filing_id: str @index # Reference to TaxFiling company_id: str @index # Reference to FreeZoneCompany document_type: str @index # Type of tax document name: str @index # Document name content?: str # Document content (for generated docs) file_url?: str # URL if uploaded generated: bool # Whether auto-generated created_at: otime # Creation timestamp } # ─────────────────────────────────────────────────────────────────────────────── # TAX & COMPLIANCE # ─────────────────────────────────────────────────────────────────────────────── # Tax filing record [rootobject] TaxFiling = { sid: str # SmartID for storage (filing_id) company_id: str @index # Reference to FreeZoneCompany filing_type: TaxFilingPeriod # Monthly, Quarterly, Annual period_start: otime # Start of filing period period_end: otime # End of filing period due_date: otime # Filing deadline status: TaxFilingStatus # Draft, Submitted, Accepted, Rejected, Amended gross_revenue: f64 # Total revenue cost_of_goods_sold: f64 # COGS gross_profit: f64 # Gross profit operating_expenses: f64 # Operating expenses net_income: f64 # Net income before tax tax_rate: f64 # Applicable tax rate (0% for FreeZone) tax_due: f64 # Tax amount due submitted_at?: otime # When filing was submitted submitted_by?: str # Resident ID who submitted signature?: str # Digital signature created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # Treasury Account entity [rootobject] TreasuryAccount = { sid: str # SmartID for storage owner_type: EntityType # Resident or Company (enum) owner_id: str @index # Resident or Company ID name: str @index # Display name kind: TreasuryAccountKind # crypto_wallet or bank_account currency: str # Currency code balance: f64 # Current balance bank_name?: str # For bank accounts iban?: str # International bank account number account_number?: str # Account number bic?: str # Bank identifier code wallet_address?: str # For crypto wallets network?: str # Blockchain network created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # Treasury Transaction entity [rootobject] TreasuryTransaction = { sid: str # SmartID for storage account_id: str @index # Reference to TreasuryAccount timestamp: otime # Transaction timestamp tx_type: TreasuryTransactionType # Credit, debit, or transfer (enum) asset: str # Asset type amount: f64 # Transaction amount currency: str # Currency code counterparty?: str # Other party status: TreasuryTransactionStatus # Transaction status (enum) created_at: otime # Creation timestamp } # ─────────────────────────────────────────────────────────────────────────────── # BUSINESS RULES - Implemented in rpc.rs (not supported by new generator) # ─────────────────────────────────────────────────────────────────────────────── # ─────────────────────────────────────────────────────────────────────────────── # ROOT OBJECTS - Storable entities with CRUD operations [rootobject] # ─────────────────────────────────────────────────────────────────────────────── # User account for authentication [rootobject] User = { sid: str # SmartID for storage email: str @index # Email address (unique) password_hash: str # Argon2id hashed password first_name?: str @index # First name last_name?: str @index # Last name is_active: bool # Account active status email_verified: bool # Email verification status email_verified_at?: otime # When email was verified kyc_verified: bool # KYC verification status kyc_verified_at?: otime # When KYC was verified public_key?: str # Ed25519 public key for signing encrypted_private_key?: str # AES-256-GCM encrypted private key keypair_version: i32 # Keypair version number created_at: otime # Account creation timestamp updated_at: otime # Last update timestamp } # User Keypair entity for storing encrypted keys [rootobject] UserKeypair = { sid: str # SmartID for storage user_id: str @index # Reference to User entity_type: EntityType # Resident or Company (enum) entity_id: str @index # Resident or Company ID public_key: str # Ed25519 public key encrypted_private_key: str # AES-256-GCM encrypted private key version: i32 # Keypair version number is_current: bool # Whether this is the current keypair created_at: otime # Creation timestamp } # User message entity [rootobject] UserMessage = { sid: str # SmartID for storage user_id: str @index # Reference to User title: str @index # Message title body: str @index # Message body/content message_type: MessageType # Type (system/notification/alert) category?: MessageCategory # Category action_url?: str # URL for action button action_label?: str # Label for action button is_read: bool # Read status created_at: otime # Creation timestamp updated_at: otime # Last update timestamp } # Verification Link for Tier 3 access [rootobject] VerificationLink = { sid: str # SmartID for storage (link_id) user_id: str @index # Owner user reference resident_id?: str @index # Reference to DigitalResident company_id?: str @index # Reference to FreeZoneCompany token: str @index # Unique verification token label?: str # User-defined label expires_at: otime # Link expiration single_use: bool # Whether link is single-use use_count: i32 # Number of times used status: VerificationLinkStatus # Link status first_used_at?: otime # First usage timestamp last_used_at?: otime # Last usage timestamp created_at: otime # Creation timestamp } # Individual vote on a proposal [rootobject] Vote = { sid: str # SmartID for storage (vote_id) proposal_id: str @index # Reference to Proposal company_id: str @index # Reference to FreeZoneCompany voter_id: str @index # Resident ID of voter vote_value: VoteValue # For, Against, Abstain voting_power: f64 # Voter's voting power at time of vote comment?: str # Optional comment signature: str # Digital signature of vote created_at: otime # When vote was cast } # ─────────────────────────────────────────────────────────────────────────────── # EMBEDDED TYPES - Complex types used within root objects # ─────────────────────────────────────────────────────────────────────────────── # ─────────────────────────────────────────────────────────────────────────────── # EMBEDDED TYPES - Complex types used within root objects # ─────────────────────────────────────────────────────────────────────────────── AcceptInviteResult = { success: bool company_id: str percentage: f64 } ActivateResult = { activated: bool message: str } # ─────────────────────────────────────────────────────────────────────────────── # EMBEDDED TYPES - Nested structures (no sid field) # ─────────────────────────────────────────────────────────────────────────────── # Physical address Address = { street: str city: str state: str postal_code: str country: str } # All pricing configurations AllPricingConfig = { company_types: [CompanyPricingConfig] resident_monthly_fee: f64 early_bird_discount: f64 # 0.20 = 20% one_year_discount: f64 # 0.20 = 20% two_year_discount: f64 # 0.40 = 40% } ApiKeyError = { code: str message: str } # API key service types ApiKeyResult = { api_key: str expires_at: otime } # ═══════════════════════════════════════════════════════════════════════════════ # ADDITIONAL RESULT AND DATA TYPES # Added to support generated RPC handlers # ═══════════════════════════════════════════════════════════════════════════════ # API Key service types ApiKeysListResult = { api_keys: [ApiKey] } AuthError = { code: str message: str } # ─────────────────────────────────────────────────────────────────────────────── # SERVICE REQUEST/RESPONSE TYPES # ─────────────────────────────────────────────────────────────────────────────── # Auth service types AuthResult = { token: str # Access token (JWT, short-lived ~15min) refresh_token: str # Refresh token (JWT, long-lived ~7days) token_type: str # "Bearer" expires_in: i64 # Access token expiry in seconds user: UserInfo # User information } BalanceResult = { account_id: str balance: str currency: str } BusinessDocumentDetailResult = { document_id: str company_id: str document_type: BusinessDocumentType name: str description?: str file_url?: str is_official: bool issued_date?: otime expiry_date?: otime created_at: otime } BusinessDocumentError = { code: str message: str } BusinessDocumentListResult = { documents: [BusinessDocumentDetailResult] } # Business document service types BusinessDocumentResult = { document_id: str document_type: BusinessDocumentType } ChangePasswordResult = { success: bool message: str } ClickPesaResult = { payment_id: str order_id: str payment_url: str status: PaymentStatus expires_at: otime } ClickPesaWebhookData = { event: str order_id: str reference: str amount: f64 currency: str status: str payment_method?: str transaction_id?: str paid_at?: otime checksum?: str } # Company service types CompaniesListResult = { companies: [FreeZoneCompany] total: i32 page: i32 page_size: i32 } CompanyCardResult = { company_id: str name: str company_type: CompanyType status: CompanyStatus established: otime public_key?: str keypair_version?: i32 } # Company service types CompanyCreateData = { name: str company_type: CompanyType resident_id: str trading_name?: str description?: str } CompanyError = { code: str message: str } # Company pricing configuration (for display) CompanyPricingConfig = { company_type: CompanyType setup_fee: f64 monthly_fee: f64 max_shareholders: i32 has_shareholder_fee: bool shareholder_tiers: [ShareholderFeeTier] # Empty if no per-shareholder fee } CompanyPricingResult = { registration_fee: f64 annual_fee: f64 currency: str company_type: CompanyType } CompanyResult = { company: FreeZoneCompany } CompanyUpdateData = { name?: str trading_name?: str description?: str status?: CompanyStatus } CompanyVerificationResult = { valid: bool company_id: str status: CompanyStatus verified_at: otime has_full_access: bool name?: str company_type?: CompanyType established?: otime public_key?: str keypair_version?: i32 verified_by?: str } ConfirmResetResult = { success: bool } # Contract service types ContractCreateData = { title: str content: str contract_type: str parties: [str] } ContractError = { code: str message: str } ContractResult = { contract: Contract } # Contract service types ContractsListResult = { contracts: [Contract] } CreateCompanyData = { name: str company_type: CompanyType description: str address: Address shareholders: [ShareholderData] email?: str phone?: str website?: str industry?: str # Subscription fields subscription_plan: CompanySubscriptionPlan # Monthly, 1yr, or 2yr auto_renewal: bool # Whether to auto-renew apply_early_bird: bool # Whether to apply early bird discount # Password for company keypair encryption password: str # Password to encrypt company's Ed25519 keypair } CreateContractData = { name: str contract_type: str counterparty: str start_date: otime end_date?: otime total_value?: f64 } CreateExpenseData = { receipt_number: str vendor_name: str description: str amount: f64 currency: str category: str receipt_url?: str expense_date: otime } CreateInvoiceData = { invoice_number: str amount: f64 currency: str tax_amount: f64 description: str line_items: [LineItem] issue_date: otime due_date: otime } CreateLinkResult = { link_id: str token: str verification_url: str expires_at: otime single_use: bool } CreateResidentData = { email: str first_name: str last_name: str phone: str kyc_provider_id?: str } CreateTreasuryAccountData = { name: str kind: TreasuryAccountKind currency: str bank_name?: str iban?: str account_number?: str bic?: str wallet_address?: str network?: str } # Crypto wallet for companies CryptoWallet = { public_key: str # Blockchain address chain: str # Blockchain network (bitcoin, ethereum, etc.) label: str # User-friendly name } DeleteBusinessDocumentResult = { success: bool } DeleteLinksResult = { deleted_count: i64 } DeleteResult = { success: bool message: str } DirectorData = { resident_id: str position: str appointed_date?: otime } DividendDetailResult = { dividend_id: str company_id: str total_amount: f64 currency: str distribution_date: otime status: DividendStatus created_at: otime } DividendDistributionListResult = { distributions: [DividendDistribution] } # Treasury operations types (aliases for generator compatibility) DividendDistributionResult = { distribution: DividendDistribution } DividendListResult = { dividends: [DividendDetailResult] } DividendPaymentListResult = { payments: [DividendPayment] } DividendPaymentResult = { payment: DividendPayment } DividendResult = { dividend_id: str status: DividendStatus } EmailError = { code: str message: str } ExchangeDetailResult = { exchange_id: str from_amount: f64 from_currency: str to_amount: f64 to_currency: str exchange_rate: f64 status: ExchangeStatus created_at: otime } ExchangeListResult = { exchanges: [ExchangeDetailResult] } ExchangeQuoteResult = { from_currency: str to_currency: str from_amount: f64 to_amount: f64 exchange_rate: f64 fee_percentage: f64 fee_amount: f64 expires_at: otime } ExchangeResult = { exchange_id: str status: ExchangeStatus } ExchangeTransactionListResult = { exchanges: [ExchangeTransaction] } ExchangeTransactionResult = { exchange: ExchangeTransaction } ExpenseResult = { expense: FreeZoneExpense } # Expense service types ExpensesListResult = { expenses: [FreeZoneExpense] } # ─────────────────────────────────────────────────────────────────────────────── # PRICING TYPES - Company pricing and subscription # ─────────────────────────────────────────────────────────────────────────────── # Fee breakdown for a single fee component FeeBreakdown = { base: f64 # Base amount before discounts months: i32 # Number of months (for recurring fees) quantity: i32 # Quantity (e.g., shareholder count) subtotal: f64 # base * months * quantity discount: f64 # Discount amount discount_label: str # e.g., "Early Bird (20%)" or "1 Year Prepaid (20%)" final: f64 # Final amount after discount } FinancialReportDetailResult = { report_id: str company_id: str report_type: FinancialReportType title: str period_start?: otime period_end?: otime as_of_date?: otime content: str created_at: otime } FinancialReportListResult = { reports: [FinancialReportDetailResult] } # Report service types FinancialReportResult = { report_id: str report_type: FinancialReportType } FundTransferDetailResult = { transfer_id: str from_account_id: str to_account_id?: str to_external_address?: str amount: f64 currency: str status: FundTransferStatus created_at: otime } FundTransferListResult = { transfers: [FundTransferDetailResult] } # Treasury operations service types FundTransferResult = { transfer_id: str status: FundTransferStatus } GovernanceError = { code: str message: str } # iDenfy document data extracted from verification IdenfyDocumentData = { doc_first_name?: str doc_last_name?: str doc_dob?: str # Date of birth (YYYY-MM-DD) doc_nationality?: str doc_number?: str # Document number doc_type?: str # PASSPORT, ID_CARD, etc. doc_expiry?: str } IdenfyWebhookData = { client_id: str scan_ref: str status: IdenfyWebhookStatus data?: IdenfyDocumentData } # iDenfy webhook status IdenfyWebhookStatus = { overall: str # Overall verification result auto_document?: str # Automatic document check auto_face?: str # Automatic face check manual_document?: str # Manual document review manual_face?: str # Manual face review } # Verification service types IndividualVerificationResult = { valid: bool resident_id: str status: ResidentStatus verified_at: otime has_full_access: bool name?: str member_since?: otime public_key?: str keypair_version?: i32 verified_by?: str } InviteDetailResult = { invite_id: str company_id: str invitee_email: str proposed_percentage: f64 status: ShareholderInviteStatus expires_at: otime created_at: otime } InviteListResult = { invites: [InviteDetailResult] } # Shareholder service types InviteResult = { invite_id: str token: str status: ShareholderInviteStatus } # Invoice service types InvoiceCreateData = { client_name: str client_email: str items: [InvoiceLineItem] due_date: otime notes?: str } InvoiceError = { code: str message: str } # Invoice line item for creating invoices InvoiceLineItem = { description: str quantity: i32 unit_price: f64 tax_rate?: f64 } InvoiceResult = { invoice: FreeZoneInvoice } InvoiceTotalsResult = { subtotal: f64 tax: f64 total: f64 currency: str } InvoiceUpdateData = { client_name?: str client_email?: str due_date?: otime notes?: str status?: InvoiceStatus } # Invoice service types InvoicesListResult = { invoices: [FreeZoneInvoice] } KeyStatusResult = { has_keypair: bool public_key?: str keypair_version?: i32 } KeypairError = { code: str message: str } # Keypair service types KeypairResult = { public_key: str keypair_version: i32 } KycCompleteResult = { complete: bool verified_at?: otime } KycConfirmData = { identity_verified: bool document_verified: bool liveness_verified: bool verification_level: str } KycConfirmResult = { success: bool resident_activated: bool } KycError = { code: str message: str } # KYC service types KycSessionResult = { kyc_url: str session_id: str expires_at: otime } KycStatusResult = { session_id: str status: KycStatus verified_at?: otime verification_data?: KycVerificationData } # KYC service types KycUserStatusResult = { user_id: str status: KycStatus verified: bool verified_at?: otime } # KYC verification data KycVerificationData = { identity_verified: bool document_verified: bool liveness_verified: bool verification_level: str } # Invoice line item LineItem = { description: str # Item description quantity: i32 # Quantity ordered unit_price: f64 # Price per unit amount: f64 # Total amount (quantity * unit_price) } LinkError = { code: str message: str } LoginResult = { token: str refresh_token: str user_id: str expires_at: otime } LogoutResult = { success: bool } # Message service types MarkAllReadResult = { count: i32 } MarkReadResult = { success: bool marked_count: i32 } MessageError = { code: str message: str } MessageResult = { message: UserMessage } # Message service types MessagesListResult = { messages: [UserMessage] } PaymentCompleteResult = { complete: bool payment_id?: str } PaymentConfirmResult = { payment_id: str status: PaymentStatus confirmed_at?: otime amount_received?: f64 transaction_hash?: str confirmation_count?: i32 } # Payment service types PaymentCreateData = { amount: str currency: str payment_method: PaymentMethod description?: str } PaymentError = { code: str message: str } PaymentInvoiceResult = { invoice_id: str payment_url: str expires_at: otime } PaymentResult = { payment: Payment } PaymentVerifyResult = { verified: bool status: PaymentStatus } # Payment service types PaymentWalletResult = { wallet_address: str payment_type: PaymentType amount: f64 currency: str crypto_amount: str exchange_rate: str payment_id: str expires_at: otime external_id: str } PaymentsListResult = { payments: [Payment] } # Complete pricing breakdown for company registration PricingBreakdown = { company_type: CompanyType subscription_plan: CompanySubscriptionPlan shareholder_count: i32 early_bird: bool setup_fee: FeeBreakdown monthly_fee: FeeBreakdown shareholder_fee?: FeeBreakdown # Only for Global/Cooperative total: f64 # Total amount to pay effective_monthly: f64 # Effective monthly rate } # Pricing error PricingError = { code: str message: str } PricingItem = { item_type: str quantity: i32 unit_price: f64 } PricingPlan = { name: str price: f64 currency: str features: [str] } # Pricing service types PricingPlansResult = { plans: [PricingPlan] } # Pricing calculation result PricingResult = { breakdown: PricingBreakdown } PricingTotalResult = { subtotal: f64 tax: f64 total: f64 currency: str } PrivateKeyResult = { private_key: str } ProposalDetailResult = { proposal_id: str company_id: str title: str description: str category: ProposalCategory status: ProposalStatus proposer_id: str voting_starts_at: otime voting_ends_at: otime quorum_percentage: i32 passing_threshold: i32 votes_for: f64 votes_against: f64 votes_abstain: f64 total_voted: f64 quorum_reached: bool created_at: otime } ProposalListResult = { proposals: [ProposalDetailResult] } # Governance service types ProposalResult = { proposal_id: str status: ProposalStatus } # Public key history types PublicKeyHistoryListResult = { history: [PublicKeyHistory] } # Public key history types PublicKeyHistoryResult = { keys: [PublicKeyHistory] current_version: i32 } RefreshResult = { token: str refresh_token: str expires_at: otime } # Auth service types RegisterResult = { user_id: str email: str verification_sent: bool } RegistrationContractResult = { contract: RegistrationContract } # ─────────────────────────────────────────────────────────────────────────────── # ERROR TYPES # ─────────────────────────────────────────────────────────────────────────────── RegistrationError = { code: str message: str } # Registration service types RegistrationStatusResult = { user_id: str entity_type: EntityType status: RegistrationFlowStatus contracts_signed: bool payment_complete: bool kyc_complete: bool } RejectInviteResult = { success: bool } ReportError = { code: str message: str } RequiredContractsResult = { contracts: [RegistrationContract] entity_type: EntityType } ResendResult = { sent: bool } ResetPasswordResult = { sent: bool } ResidentCardResult = { resident_id: str name: str status: ResidentStatus member_since: otime public_key?: str keypair_version?: i32 } # Resident service types ResidentCreateData = { user_id: str first_name: str last_name: str nationality: str date_of_birth?: otime } ResidentError = { code: str message: str } ResidentPricingResult = { registration_fee: f64 annual_fee: f64 currency: str } ResidentResult = { resident: DigitalResident } ResidentUpdateData = { first_name?: str last_name?: str nationality?: str address?: str } # Resident service types ResidentsListResult = { residents: [DigitalResident] total: i32 page: i32 page_size: i32 } ResolutionDetailResult = { resolution_id: str company_id: str proposal_id: str title: str category: ProposalCategory votes_for: f64 votes_against: f64 quorum_reached: bool passed: bool executed_at?: otime created_at: otime } ResolutionListResult = { resolutions: [ResolutionDetailResult] } ResolutionResult = { resolution_id: str proposal_id: str passed: bool } # Keypair service types RevokeKeypairResult = { revoked: bool } RevokeLinkResult = { revoked: bool } RevokeResult = { success: bool message: str } ShareTransferListResult = { transfers: [ShareTransfer] } ShareTransferResult = { transfer: ShareTransfer } # Shareholder data with ownership percentage ShareholderData = { resident_id: str # Reference to DigitalResident name: str # Full name of shareholder percentage: f64 # Ownership percentage (0-100) } ShareholderError = { code: str message: str } # Shareholder fee rate result ShareholderFeeRateResult = { rate: f64 tier_label: str # e.g., "3-5 shareholders" } # Shareholder fee tier (for tiered pricing) ShareholderFeeTier = { max_count: i32 # Maximum shareholder count for this tier rate: f64 # Rate per shareholder per month } ShareholderInviteListResult = { invites: [ShareholderInvite] } # Shareholder service types (aliases for generator compatibility) ShareholderInviteResult = { invite: ShareholderInvite } ShareholderResult = { shareholder_id: str resident_id: str company_id: str ownership_percentage: f64 } SignContractResult = { signature_id: str contract_id: str signed_at: otime signature: str } SignError = { code: str message: str } SignResult = { signature: str signed_at: otime signer_id: str keypair_version: i32 } SignaturesListResult = { signatures: [ContractSignature] } SignedDocumentsResult = { documents: [ContractSignature] } SubscriptionResult = { success: bool plan: str auto_renewal: bool subscription_end_date?: otime } TallyResult = { proposal_id: str votes_for: f64 votes_against: f64 votes_abstain: f64 total_voted: f64 quorum_reached: bool passed: bool status: ProposalStatus } # Tax service types TaxCalculationResult = { gross_revenue: f64 deductions: f64 taxable_income: f64 tax_rate: f64 tax_due: f64 currency: str } TaxDeadlineItem = { filing_type: TaxFilingPeriod period_start: otime period_end: otime due_date: otime status: str } TaxDeadlineResult = { deadlines: [TaxDeadlineItem] } TaxDocumentDetailResult = { document_id: str filing_id: str document_type: str name: str generated: bool created_at: otime } TaxDocumentListResult = { documents: [TaxDocumentDetailResult] } TaxDocumentResult = { document_id: str name: str } TaxError = { code: str message: str } TaxFilingDetailResult = { filing_id: str company_id: str filing_type: TaxFilingPeriod period_start: otime period_end: otime due_date: otime status: TaxFilingStatus gross_revenue: f64 cost_of_goods_sold: f64 gross_profit: f64 operating_expenses: f64 net_income: f64 tax_rate: f64 tax_due: f64 created_at: otime } TaxFilingListResult = { filings: [TaxFilingDetailResult] } # Tax service types TaxFilingResult = { filing_id: str status: TaxFilingStatus } TemplateResult = { template: ContractTemplate } TemplatesListResult = { templates: [ContractTemplate] } TransactionResult = { transaction: TreasuryTransaction } TransactionsListResult = { transactions: [TreasuryTransaction] } TransferDetailResult = { transfer_id: str company_id: str from_resident_id: str to_resident_id: str percentage: f64 status: ShareTransferStatus requires_vote: bool created_at: otime } TransferListResult = { transfers: [TransferDetailResult] } TransferResult = { transfer_id: str status: ShareTransferStatus } TreasuryAccountResult = { account: TreasuryAccount } # Treasury service types TreasuryAccountsListResult = { accounts: [TreasuryAccount] } # Treasury service types TreasuryAccountsResult = { accounts: [TreasuryAccount] } TreasuryError = { code: str message: str } TreasuryOperationsError = { code: str message: str } TreasuryTransactionsResult = { transactions: [TreasuryTransaction] } UnreadCountResult = { count: i32 } # Document service types UnsignedDocumentsResult = { documents: [RegistrationContract] } UpdateCompanyData = { name?: str description?: str address?: Address shareholders?: [ShareholderData] email?: str phone?: str website?: str industry?: str status?: CompanyStatus } UpdateContractData = { name?: str counterparty?: str status?: ContractStatus end_date?: otime total_value?: f64 } UpdateExpenseData = { receipt_number?: str vendor_name?: str description?: str amount?: f64 currency?: str category?: str receipt_url?: str expense_date?: otime status?: ExpenseStatus } UpdateInvoiceData = { amount?: f64 tax_amount?: f64 description?: str line_items?: [LineItem] due_date?: otime status?: InvoiceStatus } UpdateResidentData = { first_name?: str last_name?: str phone?: str status?: ResidentStatus } UpdateTreasuryAccountData = { name?: str bank_name?: str iban?: str account_number?: str bic?: str } UserInfo = { id: str email: str first_name?: str last_name?: str is_active: bool email_verified: bool kyc_verified: bool kyc_verified_at?: otime } ValidationResult = { valid: bool reseller_id?: str permissions: [str] } VerificationError = { code: str message: str } # Verification service types VerificationLinkResult = { link: VerificationLink } VerificationLinksListResult = { links: [VerificationLink] } # Verification service additional types VerificationLinksResult = { links: [VerificationLink] } VerifyAllSignedResult = { all_signed: bool unsigned_count: i32 } VerifyByTokenResult = { valid: bool entity_type: EntityType entity_id: str status: str verified_at: otime has_full_access: bool name?: str public_key?: str keypair_version?: i32 member_since?: otime } VerifyEmailResult = { success: bool message: str } VerifyError = { code: str message: str } VerifyLinkResult = { valid: bool user_id?: str company_id?: str permissions: [str] } VerifyResult = { valid: bool signer_id: str signature_keypair_version: i32 current_keypair_version: i32 is_historical_key: bool document_type?: DocumentType document_hash?: str signed_at?: otime error?: str } # Governance service types VoteListResult = { votes: [Vote] } VoteResult = { vote_id: str proposal_id: str vote_value: VoteValue voting_power: f64 } VotingPowerResult = { resident_id: str company_id: str voting_power: f64 voting_model: VotingModel shareholding_percentage: f64 } WebhookError = { code: str message: str } WebhookResult = { success: bool message: str } # ─────────────────────────────────────────────────────────────────────────────── # RPC SERVICES - Custom business logic methods # ─────────────────────────────────────────────────────────────────────────────── # ─────────────────────────────────────────────────────────────────────────────── # RPC SERVICES - Custom business logic methods # ─────────────────────────────────────────────────────────────────────────────── service ApiKeyService { version: "1.0.0" description: "API key management for resellers" # Generate API key generate(client_id: str, client_secret: str, access_password: str) -> ApiKeyResult error: ApiKeyError } # ─────────────────────────────────────────────────────────────────────────────── # RPC SERVICES - Custom business logic (beyond CRUD) # ─────────────────────────────────────────────────────────────────────────────── service AuthService { version: "1.0.0" description: "User authentication and session management" # Register a new user register(email: str, password: str, first_name?: str, last_name?: str) -> AuthResult error: RegistrationError # Login user and return JWT token login(email: str, password: str) -> AuthResult error: AuthError # Refresh JWT token refresh_token(token: str) -> AuthResult error: AuthError # Send email verification send_verification_email(email: str) -> VerifyEmailResult error: EmailError # Verify email with token verify_email(token: str) -> VerifyEmailResult error: EmailError # Change password change_password(user_id: str, old_password: str, new_password: str) -> ChangePasswordResult error: AuthError } service BusinessDocumentService { version: "1.0.0" description: "Business document management" # Upload document upload_document(company_id: str, document_type: BusinessDocumentType, name: str, description?: str, file_url: str, uploaded_by: str) -> BusinessDocumentResult error: BusinessDocumentError # Generate official document generate_official_document(company_id: str, document_type: BusinessDocumentType) -> BusinessDocumentResult error: BusinessDocumentError # Get document get_document(document_id: str) -> BusinessDocumentDetailResult error: BusinessDocumentError # List documents for a company list_documents(company_id: str, document_type?: BusinessDocumentType) -> BusinessDocumentListResult error: BusinessDocumentError # Delete document (non-official only) delete_document(document_id: str) -> DeleteBusinessDocumentResult error: BusinessDocumentError } service CompanyService { version: "1.0.0" description: "Free zone company management" # List companies for user with pagination list(user_id: str, page: i32, page_size: i32) -> CompaniesListResult error: CompanyError # Create a new company create(user_id: str, data: CreateCompanyData) -> CompanyResult error: CompanyError # Get company by ID get(company_id: str) -> CompanyResult error: CompanyError # Update company update(company_id: str, data: UpdateCompanyData) -> CompanyResult error: CompanyError # Delete company delete(company_id: str) -> DeleteResult error: CompanyError # Get company card (public display info) get_card(company_id: str) -> CompanyCardResult error: CompanyError # Get company key status get_key_status(company_id: str) -> KeyStatusResult error: KeypairError # View company private key view_private_key(company_id: str, password: str) -> PrivateKeyResult error: KeypairError # Regenerate company keypair regenerate_keypair(company_id: str, password: str) -> KeypairResult error: KeypairError # Change company keypair password change_password(company_id: str, current_password: str, new_password: str) -> ChangePasswordResult error: KeypairError } service ContractService { version: "1.0.0" description: "Business contracts and templates" # List company contracts list_company_contracts(fzc_id: str) -> ContractsListResult error: ContractError # Get company contract get_company_contract(fzc_id: str, contract_id: str) -> ContractResult error: ContractError # Create company contract create_company_contract(fzc_id: str, data: CreateContractData) -> ContractResult error: ContractError # Update company contract update_company_contract(fzc_id: str, contract_id: str, data: UpdateContractData) -> ContractResult error: ContractError # Archive company contract archive_company_contract(fzc_id: str, contract_id: str) -> ContractResult error: ContractError # List contract templates list_templates() -> TemplatesListResult error: ContractError # Get contract template get_template(template_id: str) -> TemplateResult error: ContractError # Get required registration contracts get_required_contracts(entity_type: EntityType) -> RequiredContractsResult error: ContractError # Sign contract sign_contract(user_id: str, contract_id: str, password: str) -> SignContractResult error: SignError # Get contract signatures for user get_signatures(user_id: str) -> SignaturesListResult error: ContractError } service DocumentService { version: "1.0.0" description: "Document signing and verification" # Sign document sign(entity_type: EntityType, entity_id: str, document_type: DocumentType, document_content: str, password: str) -> SignResult error: SignError # Verify document signature verify(signature: str, signer_id: str, signer_type: EntityType) -> VerifyResult error: VerifyError # Get key status get_key_status(user_id: str) -> KeyStatusResult error: KeypairError } service ExpenseService { version: "1.0.0" description: "Expense management for companies" # List expenses for company list(fzc_id: str) -> ExpensesListResult error: InvoiceError # Create expense create(fzc_id: str, data: CreateExpenseData) -> ExpenseResult error: InvoiceError # Get expense by ID get(expense_id: str) -> ExpenseResult error: InvoiceError # Update expense update(expense_id: str, data: UpdateExpenseData) -> ExpenseResult error: InvoiceError # Delete expense delete(fzc_id: str, expense_id: str) -> DeleteResult error: InvoiceError # Submit expense for approval submit(expense_id: str) -> ExpenseResult error: InvoiceError # Approve expense approve(expense_id: str, approved_by: str) -> ExpenseResult error: InvoiceError # Reject expense reject(expense_id: str, rejected_by: str, reason: str) -> ExpenseResult error: InvoiceError } service GovernanceService { version: "1.0.0" description: "Proposal creation, voting, and resolution management" # Create a new proposal create_proposal(company_id: str, title: str, description: str, category: ProposalCategory, voting_days: i32, quorum_percentage: i32, passing_threshold: i32, allow_abstention: bool) -> ProposalResult error: GovernanceError # Get proposal details get_proposal(proposal_id: str) -> ProposalDetailResult error: GovernanceError # List proposals for a company list_proposals(company_id: str, status?: ProposalStatus) -> ProposalListResult error: GovernanceError # Cast a vote on a proposal cast_vote(proposal_id: str, voter_id: str, vote_value: VoteValue, comment?: str, password: str) -> VoteResult error: GovernanceError # Get voting power for a shareholder get_voting_power(company_id: str, resident_id: str) -> VotingPowerResult error: GovernanceError # Tally votes and update proposal status tally_votes(proposal_id: str) -> TallyResult error: GovernanceError # Execute a passed proposal (create resolution) execute_proposal(proposal_id: str, executor_id: str, notes?: str) -> ResolutionResult error: GovernanceError # List resolutions for a company list_resolutions(company_id: str) -> ResolutionListResult error: GovernanceError } service InvoiceService { version: "1.0.0" description: "Invoice management for companies" # List invoices for company list(fzc_id: str) -> InvoicesListResult error: InvoiceError # Create invoice create(fzc_id: str, data: CreateInvoiceData) -> InvoiceResult error: InvoiceError # Get invoice by ID get(invoice_id: str) -> InvoiceResult error: InvoiceError # Update invoice update(invoice_id: str, data: UpdateInvoiceData) -> InvoiceResult error: InvoiceError # Delete invoice delete(fzc_id: str, invoice_id: str) -> DeleteResult error: InvoiceError } service KeypairService { version: "1.0.0" description: "Digital identity and cryptographic signing" # Generate new keypair for entity generate_keypair(entity_type: EntityType, entity_id: str, password: str) -> KeypairResult error: KeypairError # Sign document sign_document(entity_type: EntityType, entity_id: str, document_type: DocumentType, document_content: str, password: str) -> SignResult error: SignError # Verify signature verify_signature(signature: str, signer_id: str, signer_type: EntityType) -> VerifyResult error: VerifyError # View private key (requires password) view_private_key(entity_type: EntityType, entity_id: str, password: str) -> PrivateKeyResult error: KeypairError # Regenerate keypair regenerate_keypair(entity_type: EntityType, entity_id: str, password: str) -> KeypairResult error: KeypairError } service KycService { version: "1.0.0" description: "KYC verification management" # Start KYC verification session start_verification(resident_id: str, public_key: str, callback_url?: str) -> KycSessionResult error: KycError # Check KYC status check_status(session_id: str) -> KycStatusResult error: KycError # Handle iDenfy webhook handle_idenfy_webhook(data: IdenfyWebhookData) -> WebhookResult error: WebhookError } service MessageService { version: "1.0.0" description: "User and company messaging" # List user messages with filtering list_user_messages(user_id: str, category?: MessageCategory, is_read?: bool) -> MessagesListResult error: MessageError # Get user message get_user_message(user_id: str, message_id: str) -> MessageResult error: MessageError # Get unread count get_unread_count(user_id: str) -> UnreadCountResult error: MessageError # Mark message as read mark_as_read(user_id: str, message_id: str) -> MarkReadResult error: MessageError # Mark message as unread mark_as_unread(user_id: str, message_id: str) -> MarkReadResult error: MessageError # Mark all as read mark_all_read(user_id: str) -> MarkReadResult error: MessageError # Mark all as unread mark_all_unread(user_id: str) -> MarkReadResult error: MessageError # Delete message delete_message(user_id: str, message_id: str) -> DeleteResult error: MessageError # Create system message (admin) create_system_message(user_id: str, title: str, body: str, category?: MessageCategory, action_url?: str) -> MessageResult error: MessageError # List company messages list_company_messages(company_id: str) -> MessagesListResult error: MessageError # Create company message create_company_message(company_id: str, title: str, body: str, category?: MessageCategory) -> MessageResult error: MessageError # Mark company message as read mark_company_read(company_id: str, message_id: str) -> MarkReadResult error: MessageError # Mark company message as unread mark_company_unread(company_id: str, message_id: str) -> MarkReadResult error: MessageError # Mark all company messages read mark_all_company_read(company_id: str) -> MarkReadResult error: MessageError # Mark all company messages unread mark_all_company_unread(company_id: str) -> MarkReadResult error: MessageError } service PaymentService { version: "1.0.0" description: "Payment processing for residents and companies" # Get crypto wallet address for payment get_payment_wallet(resident_id: str, payment_type: PaymentType, amount: f64, currency: str) -> PaymentWalletResult error: PaymentError # Confirm payment confirm_payment(payment_id: str, sender_address?: str, transaction_hash?: str) -> PaymentConfirmResult error: PaymentError # Initiate ClickPesa payment initiate_clickpesa(entity_id: str, entity_type: EntityType, amount: f64, currency: str, description: str, payment_purpose: str, subscription_plan?: str) -> ClickPesaResult error: PaymentError # Handle ClickPesa webhook handle_clickpesa_webhook(data: ClickPesaWebhookData) -> WebhookResult error: WebhookError } service PricingService { version: "1.0.0" description: "Pricing calculation for residents and companies" # Calculate company registration pricing calculate_company_pricing(company_type: CompanyType, shareholder_count: i32, subscription_plan: CompanySubscriptionPlan, early_bird: bool) -> PricingResult error: PricingError # Get all pricing configurations (for display) get_all_pricing() -> AllPricingConfig error: PricingError # Get shareholder fee rate for a company type and count get_shareholder_fee_rate(company_type: CompanyType, shareholder_count: i32) -> ShareholderFeeRateResult error: PricingError } service PublicKeyHistoryService { version: "1.0.0" description: "Historical public key management for signature verification" # Get key history for an entity get_history(entity_type: EntityType, entity_id: str) -> PublicKeyHistoryResult error: KeypairError # Get specific historical key by version get_by_version(entity_type: EntityType, entity_id: str, version: i32) -> PublicKeyHistory error: KeypairError # Verify signature with historical key lookup verify_with_history(signature: str, entity_type: EntityType, entity_id: str) -> VerifyResult error: VerifyError } service RegistrationService { version: "1.0.0" description: "Registration flow management" # Get registration status get_status(user_id: str, entity_type: EntityType) -> RegistrationStatusResult error: RegistrationError # Update registration status update_status(user_id: str, entity_type: EntityType, status: RegistrationFlowStatus) -> RegistrationStatusResult error: RegistrationError # Check if resident payment is complete check_payment_complete(user_id: str) -> PaymentCompleteResult error: RegistrationError # Check if user KYC is complete check_kyc_complete(user_id: str) -> KycCompleteResult error: RegistrationError # Activate resident if all requirements met activate_if_complete(user_id: str) -> ActivateResult error: RegistrationError # Confirm KYC (internal) confirm_kyc(user_id: str, resident_id: str, data: KycConfirmData) -> KycConfirmResult error: KycError } service ReportService { version: "1.0.0" description: "Financial report generation" # Generate balance sheet generate_balance_sheet(company_id: str, as_of_date: otime, generated_by: str) -> FinancialReportResult error: ReportError # Generate income statement generate_income_statement(company_id: str, period_start: otime, period_end: otime, generated_by: str) -> FinancialReportResult error: ReportError # Generate cash flow statement generate_cash_flow(company_id: str, period_start: otime, period_end: otime, generated_by: str) -> FinancialReportResult error: ReportError # Generate trial balance generate_trial_balance(company_id: str, as_of_date: otime, generated_by: str) -> FinancialReportResult error: ReportError # Get report get_report(report_id: str) -> FinancialReportDetailResult error: ReportError # List reports for a company list_reports(company_id: str, report_type?: FinancialReportType) -> FinancialReportListResult error: ReportError } service ResidentService { version: "1.0.0" description: "Digital resident management" # List residents with pagination list(user_id: str, page: i32, page_size: i32) -> ResidentsListResult error: ResidentError # Create a new resident create(user_id: str, data: CreateResidentData) -> ResidentResult error: ResidentError # Get resident by ID get(resident_id: str) -> ResidentResult error: ResidentError # Update resident update(resident_id: str, data: UpdateResidentData) -> ResidentResult error: ResidentError # Delete resident delete(resident_id: str) -> DeleteResult error: ResidentError # Update subscription update_subscription(resident_id: str, plan: str, auto_renewal: bool) -> SubscriptionResult error: ResidentError # Get resident card (public display info) get_card(user_id: str) -> ResidentCardResult error: ResidentError } service ShareholderService { version: "1.0.0" description: "Shareholder management, invites, and share transfers" # Invite someone to become a shareholder invite_shareholder(company_id: str, inviter_id: str, invitee_email: str, proposed_percentage: f64, message?: str) -> InviteResult error: ShareholderError # Accept shareholder invite accept_invite(invite_token: str, resident_id: str) -> AcceptInviteResult error: ShareholderError # Reject shareholder invite reject_invite(invite_token: str) -> RejectInviteResult error: ShareholderError # List pending invites for a company list_invites(company_id: str) -> InviteListResult error: ShareholderError # Initiate share transfer initiate_transfer(company_id: str, from_resident_id: str, to_resident_id: str, percentage: f64, reason?: str) -> TransferResult error: ShareholderError # Approve share transfer (by recipient) approve_transfer(transfer_id: str, to_signature: str) -> TransferResult error: ShareholderError # Complete share transfer complete_transfer(transfer_id: str) -> TransferResult error: ShareholderError # Cancel share transfer cancel_transfer(transfer_id: str) -> TransferResult error: ShareholderError # List share transfers for a company list_transfers(company_id: str, status?: ShareTransferStatus) -> TransferListResult error: ShareholderError # Initiate dividend distribution initiate_dividend(company_id: str, total_amount: f64, currency: str, source_account_id: str, distribution_date: otime, initiated_by: str) -> DividendResult error: ShareholderError # Execute dividend distribution execute_dividend(dividend_id: str) -> DividendResult error: ShareholderError # List dividend distributions for a company list_dividends(company_id: str) -> DividendListResult error: ShareholderError } service TaxService { version: "1.0.0" description: "Tax filing and compliance management" # Create tax filing create_filing(company_id: str, filing_type: TaxFilingPeriod, period_start: otime, period_end: otime) -> TaxFilingResult error: TaxError # Get tax filing get_filing(filing_id: str) -> TaxFilingDetailResult error: TaxError # Update tax filing (draft only) update_filing(filing_id: str, gross_revenue: f64, cost_of_goods_sold: f64, operating_expenses: f64) -> TaxFilingResult error: TaxError # Submit tax filing submit_filing(filing_id: str, submitted_by: str, password: str) -> TaxFilingResult error: TaxError # List tax filings for a company list_filings(company_id: str, status?: TaxFilingStatus) -> TaxFilingListResult error: TaxError # Get upcoming filing deadlines get_deadlines(company_id: str) -> TaxDeadlineResult error: TaxError # Generate tax document generate_document(filing_id: str, document_type: str) -> TaxDocumentResult error: TaxError # List tax documents for a filing list_documents(filing_id: str) -> TaxDocumentListResult error: TaxError } service TreasuryOperationsService { version: "1.0.0" description: "Fund transfers and currency exchange" # Initiate internal fund transfer initiate_transfer(from_account_id: str, to_account_id: str, amount: f64, currency: str, reference?: str, initiated_by: str) -> FundTransferResult error: TreasuryOperationsError # Initiate external fund transfer initiate_external_transfer(from_account_id: str, to_address: str, to_name: str, amount: f64, currency: str, reference?: str, initiated_by: str) -> FundTransferResult error: TreasuryOperationsError # Approve fund transfer approve_transfer(transfer_id: str, approved_by: str) -> FundTransferResult error: TreasuryOperationsError # Cancel fund transfer cancel_transfer(transfer_id: str) -> FundTransferResult error: TreasuryOperationsError # List fund transfers for an account list_transfers(account_id: str, status?: FundTransferStatus) -> FundTransferListResult error: TreasuryOperationsError # Get exchange rate quote get_exchange_quote(from_currency: str, to_currency: str, amount: f64) -> ExchangeQuoteResult error: TreasuryOperationsError # Execute currency exchange execute_exchange(owner_type: EntityType, owner_id: str, from_account_id: str, to_account_id: str, from_amount: f64, from_currency: str, exchange_rate: f64, initiated_by: str) -> ExchangeResult error: TreasuryOperationsError # List exchange transactions list_exchanges(owner_type: EntityType, owner_id: str) -> ExchangeListResult error: TreasuryOperationsError } service TreasuryService { version: "1.0.0" description: "Treasury account and transaction management" # List company treasury accounts list_company_accounts(company_id: str) -> TreasuryAccountsResult error: TreasuryError # Get company treasury account get_company_account(company_id: str, account_id: str) -> TreasuryAccountResult error: TreasuryError # List company treasury transactions list_company_transactions(company_id: str, account_id: str) -> TreasuryTransactionsResult error: TreasuryError # Create company treasury account create_company_account(company_id: str, data: CreateTreasuryAccountData) -> TreasuryAccountResult error: TreasuryError # Update company treasury account update_company_account(company_id: str, account_id: str, data: UpdateTreasuryAccountData) -> TreasuryAccountResult error: TreasuryError # List resident treasury accounts list_resident_accounts(resident_id: str) -> TreasuryAccountsResult error: TreasuryError # Get resident treasury account get_resident_account(resident_id: str, account_id: str) -> TreasuryAccountResult error: TreasuryError # List resident treasury transactions list_resident_transactions(resident_id: str, account_id: str) -> TreasuryTransactionsResult error: TreasuryError # Create resident treasury account create_resident_account(resident_id: str, data: CreateTreasuryAccountData) -> TreasuryAccountResult error: TreasuryError # Update resident treasury account update_resident_account(resident_id: str, account_id: str, data: UpdateTreasuryAccountData) -> TreasuryAccountResult error: TreasuryError } service VerificationService { version: "1.0.0" description: "Tiered verification for individuals and companies" # Verify individual (Tier 1: anonymous, Tier 2: member, Tier 3: via link) verify_individual(resident_id: str, requester_tier: i32, link_token?: str) -> IndividualVerificationResult error: VerificationError # Verify company (Tier 1: anonymous, Tier 2: member, Tier 3: via link) verify_company(company_id: str, requester_tier: i32, link_token?: str) -> CompanyVerificationResult error: VerificationError # Create verification link create_verification_link(entity_type: EntityType, entity_id: str, label?: str, expires_in_hours: i32, single_use: bool) -> CreateLinkResult error: LinkError # Revoke verification link revoke_verification_link(link_id: str) -> RevokeResult error: LinkError # List verification links for user list_verification_links(user_id: str) -> VerificationLinksResult error: LinkError # Delete inactive verification links delete_inactive_links(user_id: str) -> DeleteLinksResult error: LinkError # Verify by token (public endpoint) verify_by_token(token: str) -> VerifyByTokenResult error: VerificationError } # ─────────────────────────────────────────────────────────────────────────────── # ENUMS - String literal union types # ─────────────────────────────────────────────────────────────────────────────── # ─────────────────────────────────────────────────────────────────────────────── # ENUMS - String literal union types # ─────────────────────────────────────────────────────────────────────────────── # Business document type BusinessDocumentType = "certificate_of_incorporation" | "business_license" | "memorandum" | "articles" | "resolution" | "other" # Free Zone Company status CompanyStatus = "active" | "inactive" | "suspended" # Company subscription plan for recurring fees CompanySubscriptionPlan = "monthly" | "one_year" | "two_years" # Company types available in the freezone CompanyType = "single_fzc" | "startup_fzc" | "growth_fzc" | "global_fzc" | "cooperative_fzc" # Contract status ContractStatus = "draft" | "pending_signature" | "active" | "expired" | "archived" # Dividend distribution status DividendStatus = "proposed" | "approved" | "processing" | "completed" | "cancelled" # Document types for signing DocumentType = "contract" | "agreement" | "invoice" | "certificate" | "other" # ═══════════════════════════════════════════════════════════════════════════════ # ZANZIBAR DIGITAL FREEZONE - OSIS Schema v2.0 # ═══════════════════════════════════════════════════════════════════════════════ # # A complete schema-driven system for digital residency and company management. # Features: # - Type-safe enums for all categorical data # - Full-text search on relevant fields # - Declarative business rules # - Cryptographic identity with key versioning # # ═══════════════════════════════════════════════════════════════════════════════ # ─────────────────────────────────────────────────────────────────────────────── # ENUMS - Type-safe categorical values # ─────────────────────────────────────────────────────────────────────────────── # Entity type for polymorphic references (resident or company) EntityType = "resident" | "company" # Exchange transaction status ExchangeStatus = "pending" | "processing" | "completed" | "failed" | "expired" # Expense status ExpenseStatus = "draft" | "submitted" | "approved" | "rejected" # Financial report type FinancialReportType = "balance_sheet" | "income_statement" | "cash_flow" | "trial_balance" # Fund transfer status FundTransferStatus = "pending" | "processing" | "completed" | "failed" | "cancelled" # Invoice status InvoiceStatus = "draft" | "sent" | "paid" | "overdue" | "cancelled" # KYC verification status KycStatus = "pending" | "in_progress" | "completed" | "failed" | "expired" # Message categories MessageCategory = "account" | "registration" | "security" | "kyc" | "payment" | "company" | "resident" | "general" # Message types MessageType = "system" | "notification" | "alert" # Payment method enum PaymentMethod = "crypto" | "clickpesa" | "bank_transfer" | "card" # Payment status PaymentStatus = "pending" | "confirming" | "confirmed" | "failed" | "expired" # Payment types PaymentType = "bitcoin" | "ethereum" | "clickpesa" # Proposal category ProposalCategory = "financial" | "strategic" | "operational" | "governance" | "personnel" # Proposal status ProposalStatus = "draft" | "active" | "passed" | "rejected" | "expired" | "executed" # Registration contract categories RegistrationContractCategory = "terms_of_service" | "privacy_policy" | "digital_residency" | "company_formation" # Registration flow status RegistrationFlowStatus = "identity_pending" | "identity_complete" | "personal_info_complete" | "payment_pending" | "payment_complete" | "kyc_pending" | "kyc_complete" | "registration_complete" # Digital Resident status ResidentStatus = "pending" | "active" | "suspended" | "expired" # Share transfer status ShareTransferStatus = "pending" | "approved" | "rejected" | "completed" | "cancelled" # Shareholder invite status ShareholderInviteStatus = "pending" | "accepted" | "rejected" | "expired" # Tax filing period type TaxFilingPeriod = "monthly" | "quarterly" | "annual" # Tax filing status TaxFilingStatus = "draft" | "submitted" | "accepted" | "rejected" | "amended" # Treasury account kind TreasuryAccountKind = "crypto_wallet" | "bank_account" # Treasury transaction status TreasuryTransactionStatus = "pending" | "confirmed" | "failed" # Treasury transaction type TreasuryTransactionType = "credit" | "debit" | "transfer" # Verification link status VerificationLinkStatus = "active" | "expired" | "used" | "revoked" # Vote value VoteValue = "for" | "against" | "abstain" # Voting model for companies VotingModel = "standard" | "cooperative"