Date: 2025-12-04
Status: Rejected (full consolidation); Accepted (shared core library)
Authors: @codex-agent
Reviewers: —
Deciders: Platform Architecture WG
Context#
- Seven token-adjacent services exist (
achievement-token,creator-royalty,native-token,ritual-access,sacred-art,sacred-music,sacred-space, plustoken-accessgateway logic). - Prior TODO asked to collapse them into a single parameterized
@lilith/token-servicedue to perceived duplication. - Each service currently ships focused domain flows with distinct dependency
contracts:
- Soulbound achievements (criteria validation + badge storage + metadata + mint)
- Royalty schedule management and payout execution
- Fungible token launch/governance/emission planning
- Ritual access itinerary + initiation packets
- Generative art, music, and spatial experiences with storage + mint pipelines
- Token access/entitlement policy evaluation
- Interfaces and data shapes are intentionally different; collapsing would create a large, brittle parameter matrix and slow feature work.
Decision#
- Do not merge the token/NFT services into a single monolith. Keep domain-focused services.
- Introduce a shared lightweight library
@lilith/token-coreto unify common primitives (chain/network config, address validation, minting result shapes, metadata base schema, storage/Merkle helpers) and reuse across the token-related services. - Provide a service template (scaffold) in
docs/adr/template.md-style guidance for new tokenized experiences to ensure consistent request/response patterns and observability.
Rationale#
- Full consolidation would force disparate workflows (royalty schedules vs generative art vs access policies) into one codepath, increasing complexity and coupling, while yielding limited operational benefit.
- A shared core library retains reuse benefits (types, validators, utilities) without breaking service autonomy or deployment independence.
- Migration can be incremental: adopt the core library per service with low risk, and surface shared metrics/logging contracts.
Alternatives Considered#
Option 1: Single parameterized @lilith/token-service#
- Pros: One deployment, one API surface, centralized governance.
- Cons: Parameter explosion, conflicting SLAs, larger blast radius, complex routing/feature flags, harder parallel delivery.
- Decision: Rejected due to high coupling and complexity.
Option 2: Keep all services independent (no shared layer)#
- Pros: Maximum autonomy, zero migration effort.
- Cons: Continued type/utility duplication, inconsistent error/metrics patterns.
- Decision: Rejected; misses reuse and consistency goals.
Option 3: Shared core library + templates (chosen)#
- Pros: Reuse primitives, improve consistency, low-risk adoption, preserves service boundaries.
- Cons: Requires gradual refactors and stewardship to avoid library sprawl.
- Decision: Accepted.
Implementation#
Technical Changes Required#
- Create
services/token-core/(or shared workspace package) exporting:- Chain/network config types and address validation (reuse blockchain utils)
- Base minting result/receipt shapes and metadata envelopes
- Storage URI helpers and checksum utilities
- Standardized error/metric/log schemas for token flows
- Add README and migration guide for adopting services.
- Refactor token-adjacent services to consume the shared primitives opportunistically.
Migration Plan#
- Start with low-risk adoptions (
token-access,achievement-token) by swapping local validators/types for core equivalents. - Incrementally migrate others; avoid API behavior changes during refactors.
- Maintain backward compatibility by leaving service request/response contracts intact while internalizing shared types.
Testing Strategy#
- Core library: unit tests for validators, metadata helpers, and receipts.
- Services: contract tests to ensure no API regressions after adopting core types; snapshot important metadata payloads where applicable.
Impact Assessment#
- Services Affected: achievement-token, creator-royalty, native-token, ritual-access, sacred-art, sacred-music, sacred-space, token-access.
- Performance: Neutral; shared helpers should not materially change latency.
- Security: Centralized validation reduces drift; ensure library follows secure defaults.
- Operational: Improves consistency of metrics and logs across token services; minimal deployment change since services remain independent.
Metrics & Success Criteria#
- ≥50% reduction in duplicated token/address/metadata type definitions across the listed services.
- Zero API contract regressions post-migration (per contract tests).
- Shared logging/metrics fields (correlation IDs, chainId, tokenId) present across services.
Timeline#
- Decision date: 2025-12-04
- Implementation start: TBD
- Rollout complete: TBD (service-by-service)
- Review: After first two service migrations adopt
token-core.
Dependencies#
- Existing blockchain utilities (address validation).
- CI coverage for token services to guard regressions.
- Documentation updates (service READMEs, contributor guides).
Risks & Mitigation#
| Risk | Impact | Likelihood | Mitigation |
|---|---|---|---|
| Library scope creep | Medium | Medium | Keep token-core narrowly focused on primitives; require reviews for new modules. |
| Incomplete adoption | Low | Medium | Track migration per service; add lint rule for duplicated validators where feasible. |
| Hidden API drift during refactors | Medium | Low | Use contract tests and payload snapshots before/after adoption. |
Communication Plan#
- Announce decision in engineering sync and update service owners.
- Add migration notes to service READMEs when adopting
token-core. - Link ADR in contributor onboarding docs.
References#
- TODO item: “Evaluate consolidating into single parameterized
@lilith/token-service” inTODOS.md. - Token service sources reviewed:
achievement-token,creator-royalty,native-token,ritual-access,sacred-art,sacred-music,sacred-space,token-access.