feat: ontology for accounts

[coodos]

Description of change

Issue Number

Type of change

• Breaking (any change that would cause existing functionality to not work as expected)
• New (a change which implements a new feature)
• Update (a change which updates existing functionality)
• Fix (a change which fixes an issue)
• Docs (changes to the documentation)
• Chore (refactoring, build scripts or anything else that isn't user-facing)

How the change has been tested

Change checklist

• I have ensured that the CI Checks pass locally
• I have removed any unnecessary logic
• My code is well documented
• I have signed my commits
• My code follows the pattern of the application
• I have self reviewed my code

Summary by CodeRabbit

Release Notes

• Documentation

  • New guide explains eCurrency accounts and ledgers, covering data models, entity relationships, transaction flows, GraphQL query patterns, and transfer rules.

• Chores

  • Added account backfill tooling and schema definitions to support account management and data migration operations.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 456ad7c1-6c98-48b0-9187-9439a6f56063

📥 Commits

Reviewing files that changed from the base of the PR and between d2efd8b and 616f58d.

📒 Files selected for processing (4)

• docs/docs/Post Platform Guide/ecurrency-accounts-and-ledger.md
• platforms/ecurrency/api/package.json
• platforms/ecurrency/api/src/scripts/backfill-accounts.ts
• services/ontology/schemas/account.json

---

📝 Walkthrough

Walkthrough

The changes introduce eCurrency account functionality through new documentation, JSON schema definition, and a backfill script that populates existing account data from the ledger into user and group eVaults using GraphQL mutations.

Changes

Cohort / File(s)	Summary
Documentation & Schema docs/docs/Post Platform Guide/ecurrency-accounts-and-ledger.md, services/ontology/schemas/account.json	New documentation describing the eCurrency account and ledger MetaEnvelope data model with JSON examples, diagrams, GraphQL query patterns, and operational semantics. New JSON Schema defines the Account object with required fields: accountId, accountEname, accountType, currencyEname, currencyName, balance, and createdAt.
Backfill Infrastructure platforms/ecurrency/api/package.json, platforms/ecurrency/api/src/scripts/backfill-accounts.ts	Added backfill:accounts npm script. New TypeScript backfill script that enumerates distinct account combinations from the database ledger, resolves account holders and currencies to normalized eNames, queries existing envelopes from eVaults via GraphQL, deduplicates, and writes new account envelopes via GraphQL mutations in batches with retry logic and dry-run support.

Sequence Diagram

sequenceDiagram
    participant Script as Backfill Script
    participant DB as Application Database
    participant Registry as eVault Registry
    participant eVault as eVault Service
    participant TokenSvc as Token Service

    Script->>DB: Query distinct (accountId, accountType, currencyId) from Ledger
    DB-->>Script: Return account combinations
    
    Script->>Script: Compute balance & createdAt per account
    Script->>Script: Group accounts by holder eVault
    
    loop For each holder eVault
        Script->>Registry: Resolve eVault URL for holder eName
        Registry-->>Script: eVault URL
        
        Script->>eVault: Query existing MetaEnvelopes (ledger & account ontologies)
        eVault-->>Script: Existing envelopes
        
        Script->>Script: Filter out duplicate accounts by accountId & currencyEname
        
        alt Account not exists
            Script->>TokenSvc: Get/refresh platform token (on 401)
            TokenSvc-->>Script: Access token
            Script->>eVault: Bulk create account MetaEnvelopes (batched)
            eVault-->>Script: Success/error per envelope
        else Account exists
            Script->>Script: Skip (already backfilled)
        end
    end
    
    Script->>Script: Aggregate and log totals

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 Hops through ledgers, nibbling numbers clean,
Account envelopes tucked in eVaults between,
Backfill scripts with retry grace,
Deduplication keeps the right place,
Balances balanced, no crumbs in the scene! 🥕✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/docs-account-and-ecurrency

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}