Skip to content

feature/add-contract-support - #716

Open
Bamzy123 wants to merge 2 commits into
ritik4ever:mainfrom
Bamzy123:feature/add-contract-support
Open

feature/add-contract-support#716
Bamzy123 wants to merge 2 commits into
ritik4ever:mainfrom
Bamzy123:feature/add-contract-support

Conversation

@Bamzy123

@Bamzy123 Bamzy123 commented Jul 29, 2026

Copy link
Copy Markdown

Summary

This PR introduces Conditional Matching Grants to the stellar-goal-vault smart contracts, enabling sponsors to escrow matching funds for campaigns that satisfy predefined funding conditions.

Matching grants are released only when a campaign meets the configured minimum funding target. If the campaign does not qualify, any escrowed funds are returned to the sponsor. The implementation also enforces configurable matching ratios and maximum match caps while ensuring unused escrow is refunded appropriately.

Changes Made

Matching Grant Creation

  • Added support for creating conditional matching grants linked to a specific campaign.
  • Escrows the sponsor's matching funds within the vault contract at creation time.
  • Configured matching grants with:
    • Campaign ID
    • Accepted token
    • Matching ratio
    • Maximum match cap
    • Minimum campaign target
  • Emits a MatchingGrantCreated event when a grant is successfully created.

Campaign Claim Integration

  • Extended the campaign claim flow to evaluate matching grant eligibility.
  • Verified campaigns meet the configured minimum funding target before releasing matching funds.
  • Calculated matching amounts using the configured matching ratio while enforcing the maximum match cap.
  • Automatically transferred matched funds to the campaign creator.
  • Refunded any unused escrowed matching funds back to the sponsor after a successful claim.
  • Emitted matching grant release and refund events during settlement.

Matching Grant Refunds

  • Added support for refunding escrowed matching grants when:
    • A campaign fails to meet the required funding threshold.
    • A campaign expires without a successful claim.
    • A campaign is cancelled.
  • Returned all remaining escrowed matching funds to the sponsor.
  • Prevented duplicate refund operations by tracking refunded grants.
  • Emitted a MatchingGrantRefunded event upon successful refund.

Testing

Added comprehensive test coverage to verify:

  • Matching grants are successfully created and escrowed.
  • Matching funds are released only for qualifying campaigns.
  • Matching ratios are calculated correctly.
  • Maximum match caps are enforced.
  • Non-qualifying campaigns receive no matching funds.
  • Unused escrow is refunded to the sponsor after successful claims.
  • Full escrow refunds occur when campaigns fail or expire.
  • Matching grant events are emitted correctly throughout the lifecycle.

Impact

  • Introduces sponsor-funded conditional matching incentives for crowdfunding campaigns.
  • Ensures matching funds are securely escrowed until campaign conditions are satisfied.
  • Prevents over-allocation through configurable matching caps.
  • Automatically refunds unused or ineligible matching funds to sponsors.
  • Improves transparency through lifecycle event emission and deterministic settlement logic.

Closes #554

Summary by CodeRabbit

  • New Features

    • Added conditional matching grants for campaigns, including sponsor funding, configurable match ratios, minimum targets, and maximum caps.
    • Automatically releases qualifying matching funds when campaigns are claimed and returns unused escrow to sponsors.
    • Added grant refunds for canceled or expired campaigns.
    • Added grant status, campaign grant listing, and match amount calculation queries.
  • Documentation

    • Added documentation describing the matching-grant lifecycle and acceptance criteria.
  • Tests

    • Added coverage for grant creation, qualification, caps, payouts, and refunds.

@vercel

vercel Bot commented Jul 29, 2026

Copy link
Copy Markdown

@Bamzy123 is attempting to deploy a commit to the ritik4ever's projects Team on Vercel.

A member of the Team first needs to authorize it.

@drips-wave

drips-wave Bot commented Jul 29, 2026

Copy link
Copy Markdown

@Bamzy123 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

@coderabbitai

coderabbitai Bot commented Jul 29, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@Bamzy123, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 41 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 34fc5e09-160d-44bc-bb5c-c1bab68640bf

📥 Commits

Reviewing files that changed from the base of the PR and between 848df8c and 04dfbce.

📒 Files selected for processing (3)
  • contracts/src/matching.rs
  • contracts/src/test.rs
  • workflow.md
📝 Walkthrough

Walkthrough

Adds conditional matching grants with sponsor escrow, campaign qualification, capped payouts during claims, unused-fund returns, refunds for failed campaigns, public query methods, tests, and workflow documentation.

Changes

Conditional matching grants

