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', + }, ], }, { 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..4808fda8f --- /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. 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.