feat(core): add participation-token module with buy endpoint

[JuanWimmin]

Summary

• Add ParticipationTokenModule to apps/core/src/ with REST endpoint to interact with deployed Participation Token contracts
• POST /participation-token/buy → returns { unsignedXdr } for client-side signing
• Uses SorobanService.buildContractCallTransaction() to build the on-chain call
• Module registered in AppModule, does not interfere with existing deploy module

Files created/modified

apps/core/src/participation-token/
├── dto/
│   └── buy.dto.ts              # Validates contractId, usdcAddress, payer, beneficiary, amount, callerPublicKey
├── participation-token.controller.ts   # POST /participation-token/buy
├── participation-token.service.ts      # Calls soroban.buildContractCallTransaction
└── participation-token.module.ts       # Registers controller + service

• apps/core/src/app.module.ts — added ParticipationTokenModule to imports

Test plan

• POST /participation-token/buy returns { unsignedXdr } with valid request body
• DTO validation rejects missing fields and non-positive amounts
• Module does not affect existing deploy, campaigns, or investments endpoints
• Build compiles with no new errors (existing Prisma errors are pre-existing)

Closes #40

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added a participation token purchase endpoint to initiate token buy transactions; accepts contract and payment details, payer and beneficiary, and amount, returning an unsigned transaction ready for signing.
  • Input validation added for required fields and positive amounts to prevent invalid requests.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a6542673-f46b-4538-8b03-aea23cd5b03f

📥 Commits

Reviewing files that changed from the base of the PR and between dff933a and 9c41e0c.

📒 Files selected for processing (1)

• apps/core/src/app.module.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• apps/core/src/app.module.ts

---

📝 Walkthrough

Walkthrough

Adds a new NestJS module participation-token with a validated BuyDto, a controller exposing POST /participation-token/buy, and a service that delegates to SorobanService.buildContractCallTransaction; the module is registered in AppModule.

Changes

Cohort / File(s)	Summary
App Registration apps/core/src/app.module.ts	Registered ParticipationTokenModule in AppModule imports.
Module Declaration apps/core/src/participation-token/participation-token.module.ts	New NestJS module declaring ParticipationTokenController and ParticipationTokenService.
DTO apps/core/src/participation-token/dto/buy.dto.ts	Added BuyDto with validations: contractId, usdcAddress, payer, beneficiary, callerPublicKey (strings, not empty) and amount (number, positive).
Service apps/core/src/participation-token/participation-token.service.ts	New ParticipationTokenService.buy(dto) that calls soroban.buildContractCallTransaction(contractId, 'buy', args, callerPublicKey) and returns unsigned XDR.
Controller apps/core/src/participation-token/participation-token.controller.ts	New POST /participation-token/buy endpoint accepting BuyDto and returning { unsignedXdr } from the service.

Sequence Diagram

sequenceDiagram
    actor Client
    participant Controller as ParticipationTokenController
    participant Service as ParticipationTokenService
    participant Soroban as SorobanService

    Client->>Controller: POST /participation-token/buy (BuyDto)
    activate Controller
    Controller->>Service: buy(dto)
    deactivate Controller

    activate Service
    Service->>Soroban: buildContractCallTransaction(contractId, "buy", args, callerPublicKey)
    deactivate Service

    activate Soroban
    Note over Soroban: Create client → call contract method → return unsigned XDR
    Soroban-->>Service: unsignedXdr
    deactivate Soroban

    Service-->>Controller: unsignedXdr
    Controller-->>Client: { unsignedXdr }

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Refactor/move funcs to core #14 — Adds a ParticipationToken module/service that depends on and calls SorobanService and updates AppModule imports.

Suggested reviewers

• JoelVR17
• zkCaleb-dev
• armandocodecr

Poem

🐰
I hopped a new route through code so spry,
A buy endpoint ready to fly,
XDR tucked in a gentle byte,
Soroban hums through day and night,
Tokens bloom beneath my sky.

🚥 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 accurately describes the main change: adding a participation-token module with a buy endpoint, matching the core objective of the PR.
Linked Issues check	✅ Passed	All coding requirements from issue #40 are met: module structure created, buy endpoint with DTO validations implemented, SorobanService integration added, and module registered in AppModule.
Out of Scope Changes check	✅ Passed	All changes are directly related to the participation-token module implementation as specified in issue #40; no out-of-scope modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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.}

[zkCaleb-dev]

Greate!!