Layer / File(s) Summary
Grant contract and creation
contracts/Cargo.toml, contracts/src/lib.rs, contracts/src/matching.rs
Defines grant storage and events, exposes matching-grant methods, validates parameters and campaign eligibility, and escrows sponsor funds.
Grant claim and refund lifecycle
contracts/src/lib.rs, contracts/src/matching.rs, contracts/src/test.rs
Processes grants during claims, releases capped matches, returns unused escrow, supports refunds, and tests successful, capped, non-qualifying, and partial-match flows.
Grant queries and workflow validation
contracts/src/matching.rs, workflow.md
Adds grant retrieval and match-calculation helpers and documents the matching-grant lifecycle and acceptance criteria.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Sponsor
  participant StellarGoalVaultContract
  participant CampaignCreator
  participant TokenClient
  Sponsor->>StellarGoalVaultContract: create_matching_grant
  StellarGoalVaultContract->>TokenClient: Lock max_match_cap in escrow
  StellarGoalVaultContract-->>Sponsor: Return grant ID
  StellarGoalVaultContract->>StellarGoalVaultContract: claim campaign
  StellarGoalVaultContract->>StellarGoalVaultContract: process_campaign_matching_grants
  StellarGoalVaultContract->>TokenClient: Transfer capped match
  TokenClient-->>CampaignCreator: Release matched funds
  StellarGoalVaultContract->>TokenClient: Return unused escrow
  TokenClient-->>Sponsor: Refund unused funds
Loading

Possibly related issues

  • #535: Adds the contract-level sponsor escrow, proportional capped matching, and campaign claim integration described by this issue.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Title check ❓ Inconclusive The title is generic and does not describe the actual change. Rename it to a specific summary like 'Add conditional matching grants to contracts'.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check ✅ Passed The PR implements conditional matching grants with escrow, cap/target checks, claim release, refunds, and tests as required.
Out of Scope Changes check ✅ Passed The changes stay focused on the matching-grant feature and supporting tests/docs, with no clear unrelated additions.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
  • Fix failing CI checks
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@contracts/Cargo.toml`:
- Around line 19-22: Update the soroban-sdk dependencies in contracts/Cargo.toml
and all workspace manifests from 23.5.2 to a supported major within the two most
recent release majors, keeping the dev-dependency testutils feature intact and
aligning all workspace versions.

In `@contracts/src/matching.rs`:
- Around line 274-277: Update refund_matching_grant so it rejects refunds when
the campaign has already reached grant.min_campaign_target, even after the
deadline and before claim(). Preserve refunds for canceled or expired campaigns
that remain below the target, and ensure a qualifying campaign’s grant remains
available for claim().

In `@workflow.md`:
- Around line 8-21: Add the text language identifier to the fenced diagram block
in workflow.md, changing the opening fence to specify text while preserving the
diagram content unchanged.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f6846f13-ded8-4f72-b122-e1dc6cbbddef

📥 Commits

Reviewing files that changed from the base of the PR and between 10f827c and 848df8c.

⛔ Files ignored due to path filters (1)
  • contracts/Cargo.lock is excluded by !**/*.lock
📒 Files selected for processing (5)
  • contracts/Cargo.toml
  • contracts/src/lib.rs
  • contracts/src/matching.rs
  • contracts/src/test.rs
  • workflow.md

Comment thread contracts/Cargo.toml
Comment on lines +19 to +22
soroban-sdk = "23.5.2"

[dev-dependencies]
soroban-sdk = { version = "21.0.0", features = ["testutils"] }
proptest = "1.4"
soroban-sdk = { version = "23.5.2", features = ["testutils"] }

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

What is the latest soroban-sdk major version and which majors currently receive security fixes?

💡 Result:

As of July 29, 2026, the latest major version of the soroban-sdk is 27 [1][2]. Regarding the support policy, the two most recent major releases are supported with critical security fixes [3][4][5]. While critical security issues may be backported to earlier versions if practical, this is not guaranteed [3][4][5]. General bug fixes and new features are exclusively provided for the latest major release [3][4][5].

Citations:


Lock soroban-sdk to a supported security-fix release.

The supported security-fix window is the two most recent majors; with 27.x current, 23.5.2 is two majors behind and can rely only on backports, not guaranteed fixes. Update contracts/Cargo.toml to a supported major and bump dependency versions across the workspace.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@contracts/Cargo.toml` around lines 19 - 22, Update the soroban-sdk
dependencies in contracts/Cargo.toml and all workspace manifests from 23.5.2 to
a supported major within the two most recent release majors, keeping the
dev-dependency testutils feature intact and aligning all workspace versions.

Comment thread contracts/src/matching.rs
Comment thread workflow.md Outdated
@ritik4ever

Copy link
Copy Markdown
Owner

Hi @Bamzy123,

This PR could not be merged because it has merge conflicts with the target branch.

Please resolve the merge conflicts, push the updated changes, and the PR can be reviewed and merged.

Thank you!

1 similar comment
@ritik4ever

Copy link
Copy Markdown
Owner

Hi @Bamzy123,

This PR could not be merged because it has merge conflicts with the target branch.

Please resolve the merge conflicts, push the updated changes, and the PR can be reviewed and merged.

Thank you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE] Add contract support for conditional matching grants

2 participants