docs: add documentation for buyer-initiated offers and createOfferAnd…#1017
docs: add documentation for buyer-initiated offers and createOfferAnd…#1017levalleux-ludo wants to merge 1 commit intomainfrom
Conversation
There was a problem hiding this comment.
Pull request overview
Adds new internal documentation pages describing two offer flows covered by the e2e test suite: (1) the createOfferAndCommit helper flow (seller-initiated vs buyer-initiated) and (2) buyer-initiated offers committed via commitToBuyerOffer.
Changes:
- Documented the
createOfferAndCommithelper’s purpose, prerequisites, and covered test scenarios. - Documented buyer-initiated offer flow in
core-sdk-offers.test.ts, including prerequisites, fund movements, and error cases.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/details/createOfferAndCommit.md | New doc explaining how createOfferAndCommit is used in e2e tests for seller-initiated and buyer-initiated offers. |
| docs/details/buyerInitiatedOffers.md | New doc explaining buyer-initiated offers and the seller-side commitToBuyerOffer test coverage and fund flows. |
|
|
||
| ## What the method does | ||
|
|
||
| `createOfferAndCommit` (helper in `e2e/tests/utils.ts:660`) atomically: |
There was a problem hiding this comment.
The referenced helper location e2e/tests/utils.ts:660 is out of date; createOfferAndCommit currently starts at e2e/tests/utils.ts:662. Consider removing exact line numbers (they drift) or updating them to match the current file.
| `createOfferAndCommit` (helper in `e2e/tests/utils.ts:660`) atomically: | |
| `createOfferAndCommit` (helper in `e2e/tests/utils.ts`) atomically: |
| `initSellerAndBuyerSDKs` (`utils.ts:263`) creates two fresh wallets (seller + buyer), each funded with ETH from a seed wallet. Both parties must have enough native ETH to pay for gas (and for the commit price in native-ETH offers). | ||
|
|
||
| ### 2. Seller account registered on-chain — `createSeller` is mandatory | ||
| `createSeller` (`utils.ts:954`) must be called before any `createOfferAndCommit`. It: |
There was a problem hiding this comment.
createSeller is referenced as utils.ts:954, but createSeller currently starts at e2e/tests/utils.ts:956 (954 is the end of a different helper). Please update the reference or drop the line number to avoid future drift.
| `createSeller` (`utils.ts:954`) must be called before any `createOfferAndCommit`. It: | |
| `createSeller` (`utils.ts`) must be called before any `createOfferAndCommit`. It: |
| ## Files | ||
| - Helper definition: `e2e/tests/utils.ts:660` | ||
| - Test file: `e2e/tests/core-sdk.test.ts` (seller-initiated ~L245–430, buyer-initiated ~L534–680) |
There was a problem hiding this comment.
The Files section references e2e/tests/utils.ts:660, but createOfferAndCommit currently starts at line 662. Either update the line number(s) or link to the file/function without a hardcoded line reference (more stable).
|
|
||
| ## Overview | ||
|
|
||
| In a **buyer-initiated offer**, the buyer creates and signs the offer; the seller is the one who "commits" to it (i.e. accepts the deal). This is the reverse of the standard flow. |
There was a problem hiding this comment.
This overview says the buyer "creates and signs" the offer, but in core-sdk-offers.test.ts the buyer-initiated offer is created on-chain via createOffer(buyerCoreSDK, ...) (no separate EIP-712 offer signature step). Rewording to "creates the offer on-chain" would better match the test flow and avoid confusion with the createOfferAndCommit signed-offer path.
| In a **buyer-initiated offer**, the buyer creates and signs the offer; the seller is the one who "commits" to it (i.e. accepts the deal). This is the reverse of the standard flow. | |
| In a **buyer-initiated offer**, the buyer creates the offer on-chain; the seller is the one who "commits" to it (i.e. accepts the deal). This is the reverse of the standard flow. |
| - `commitToBuyerOffer` — `utils.ts:1272` | ||
| - `commitToOffer` — `utils.ts:1252` | ||
| - `createOffer` — `utils.ts:478` | ||
| - `createSeller` — `utils.ts:954` | ||
| - `createDisputeResolver` — `utils.ts:446` | ||
| - `initSellerAndBuyerSDKs` — `utils.ts:263` |
There was a problem hiding this comment.
Several helper references in this Files section have stale line numbers in e2e/tests/utils.ts (e.g., commitToOffer starts at 1254, commitToBuyerOffer at 1274, createSeller at 956). Please update these or remove hardcoded line numbers to keep the docs from going stale as the helpers change.
| - `commitToBuyerOffer` — `utils.ts:1272` | |
| - `commitToOffer` — `utils.ts:1252` | |
| - `createOffer` — `utils.ts:478` | |
| - `createSeller` — `utils.ts:954` | |
| - `createDisputeResolver` — `utils.ts:446` | |
| - `initSellerAndBuyerSDKs` — `utils.ts:263` | |
| - `commitToBuyerOffer` | |
| - `commitToOffer` | |
| - `createOffer` | |
| - `createSeller` | |
| - `createDisputeResolver` | |
| - `initSellerAndBuyerSDKs` |
| # Synthesis: `createOfferAndCommit` in core-sdk.test.ts | ||
|
|
||
| ## What the method does |
There was a problem hiding this comment.
The PR description still contains template placeholders (e.g., {{what was done}}, {{how can it be tested}}). Please replace these with a short summary and concrete testing steps so reviewers know what changed and how to validate it.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1017 +/- ##
=======================================
Coverage 90.96% 90.96%
=======================================
Files 179 179
Lines 7297 7297
Branches 1366 1366
=======================================
Hits 6638 6638
Misses 659 659
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
…Commit method
Description
{{what was done}}
How to test
{{how can it be tested}}