From c02c07bca61a1cf1cc1829a8abe1a6a3b041739c Mon Sep 17 00:00:00 2001
From: jermaine150 <jermaine150@gmail.com>
Date: Wed, 25 Oct 2023 13:03:10 +0200
Subject: [PATCH] Updating main architecture index and adding sale contracts
---
.../src/pages/marmalade/architecture/index.md | 14 ++---
.../marmalade/architecture/sale-contracts.md | 57 +++++++++++++++++++
2 files changed, 64 insertions(+), 7 deletions(-)
create mode 100644 packages/apps/docs/src/pages/marmalade/architecture/sale-contracts.md
diff --git a/packages/apps/docs/src/pages/marmalade/architecture/index.md b/packages/apps/docs/src/pages/marmalade/architecture/index.md
index 05cfe3dc90..bb7a9495cd 100644
--- a/packages/apps/docs/src/pages/marmalade/architecture/index.md
+++ b/packages/apps/docs/src/pages/marmalade/architecture/index.md
@@ -10,7 +10,7 @@ layout: full
# Marmalade Architecture
The introduction of the multi-policy model in Marmalade V2, with the inclusion
-of middleware contracts like quote-manager and policy-manager, aims to enhance
+of middleware contracts like policy-manager and sale-contracts, aims to enhance
the user experience by simplifying token creation and management.
## Ledger
@@ -22,7 +22,7 @@ and it offers the following main functions:
token\
**mint**: mints token\
**burn**: burns token\
-**Transfer**: transfers token from a Marmalade account to another Marmalade account\
+**transfer**: transfers token from a Marmalade account to another Marmalade account\
**[sale] offer**: 1st step of sale, transfers the token from the seller to an
escrow\
**[sale] buy**: 2nd step of sale, transfers the token to from escrow to the buyer\
@@ -61,11 +61,11 @@ quoted price from the buyer to an escrow account, disburses a portion of the
reserved fees to the policies, and then remits the remaining quoted price to the
seller.
+## Sale Contracts
-## Sale Whitelists
+The Sale Contract is a contract responsible for updating the final price
+of the quote during the buy process. By managing sale contracts within Marmalade, we can provide users a
+safe way to participate in various sale features such as creative auctions, while also guaranteeing royalty payout.
-The Sale Contract is a contract responsible for updating quotes, thereby allowing
-auction system.
+**[Marmalade on GitHub](https://github.com/kadena-io/marmalade)**
-**Offical GitHub Link**:
-https://github.com/kadena-io/marmalade/blob/v2/test-marmalade-v2.md
diff --git a/packages/apps/docs/src/pages/marmalade/architecture/sale-contracts.md b/packages/apps/docs/src/pages/marmalade/architecture/sale-contracts.md
new file mode 100644
index 0000000000..f2a41119bb
--- /dev/null
+++ b/packages/apps/docs/src/pages/marmalade/architecture/sale-contracts.md
@@ -0,0 +1,57 @@
+---
+title: Sale Contracts
+description: Sale Contracts in Marmalade V2
+menu: Sale Contracts
+label: Sale Contracts
+order: 3
+layout: full
+---
+
+# Sale Contracts
+
+With Sale Contracts, Marmalade V2 introduces a new way to manage the sale of a token. WHen offering a token up for sale in the ledger, it is now possible to also provide a reference to a sale contract. This sale contract can then be used to manage the sale of the token which allows for maximum flexibility and creativity in the sale of a token.
+
+Security is an important aspect of selling a token, especially when it comes to guaranteeing royalty. Therefore the sale contracts are required to be registered within the Policy Manager. This ensures that the sale contract is known to the Policy Manager and that the Policy Manager can enforce the sale contract. Before registering the sale contract will undergo a review process to ensure that it is safe to use.
+
+Where Sale Contracts are aimed at general purpose sales, Marmalade token creators still have complete flexibility to implement any custom sale logic within a policy and attach it to the token itself. This allows for a wide range of sale options and flexibility.
+
+## Sale Contract Interface
+
+The sale contract interface is a light interface which needs to be implemented by any sale contract. It is used by the Policy Manager to enforce the sale contract. The interface is defined as follows:
+
+```pact
+(defun enforce-quote-update:bool (sale-id:string price:decimal)
+ @doc "Read-only Function that is enforced to update quote price at enforce-buy"
+)
+```
+
+The function `enforce-quote-update` is called in from the `buy` step in the ledger and takes two parameters:
+
+- sale-id (type: string): This parameter represents the identifier of the sale, which is basicaly the pact-id that is created when the token is offered up for sale in the ledger.
+- price (type: decimal): This parameter represents the finale price associated with the sale.
+
+## Available Sale Contracts
+
+**Conventional Auction**
+
+A conventional auction is a sale contract that allows for the sale of a token through a conventional auction. The seller can set a reserve price which will ensure that the token is not sold below a certain price. The auction will run for a set amount of time and the highest bidder will win the auction. If the reserve price is not met, the seller can choose to cancel the auction and the token will be returned to the seller.
+The contract is deployed at `marmalade-sale.conventional-auction`.
+
+More sale contracts will follow but in the meantime, you can also create your own sale contract. The sale contracts can be found in the [Marmalade Github repository](https://github.com/kadena-io/marmalade) under `pact/sale-contracts`. Just create a pull request and we will review your sale contract and take care of deployment and whitelisting it in the Policy Manager.
+
+## Using a Sale Contract
+The sale contract can be used by providing the sale contract's module name as part of the quote specification when calling the `offer` function in the ledger. Here's an example of the quote specification with the sale contract's module name mentioned under the key `sale-type`.
+
+```pact
+"quote" : {
+ "fungible": coin
+ ,"sale-price": 0.0
+ ,"seller-fungible-account": {
+ "account": "k:seller"
+ ,"guard": {"keys": ["seller"], "pred": "keys-all"}
+ }
+ ,"sale-type": "marmalade-sale.conventional-auction"
+}
+```
+
+**_Note:_** When using a sale contract the `sale-price` during `offer` must always be `0.0`, since the sale contract will be responsible for updating the price during the `buy` step.
\ No newline at end of file