From 7f3332c01453539059d4019d90d425544fe9b833 Mon Sep 17 00:00:00 2001 From: Kris Bennett Date: Wed, 22 May 2024 11:00:51 -0600 Subject: [PATCH 1/3] Create explainer for postal service contract --- .../postal-service-contract-explainer.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 main/guides/getting-started/postal-service-contract-explainer.md diff --git a/main/guides/getting-started/postal-service-contract-explainer.md b/main/guides/getting-started/postal-service-contract-explainer.md new file mode 100644 index 000000000..5668ec6ef --- /dev/null +++ b/main/guides/getting-started/postal-service-contract-explainer.md @@ -0,0 +1,64 @@ +# Understanding the Agoric Postal Service Contract + +This contract is implemented using the Zoe Contract Facet (ZCF) and demonstrates how to create and manage a basic postal service within the blockchain environment. Let's break down the main components and functionalities of this contract. + +## Contract Structure and Components +## 1. Contract Setup: +The contract starts with a setup that includes the terms of the service, typically the price of joining the postal service. This setup is done through the `start` function, which is a standard entry point for Agoric contracts. The function initializes the service and sets up any required assets or parameters. +```javascript +export const start = async (zcf) => { + const { joinPrice } = zcf.getTerms(); + const { zcfSeat: postalSeat } = zcf.makeEmptySeatKit(); + const mint = await zcf.makeZCFMint('PostalToken', AssetKind.NAT); + + // Other initialization logic +}; +``` + +## 2. Minting and Managing Assets: +The contract utilizes the `ZCFMint` object to mint new tokens or assets. In this example, tokens are created to represent the postal services or stamps. +```javascript +const mint = await zcf.makeZCFMint('PostalToken', AssetKind.COPY_BAG); +``` + +## 3. Handling User Requests: +User interactions with the contract are managed through invitations. These invitations allow users to perform specific actions, such as joining the postal service or sending a package. +```javascript +const joinHandler = userSeat => { + const { give, want } = userSeat.getProposal(); + + // Ensure the payment is sufficient + assert(give.Price.value >= joinPrice.value, 'Insufficient payment'); + + // Process the request and update the contract state + userSeat.exit(); + return 'Welcome to the postal service'; +}; + +const publicFacet = Far('API', { + makeJoinInvitation: () => zcf.makeInvitation(joinHandler, 'Join Postal Service'), +}); +``` + +## 4. Public Facet: +The public facet of the contract exposes the functionality that external users can interact with. In this contract, users can create invitations to join the postal service. +```javascript +return { publicFacet }; +``` + +## Deploying and Interacting with the Contract +To deploy this contract, developers use the Agoric CLI tools. The process typically involves bundling the contract code, deploying it to the blockchain, and setting up any necessary client-side interfaces to interact with the contract. + +### 1. Deployment Script: +The deployment script automates the process of installing the contract on the blockchain. +```javascript +const deploy = async (homeP) => { + const { zoe } = homeP; + const bundle = await bundleSource('./src/contract.js'); + const installation = await E(zoe).install(bundle); + console.log('Contract installed:', installation); +}; +``` + +### 2. Client Interaction: +Users interact with the deployed contract through a web interface or directly using CLI commands. They can create and use invitations to join the service, make payments, and manage their assets. From 68755fab91bdfaf163d62d992bb491f93cae0c1c Mon Sep 17 00:00:00 2001 From: Kris Bennett Date: Wed, 22 May 2024 11:29:48 -0600 Subject: [PATCH 2/3] Update navigation to include postal service contract explainer --- main/.vitepress/config.mjs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/main/.vitepress/config.mjs b/main/.vitepress/config.mjs index 24595f050..a120ecd16 100644 --- a/main/.vitepress/config.mjs +++ b/main/.vitepress/config.mjs @@ -446,11 +446,16 @@ export default defineConfig({ text: 'Takeaway 2: Swaparoo Contract Overview', link: '/guides/getting-started/swaparoo-how-to-swap-assets-explainer', }, - + { text: 'Takeaway 3: Sending Invitation Payments using an Address', link: '/guides/getting-started/swaparoo-making-a-payment-explainer', }, + + { + text: 'Takeaway 4: Postal Service Contract Overview', + link: '/guides/getting-started/postal-service-contract-explainer', + }, ], }, { From 16f59a260cb78a541b7f37af156efec972cc7ea7 Mon Sep 17 00:00:00 2001 From: Kris Bennett Date: Wed, 22 May 2024 12:53:52 -0600 Subject: [PATCH 3/3] Update postal-service-contract-explainer.md --- .../guides/getting-started/postal-service-contract-explainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/main/guides/getting-started/postal-service-contract-explainer.md b/main/guides/getting-started/postal-service-contract-explainer.md index 5668ec6ef..4808fda8f 100644 --- a/main/guides/getting-started/postal-service-contract-explainer.md +++ b/main/guides/getting-started/postal-service-contract-explainer.md @@ -1,6 +1,6 @@ # Understanding the Agoric Postal Service Contract -This contract is implemented using the Zoe Contract Facet (ZCF) and demonstrates how to create and manage a basic postal service within the blockchain environment. Let's break down the main components and functionalities of this contract. +This contract is implemented using the Zoe Contract Facet (ZCF) and demonstrates how to create and manage a basic postal service. Let's break down the main components and functionalities of this contract. ## Contract Structure and Components ## 1. Contract Setup: