fix: enforce EVC subaccount boundary

[Seranged]

Summary

• Enforce the EVC 8-bit account-family boundary across the shared SDK sub-account helpers.
• Prevent address generation and discovery from crossing into an adjacent account family.

Changes

• Set SUB_ACCOUNT_MAX_ID to 255, so account-family IDs are limited to 0–255 and default free-sub-account discovery returns IDs 1–255.
• Cover the boundary through getSubAccountAddress, getSubAccountId, isSubAccount, and getFreeSubAccounts, including acceptance of 255 and rejection of 256.
• Document the 256-address family as primary account ID 0 plus sub-account IDs 1–255.
• The open Activity service PR feat: add activity service #66 must rebase onto this fix before merging so its Activity validation inherits the corrected maximum.

Test plan

• pnpm --filter @eulerxyz/euler-v2-sdk exec vitest run test/accountPortfolio.test.ts
• pnpm --filter @eulerxyz/euler-v2-sdk run test
• pnpm --filter @eulerxyz/euler-v2-sdk run typecheck
• pnpm --filter @eulerxyz/euler-v2-sdk exec biome check src/utils/subAccounts.ts test/accountPortfolio.test.ts

Summary by CodeRabbit

• Documentation

  • Clarified that an account family contains up to 256 EVC account addresses: one primary account and sub-accounts numbered 1–255.
  • Expanded the description of account-family details, including controllers, collaterals, and liquidity.

• Bug Fixes

  • Corrected sub-account boundary handling to enforce the valid 0–255 ID range.
  • Improved validation for out-of-range account IDs and family addresses.

• Tests

  • Added coverage for account-family boundary behavior and invalid ID handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: euler-xyz/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 37098451-e376-4737-bf63-e8b5f46d8305

📥 Commits

Reviewing files that changed from the base of the PR and between 36868c8 and 91d204b.

📒 Files selected for processing (3)

• packages/euler-v2-sdk/docs/basic-usage.md
• packages/euler-v2-sdk/src/utils/subAccounts.ts
• packages/euler-v2-sdk/test/accountPortfolio.test.ts

---

📝 Walkthrough

Walkthrough

The SDK now treats account families as 256 EVC addresses with IDs 0–255. Sub-account utilities enforce the upper bound, tests cover boundary and out-of-family behavior, and the basic usage documentation reflects the updated account model.

Changes

Account family boundary

Layer / File(s)	Summary
Define the 8-bit account family boundary packages/euler-v2-sdk/src/utils/subAccounts.ts, packages/euler-v2-sdk/docs/basic-usage.md	Sets SUB_ACCOUNT_MAX_ID to 255 and documents primary account ID 0 with sub-account IDs 1–255.
Validate boundary behavior packages/euler-v2-sdk/test/accountPortfolio.test.ts	Adds boundary and out-of-family assertions for sub-account address, ID, detection, and free-account helpers.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: enforcing the EVC subaccount boundary.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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 fix/subaccount-id-boundary

---

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

[LeonardEulerXYZ]

Leonard review walkthrough

Verdict: clean at 91d204b31aee7b7d66f6423ffaebfcd234dba652.

This fixes the shared boundary at the correct abstraction: SUB_ACCOUNT_MAX_ID now represents the largest valid 8-bit family-relative ID (255), and the existing helpers consistently inherit it:

• getSubAccountAddress rejects 256 instead of crossing into the adjacent first-19-byte prefix.
• getSubAccountId and isSubAccount no longer classify the adjacent family as related.
• Default free-account discovery is bounded to IDs 1–255.
• The docs distinguish 256 total family addresses from 255 non-primary subaccounts.

Validation

• EVC reference check: ethereum-vault-connector keys ownership by bytes19 / the first 19 address bytes and documents groups of exactly 256 addresses.
• pnpm --filter @eulerxyz/euler-v2-sdk exec vitest run test/accountPortfolio.test.ts — 28 passed.
• pnpm --filter @eulerxyz/euler-v2-sdk run test — 31 files / 404 tests passed.
• Package and workspace typechecks passed.
• Package and workspace builds passed, including the React SDK example.
• Built public-export smoke confirmed SUB_ACCOUNT_MAX_ID === 255, ID 255 round-trips, and ID 256 is rejected.
• Changed source passed Biome; git diff --check passed.
• Whole-diff security/supply-chain sweep found no dependency, workflow, secret, network, or executable-surface changes.

Scalability / maintainability hygiene

The account, portfolio, account-service candidate selection, and execution simulation paths already consume these shared helpers rather than carrying sibling limits, so the fix propagates without a second local abstraction. Repository-wide searches found no remaining hardcoded 256-as-maximum behavior on main. Open Activity PR #66 also consumes the exported constant/helpers; its current branch still describes 256 as the maximum ID, so the PR body’s explicit rebase requirement is the correct sequencing guard.

Euler Lite’s current consumers use the exported address/ID helpers and contain no parallel 256 boundary. No additional reusable utility or sibling-flow patch is needed here.

CodeRabbit reported no actionable findings; I found no material bot false positive to call out. No screenshots were applicable because this is a non-UI SDK invariant fix.

[LeonardEulerXYZ]

Approved at 91d204b31aee7b7d66f6423ffaebfcd234dba652.

The EVC first-19-byte family invariant, helper behavior, default discovery range, public package export, sibling consumers, and Activity PR #66 sequencing were checked. Focused tests (28), full package tests (404), package/workspace typechecks, package/workspace builds, changed-source Biome, and git diff --check passed. No blocking correctness, compatibility, security, or maintainability findings.