From 8330be7f51e51beb7258f64be6b93a0c506dea28 Mon Sep 17 00:00:00 2001 From: alexanderem49 Date: Wed, 25 Oct 2023 12:03:58 +0400 Subject: [PATCH] Fix: update comments --- contract/src/simpleExchange.js | 38 ++++++++++++------- contract/src/upgradableSimpleExchange.js | 47 +++++++++++++++++------- 2 files changed, 58 insertions(+), 27 deletions(-) diff --git a/contract/src/simpleExchange.js b/contract/src/simpleExchange.js index c8e22af..d7408ea 100644 --- a/contract/src/simpleExchange.js +++ b/contract/src/simpleExchange.js @@ -10,10 +10,11 @@ import { } from '@agoric/zoe/src/contractSupport'; const start = (zcf) => { - // The contract expects issuers to be labeled as 'Asset' and 'Price'. + // The contract expects proposals for this contract instance + // should use keywords 'Asset' and 'Price'. assertIssuerKeywords(zcf, harden(['Asset', 'Price'])); - // Store the order book in two arrays, one for buys and one for sells. + // Store the users seats in two arrays, one for buys and one for sells offers. let sellSeats = []; let buySeats = []; @@ -30,20 +31,23 @@ const start = (zcf) => { // Create a notifier that will update when the order book changes. const { notifier, updater } = makeNotifierKit(getOrderBook()); - // Update the notifier when the order book changes. + // Update the notifier state when the order book changes. const updateOrderBook = () => updater.updateState(getOrderBook()); - // Return true if the first seat is satisfied by the second seat. - // Returns true if wants of both seats are satisfied. + // Checks if the second seat argument's currentAllocation satisfies the + // first seat argument's proposal.want. Returns true if satisfied. const satisfiedBy = (xSeat, ySeat) => satisfies(zcf, xSeat, ySeat.getCurrentAllocation()); // Execute swap with first satisfiable offer in the array. - // Return the satisfiable offer, or undefined if no offer was found. + // Return the user seat that made the satisfiable offer, or + // undefined if no offer was found. const swapIfCanTrade = (offers, seat) => { for (const offer of offers) { + // Calls satisfiedBy() on both orders of the two seats. If both + // satisfy each other, it does a swap on them. if (satisfiedBy(offer, seat) && satisfiedBy(seat, offer)) { - // When satisfiable offer is found, swap and return the offer. + // When satisfiable offer is found, swap and return the user seat. // Swap will throw if the swap fails, no assets will be transferred, // and both seats will fail. If the swap succeeds, both seats will // be exited and the assets will be transferred. @@ -57,7 +61,7 @@ const start = (zcf) => { // Process an incoming offer. If the offer can be satisfied, swap and remove // the counter offer from the counterOffers array. If the offer cannot be - // satisfied, add the offer to the counterOffers array. + // satisfied, add the seat to the counterOffers array. const swapIfCanTradeAndUpdateBook = (counterOffers, coOffers, seat) => { // try to execute a swap const offer = swapIfCanTrade(counterOffers, seat); @@ -70,7 +74,7 @@ const start = (zcf) => { coOffers.push(seat); } - // notify the notifier that the order book has changed + // Update the notifier state with the changes made to the order book. updateOrderBook(); return counterOffers; }; @@ -84,6 +88,13 @@ const start = (zcf) => { // Get the proposal from the seat. const { want, give } = seat.getProposal(); + // Check if the proposal is a buy or sell offer. + + // Buy offer is an offer that wants Asset and gives Price, give.Asset + // in this case is undefined. + + // Sell offer is an offer that wants Price and gives Asset, want.Asset + // in this case is undefined. if (want.Asset) { // If the proposal is a buy, try to execute a swap with the sell book. sellSeats = swapIfCanTradeAndUpdateBook(sellSeats, buySeats, seat); @@ -102,7 +113,7 @@ const start = (zcf) => { }; // Create an invitation to the contract. The incoming offer will be handled - // by the exchangeOfferHandler function. Incoming offer seat must match the + // by the exchangeOfferHandler function. Incoming offerProposal must match the // proposal shape defined by the contract - both give and want must be either // Asset or Price. const makeExchangeInvitation = () => { @@ -120,15 +131,14 @@ const start = (zcf) => { // The creatorFacet of the contract, in this case it has no functions. const creatorFacet = Far('creatorFacet', {}); - // The publicFacet has a function that allows users to create invitations - // to the contract, and a function that returns a notifier that will update - // when the order book changes. + // The publicFacet has a function that allows users to create the + // invitation to exercise a sell or buy offer, and a function that + // returns a notifier that will update when the order book changes. const publicFacet = Far('publicFacet', { makeInvitation: makeExchangeInvitation, getNotifier: () => notifier, }); - // Return the facets of the contract. return harden({ creatorFacet, publicFacet }); }; diff --git a/contract/src/upgradableSimpleExchange.js b/contract/src/upgradableSimpleExchange.js index c717ed1..8644291 100644 --- a/contract/src/upgradableSimpleExchange.js +++ b/contract/src/upgradableSimpleExchange.js @@ -17,7 +17,8 @@ import { const prepare = async (zcf, privateArgs, baggage) => { const { marshaller, storageNode } = privateArgs; - // The contract expects issuers to be labeled as 'Asset' and 'Price'. + // The contract expects proposals for this contract instance + // should use keywords 'Asset' and 'Price'. assertIssuerKeywords(zcf, harden(['Asset', 'Price'])); // Create a recorder kit that will be used to create a subscriber for @@ -30,7 +31,11 @@ const prepare = async (zcf, privateArgs, baggage) => { recorderKit: () => makeRecorderKit(storageNode), }); - // Create storages for the order book, one for buys and one for sells. + // Create durable storages for the order book, one for buy offers and + // one for sell offers. + // Durable storage is a storage that persists with contract upgrades. + // Using durable storage makes this contract upgradable without losing + // the order book data. const sellSeatsMap = provide(baggage, 'sellSeats', () => makeScalarBigMapStore('sellSeats', { durable: true }), ); @@ -57,20 +62,24 @@ const prepare = async (zcf, privateArgs, baggage) => { sells: getOffers(sellSeatsMap), }); + // Update the subscriber state when the order book changes. const updateOrderBook = () => recorder.write(getOrderBook()); updateOrderBook(); - // Return true if the first seat is satisfied by the second seat. - // Returns true if wants of both seats are satisfied. + // Checks if the second seat argument's currentAllocation satisfies the + // first seat argument's proposal.want. Returns true if satisfied. const satisfiedBy = (xSeat, ySeat) => satisfies(zcf, xSeat, ySeat.getCurrentAllocation()); // Execute swap with first satisfiable offer in the storage. - // Return the satisfiable offer, or undefined if no offer was found. + // Return the user seat that made the satisfiable offer, or + // undefined if no offer was found. const swapIfCanTrade = (seatsMap, userSeat) => { for (const seat of seatsMap.keys()) { + // Calls satisfiedBy() on both orders of the two seats. If both + // satisfy each other, it does a swap on them. if (satisfiedBy(seat, userSeat) && satisfiedBy(userSeat, seat)) { - // When satisfiable offer is found, swap and return the offer. + // When satisfiable offer is found, swap and return the user seat. // Swap will throw if the swap fails, no assets will be transferred, // and both seats will fail. If the swap succeeds, both seats will // be exited and the assets will be transferred. @@ -78,22 +87,26 @@ const prepare = async (zcf, privateArgs, baggage) => { return seat; } } + // Return undefined if no satisfiable offer was found. return undefined; }; // Process an incoming offer. If the offer can be satisfied, swap and remove // the counter offer from the counterOffers storage. If the offer cannot be - // satisfied, add the offer to the counterOffers storage. + // satisfied, add the seat to the counterOffers storage. const swapIfCanTradeAndUpdateBook = (counterOffers, coOffers, userSeat) => { // try to execute a swap const seat = swapIfCanTrade(counterOffers, userSeat); + if (seat) { + // if the swap succeeded, remove the offer from the counterOffers storage counterOffers = counterOffers.delete(seat); } else { + // if the swap was not executed, add the offer to the coOffers storage coOffers.init(userSeat, userSeat.getProposal()); } - // notify the subscriber that the order book has changed. + // Update the subscriber state with the changes made to the order book. updateOrderBook(); }; @@ -106,6 +119,13 @@ const prepare = async (zcf, privateArgs, baggage) => { // Get the proposal from the seat. const { want, give } = seat.getProposal(); + // Check if the proposal is a buy or sell offer. + + // Buy offer is an offer that wants Asset and gives Price, give.Asset + // in this case is undefined. + + // Sell offer is an offer that wants Price and gives Asset, want.Asset + // in this case is undefined. if (want.Asset) { // If the proposal is a buy, try to execute a swap with the sell book. swapIfCanTradeAndUpdateBook(sellSeatsMap, buySeatsMap, seat); @@ -124,7 +144,7 @@ const prepare = async (zcf, privateArgs, baggage) => { }; // Create an invitation to the contract. The incoming offer will be handled - // by the exchangeOfferHandler function. Incoming offer seat must match the + // by the exchangeOfferHandler function. Incoming offerProposal must match the // proposal shape defined by the contract - both give and want must be either // Asset or Price. const makeExchangeInvitation = () => { @@ -139,9 +159,11 @@ const prepare = async (zcf, privateArgs, baggage) => { ); }; - // The publicFacet has a function that allows users to create invitations - // to the contract, and a function that returns a subscriber that will update - // when the order book changes. + // The publicFacet has a function that allows users to create the + // invitation to exercise a sell or buy offer, and a function that + // returns a subscriber that will update when the order book changes. + // The publicFacet has a baggage parameter that is used to store the + // durable storage of the contract and preserve it across upgrades. const publicFacet = prepareExo( baggage, 'publicFacet', @@ -163,7 +185,6 @@ const prepare = async (zcf, privateArgs, baggage) => { {}, ); - // Return the facets of the contract. return harden({ creatorFacet, publicFacet }); };