Implement connection.rs Soroban contract (scout-player agreements)

[Petah1]

Summary

Implement the connection Soroban smart contract that records trial offer agreements between scouts and players on-chain, and advances a player to Elite Tier (Level 3) when a trial offer is logged.

Category

• Feature

Priority

• P0 – Blocks deployment

Depends On

#216 (workspace scaffold), #217 (register.rs — must update player progress level), #218 (progress.rs — shares validator registry)

Description

Function	Description
log_trial_offer(scout, player_id, details_uri)	Scout records a trial offer; advances player to Level 3; emits trial_offer_logged
get_connections(player_id)	Read-only: returns all scout-player connection records for a player
get_trial_offers(scout)	Read-only: returns all trial offers made by a scout

Level 3 promotion logic:
When log_trial_offer is called:

1. Verify caller is a scout with an active subscription OR has paid the contact fee for this player.
2. Write a TrialOffer record to persistent storage.
3. Call into register contract storage to set player's progress_level = 3.
4. Emit trial_offer_logged event with topics ["trial_offer_logged", scout, player_id].

Storage:

• Key: TrialOfferKey(scout, player_id) → TrialOfferData { details_uri, created_at }

Test Cases Required

• log_trial_offer promotes player from Level 2 to Level 3
• log_trial_offer requires scout to be subscribed or have paid contact fee
• Duplicate trial offer for same (scout, player) is idempotent
• get_connections returns correct records

[shadrach68]

I would like to work on this issue because I am a full-stack developer with 5+ years experience. I focus on identifying root causes and delivering clean, efficient, and maintainable solutions, with thorough testing to ensure reliable results.

[ayomideadeniran]

I'm a full-stack developer and I'd like to take this issue.
I understand the requirements and will follow the existing project structure, keep the implementation clean, and include proper tests where applicable.

ETA: 1–3 days (depending on scope)
Portfolio: https://knightsdev-portfolio.vercel.app/

[aliyuHabibu]

Hi, I'm a software engineer, I've gone through the issue and I can resolve it. Assign it to me thank you

[aliyuHabibu]

Hi, I'm a software engineer, I've gone through the issue and I can resolve it. Assign it to me thank you

[marshalfleet]

Hi maintainers,

I'd like to take this issue on. I’ve worked on Soroban-style contract systems where correctness depends heavily on cross-contract state updates, idempotency, and strict access control, and I understand this is a core P0 piece in the player progression flow.

Proposed implementation approach

I will implement the connection contract with a focus on deterministic state transitions and strict authorization boundaries.

---

1. log_trial_offer(scout, player_id, details_uri)

This function will enforce the full business rule chain:

• Verify the caller is a valid scout.

• Verify eligibility:

  • Either the scout has an active subscription, OR
  • The scout has successfully executed pay_to_contact for the given player_id.

• Enforce idempotency using TrialOfferKey(scout, player_id):

  • If a record already exists, return early without modifying state or re-emitting side effects.

• Persist TrialOfferData { details_uri, created_at } in storage.

• Trigger cross-contract update via register:

  • Set player.progress_level = 3 (Elite Tier)

• Emit event:

  • trial_offer_logged with topics ["trial_offer_logged", scout, player_id]

---

2. Storage model

I will use a deterministic key structure:

• TrialOfferKey(scout, player_id) → TrialOfferData

This guarantees:

• One trial offer per scout-player pair (natural idempotency boundary)
• O(1) lookup for existence checks
• Safe replay handling for retries or duplicate submissions

---

3. Read APIs

• get_connections(player_id)

  • Returns all TrialOfferData entries indexed by player

• get_trial_offers(scout)

  • Returns all offers indexed by scout

If the current storage layout does not support bidirectional iteration efficiently, I’ll introduce a minimal secondary index strategy aligned with existing storage patterns (without over-engineering).

---

4. Promotion logic (Level 3)

Player promotion will be handled via the shared register/progress module (from #217/#218). I will ensure:

• Promotion is only triggered once per player transition
• Repeated trial offers do not repeatedly mutate state
• The progression update is safe under concurrent or replayed calls

---

5. Security + correctness considerations

Because this contract influences progression and eligibility, I will prioritize:

• Strict authorization validation for scout identity
• Correct enforcement of subscription vs pay-to-contact gating logic
• Idempotent writes to prevent duplicate progression triggers
• Safe cross-contract calls to avoid partial state corruption
• Defensive handling of missing or inconsistent external state

---

6. Testing plan

I will add full integration coverage including:

• ✔ Player promotion from Level 2 → Level 3 on first valid trial offer
• ✔ Rejection when scout is neither subscribed nor has paid contact fee
• ✔ Idempotency: repeated log_trial_offer does not duplicate storage or re-trigger promotion
• ✔ Correct retrieval from get_connections and get_trial_offers
• ✔ Cross-contract interaction with register/progress logic
• ✔ Event emission validation

---

Summary

I will treat this as a state-transition critical contract, ensuring:

• deterministic storage behavior,
• safe cross-contract updates,
• and strict idempotency guarantees under replay conditions.

Happy to coordinate with the work in #217 and #218 to ensure clean integration across the progression system. I’d appreciate the opportunity to implement this.

[grantfox-oss]

🦊 GrantFox — @marshalfleet 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 #220)
2. Your PR will be reviewed by the scout-off maintainers

Good luck! Track your progress on GrantFox.