From 22c5b2b4f885dfae51feb423acf85e3d622237a7 Mon Sep 17 00:00:00 2001 From: Kristofer Date: Tue, 26 Nov 2024 13:08:59 +0100 Subject: [PATCH] README --- motoko/ic-pos/README.md | 73 ++++++++++++++++++++++++++--------------- 1 file changed, 47 insertions(+), 26 deletions(-) diff --git a/motoko/ic-pos/README.md b/motoko/ic-pos/README.md index 625006c3b..cea9d3ddc 100644 --- a/motoko/ic-pos/README.md +++ b/motoko/ic-pos/README.md @@ -4,8 +4,6 @@ keywords: [advanced, motoko, bitcoin, pos, point of sale, ckbtc] # IC-POS -[View this sample's code on GitHub](https://github.com/dfinity/examples/tree/master/motoko/ic-pos) - ![](./media/header.png) @@ -27,9 +25,9 @@ For deeper understanding of the ICP < > BTC integration, see the IC wiki article IC-POS is deployed on the Internet Computer. You can try it out here: -https://hngac-6aaaa-aaaal-qb6tq-cai.icp0.io/ +https://hngac-6aaaa-aaaal-qb6tq-cai.icp0.io -https://github.com/kristoferlund/ic-pos/assets/9698363/f67d9952-3ee1-4876-a5e5-6ed0e29bae9d +**Note:** The live version of IC-POS uses real ckBTC tokens. To test, use only fractions of a token to avoid losing funds. ## Architecture @@ -56,23 +54,41 @@ The frontend interacts with the following IC canisters: - `ckbtc index` - to fetch transaction history. - `internet identity` - to authenticate users. -# Local deployment +## Setup, dev environment + +Pre-requisites: + +- [Local Internet Computer dev environment](https://internetcomputer.org/docs/current/developer-docs/backend/rust/dev-env) +- [Node 20+](https://nodejs.org/en/) +- [pnpm](https://pnpm.io/installation) + +## Deploy using script + +To get started quickly and deploy the IC-POS app locally, you can run a deploy script. This script will start a local replica, deploy the necessary canisters, and build and deploy the frontend. -## Prerequisites +```bash +bash ./scripts/deploy.sh +``` -- [x] Install the [IC SDK](https://internetcomputer.org/docs/current/developer-docs/setup/install/index.mdx). -- [x] Install [Node.js](https://nodejs.org/en/). -- [x] Clone the example dapp project: `git clone https://github.com/dfinity/examples` +Once the script has finished, you should proceed to step 10 to create a store and mint yourself some test tokens. -### Step 1: Start a local instance of the replica: +## Deploy manually -(To complete steps 1-7 in one go, you can run the `./scripts/deploy.sh` script.) +### 1. Clone the examples repository and navigate to the IC-POS project: + +```bash +git clone https://github.com/dfinity/examples +cd examples/motoko/ic-pos +``` + + +### 2. Start a local instance of the replica: ```bash dfx start --clean --background ``` -### Step 2: Deploy the Internet Identity canister: +### 3. Deploy the Internet Identity canister: Integration with the [Internet Identity](https://internetcomputer.org/internet-identity/) allows store owners to securely setup and manage their store. The Internet Identity canister is already deployed on the IC mainnet. For local development, you need to deploy it to your local instance of the IC. @@ -80,7 +96,7 @@ Integration with the [Internet Identity](https://internetcomputer.org/internet-i dfx deploy internet_identity ``` -### Step 3: Save the current principal as a variable: +### 4. Save the current principal as a variable: The principal will be used when deploying the ledger canister. @@ -88,7 +104,7 @@ The principal will be used when deploying the ledger canister. export OWNER=$(dfx identity get-principal) ``` -### Step 3: Deploy the ckBTC ledger canister: +### 5. Deploy the ckBTC ledger canister: The responsibilities of the ledger canister is to keep track of token balances and handle token transfers. @@ -131,7 +147,7 @@ dfx deploy icrc1_ledger --argument ' ' ``` -### Step 4: Deploy the index canister: +### 6. Deploy the index canister The index canister syncs the ledger transactions and indexes them by account. @@ -143,7 +159,7 @@ dfx deploy icrc1_index --argument ' ' ``` -### Step 5: Deploy the icpos canister: +### 7. Deploy the icpos canister The icpos canister manages the store configuration and sends notifications when a payment is received. @@ -153,31 +169,36 @@ The `--argument '(0)'` argument is used to initialize the canister with `startBl dfx deploy icpos --argument '(0)' ``` -### Step 6: Configure the icpos canister: +### 8. Configure the icpos canister -ic-pos uses [Courier](https://courier.com/) to send email and SMS notifications. If you want to enable notifications, you need to sign up for a Courier account and and create and API key. Then issue the following command: +IC-POS uses [Courier](https://courier.com/) to send email and SMS notifications. If you want to enable notifications, you need to sign up for a Courier account and and create and API key. Then issue the following command: ```bash dfx canister call icpos setCourierApiKey "pk_prod_..." ``` -### Step 7: Build and run the frontend: +### 9. Build and run the frontend -Run npm to install dependencies and start the frontend. The frontend will be available at http://localhost:5173. +Run npm to install dependencies and start a development version of the frontend. ```bash pnpm install -dfx deploy icpos_frontend +pnpm run dev ``` -### Step 8: Make a transfer! + +The app should now be accessible at a local url, typically `http://localhost:5173`. + +### 10. Make a transfer! + + Now that everything is up and running, you can make a transfer to your newly created store. The easiest way to do this is to create two stores using two different Internet Identity accounts, using two different web browsers. Then, transfer some tokens from one store to the other. -#### 8.1: Create the first store and supply it with some tokens: +#### 10.1 Create the first store and supply it with some tokens -Log in to the frontend using the Internet Identity. Configure the store and navigate to the `Receive` page. Click on the principal pill to copy the address to your clipboard. Then, using the `dfx` command, mint some tokens from your owner principal to the store principal. +Log in to the frontend using the Internet Identity. Configure the store with a name and then, on the main store page, click on the principal pill to copy the address to your clipboard. Using the `dfx` command, now mint some tokens from your owner principal to the store principal. ```bash dfx canister call icrc1_ledger icrc1_transfer ' @@ -190,9 +211,9 @@ dfx canister call icrc1_ledger icrc1_transfer ' ' ``` -#### 8.2: Create the second store: +#### 10.2 Create the second store -Log in to the frontend using **a new Internet Identity on another web browser**. Configure the store and navigate to the `Receive` page. Click on the principal pill to copy the address to your clipboard. +Log in to the frontend using **a new Internet Identity using another web browser**. Give this store a name as well and copy the store principal like in the previous step. Now, go back to the first browser/store, navigate to the `Send` page, and transfer some tokens to the second store.