Write architecture decision records (ADRs) for key design choices

[prodbycorne]

Overview

Several non-obvious design decisions in the contracts lack documentation. Future contributors and auditors cannot determine whether a choice was intentional or accidental. Architecture Decision Records (ADRs) capture the why behind key choices.

ADRs Required

ADR-001: Dual Credit Systems (Boost/Stake vs Lock/Unlock)

• Why does the pool have two independent credit accrual mechanisms?
• When should a user use stake/unstake vs lock_assets/unlock_assets?
• How are credits from both systems intended to be combined?

ADR-002: Factory-Deployed vs Standalone Pool Deployment

• Why are pools deployed via a factory rather than standalone?
• What is the security model for verifying a pool's authenticity (pool_wasm_hash check)?
• Trade-offs of deterministic salt vs random salt

ADR-003: TTL Extension Strategy

• Why are TTLs extended on every read/write rather than only on writes?
• What are the cost implications?
• What happens to user data when TTL expires?

ADR-004: Credit Accrual without On-Chain Token Minting

• Why do credits exist as a counter rather than as minted tokens?
• How does the credit-to-reward conversion work (planned or current)?
• Why not use a standard Soroban token for credits?

ADR-005: Pause Mechanism Scope

• Why does pause block user functions but not admin functions?
• What is the intended recovery procedure after a pause?

Format

Store ADRs as docs/decisions/ADR-00N-title.md using the standard format:

# ADR-NNN: Title
## Status: Accepted
## Context
## Decision
## Consequences

Acceptance Criteria

• docs/decisions/ directory created
• All 5 ADRs above written
• Each ADR includes Status, Context, Decision, and Consequences sections
• docs/README.md links to all ADRs
• ADR-002 includes a diagram or table of the factory-pool relationship

[umohjosephemmanuel-cyber]

Authored comprehensive Architecture Decision Records (ADRs) to document critical smart contract design choices, deployment strategies, credit systems, TTL management, and recovery mechanisms, improving project maintainability, auditability, and onboarding for future contributors.

[Exploit34]

@Exploit34 has applied to work on this issue as technical docs

Hi Maintainer, I have experience contributing to technical documentation and I understand what's being requested here. I'd be glad to write all 5 ADRs covering the dual credit systems, factory deployment model, TTL strategy, credit accrual, and pause mechanism, following the standard ADR format. Please permit me to take ownership of it.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Exploit34 to this issue.

[clintjeff2]

Hello, I have 6 years of experience working on tasks like this and handling similar challenges across backend, frontend, and smart-contract development. I have carefully read and fully understood the task requirements, and I am confident I can deliver a clean, efficient, and well-tested solution promptly. I always ensure high-quality implementation, maintainability, and adherence to best practices.

Pull request in 5 hours.

[MikRoyce]

Hi Maintainer,

I would love to take ownership of this issue and author the comprehensive Architecture Decision Records (ADRs) for the smartdrop-contracts repository.

I have a strong understanding of smart contract architectures and technical documentation best practices. I will ensure all 5 ADRs—covering the dual credit systems, factory deployment model, TTL strategy, credit accrual mechanisms, and pause scope—are meticulously documented following your required template (Status, Context, Decision, and Consequences).

Additionally, I will set up the proper directory structure (docs/decisions/), update the main docs/README.md with clean navigation links, and include a clear diagram/table detailing the factory-pool relationship for ADR-002 to meet all your acceptance criteria.

[grantfox-oss]

🦊 GrantFox — @MikRoyce has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #39)
2. Your PR will be reviewed by the SmartDropLabs maintainers

Good luck! Track your progress on GrantFox.