diff --git a/README.md b/README.md index d81d34746..ad9c7b3b7 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,9 @@ Get started building on ICP with the sample applications in this repository. Fro The projects in this repository are not intended to be used as commercial applications and do not provide any explicit or implied support or warranty of any kind. -You can also contribute your own project or suggest updates to published projects using the standard GitHub workflow. - ## Sample applications -**New here?** Start with [hello_world](motoko/hello_world/) (Motoko) or [hello_world](rust/hello_world/) (Rust) — a simple full-stack canister with a frontend. For user authentication with Internet Identity, see [who_am_i](motoko/who_am_i/) or [who_am_i](rust/who_am_i/). +**New here?** Start with `hello_world` ([Motoko](motoko/hello_world/) or [Rust](rust/hello_world/)) — a simple full-stack canister with a frontend. Then move on to `who_am_i` ([Motoko](motoko/who_am_i/) or [Rust](rust/who_am_i/)) to add user authentication with [Internet Identity](https://docs.internetcomputer.org/guides/authentication/internet-identity). Canister examples are organized by language: @@ -21,6 +19,7 @@ Frontend-only and native app examples: - [hosting/](hosting/) — frontend examples (React, static sites, etc.) - [native-apps/](native-apps/) — Unity and other native app integrations +- [wasm/](wasm/) — canisters written directly in WebAssembly ## Local development diff --git a/hosting/README.md b/hosting/README.md index f925bad14..36c7a4957 100644 --- a/hosting/README.md +++ b/hosting/README.md @@ -1,7 +1,22 @@ # Hosting examples -## Basic +Frontend-only examples that run entirely on the Internet Computer — static sites, web apps, and game builds served on-chain with no custom backend. Each example is self-contained: follow its README to deploy it locally with `icp-cli`. -- [`static-website`](https://github.com/dfinity/examples/tree/master/hosting/static-website) -- simple HTML website demo. -- [`Unity-WebGL-sample`](https://github.com/dfinity/examples/tree/master/hosting/unity-webgl-template) -- simple Unity WebGL sample. -- [`Godot-HTML5-sample`](https://github.com/dfinity/examples/tree/master/hosting/godot-html5-template) -- Godot HTML5 sample. +These examples use the `@dfinity/static-site` recipe, which deploys the [certified-assets canister](https://github.com/dfinity/certified-assets) — the successor of the legacy [asset canister](https://docs.internetcomputer.org/guides/frontends/asset-canister) going forward, adding response certification, clean-URL canonicalization, and `_headers`/`_redirects` configuration. The one deliberate exception is [`photo-storage`](photo-storage/): it demonstrates programmatic uploads via `AssetManager`, an API only the legacy asset canister provides. + +**New to ICP?** Start with [`static-website`](static-website/), the smallest possible deployment, then [`react`](react/) for a typical single-page app setup. + +Prerequisites and dev-container setup are covered in the [repository README](../README.md). + +## Examples + +- [`static-website`](static-website/) — deploy a plain HTML/CSS website on ICP. +- [`react`](react/) — a minimal React single-page application hosted fully on-chain. +- [`photo-storage`](photo-storage/) — store and manage photos programmatically with `AssetManager` from `@icp-sdk/canisters/assets` (runs on the legacy asset canister). +- [`godot-html5-template`](godot-html5-template/) — deploy a Godot HTML5 game build. +- [`unity-webgl-template`](unity-webgl-template/) — deploy a Unity WebGL game build. +- [`oisy-signer-demo`](oisy-signer-demo/) — connect to the OISY wallet signer, fetch token balances, and perform ICRC transfers. + +## Security considerations and best practices + +If you base your application on one of these examples, we recommend you familiarize yourself with and adhere to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices. diff --git a/motoko/README.md b/motoko/README.md index fd02502c4..1cfeccaff 100644 --- a/motoko/README.md +++ b/motoko/README.md @@ -1,7 +1,63 @@ # Motoko examples -These examples demonstrate the use of Motoko as a backend language on the ICP platform. +Canonical examples for building canisters on the Internet Computer with [Motoko](https://docs.internetcomputer.org/languages/motoko). Each example is self-contained: follow its README to deploy it locally with `icp-cli` and run its tests. Most examples have a Rust counterpart in [`../rust/`](../rust/) implementing the same Candid interface. -## Security considerations and security best practices +**New to ICP?** Start with [`hello_world`](hello_world/) — a full-stack canister with a frontend and the structural template for all examples. Then try [`who_am_i`](who_am_i/) for user authentication with [Internet Identity](https://docs.internetcomputer.org/guides/authentication/internet-identity). -If you base your application on one of these examples, it is recommended that you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/building-apps/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices. +Prerequisites and dev-container setup are covered in the [repository README](../README.md). + +## Getting started + +- [`hello_world`](hello_world/) — full-stack "Hello, world!" with a Motoko backend and a Vite frontend. +- [`backend_only`](backend_only/) — the minimal canister: a single `greet` query function, no frontend. +- [`who_am_i`](who_am_i/) — sign in with Internet Identity and see the principal your app receives. + +## Full-stack applications + +- [`daily_planner`](daily_planner/) — monthly calendar with notes and tasks; fetches historic facts via HTTPS outcalls. +- [`superheroes`](superheroes/) — CRUD application with a React frontend. +- [`filevault`](filevault/) — upload, download, and delete files stored per Internet Identity principal. +- [`flying_ninja`](flying_ninja/) — 2D side-scroller game with an on-chain leaderboard. +- [`ic-pos`](ic-pos/) — point-of-sale app accepting ICRC-1 token payments via QR codes. +- [`llm_chatbot`](llm_chatbot/) — chat with a large language model from a canister. + +## Tokens and payments + +- [`icp_transfer`](icp_transfer/) — hold ICP in a canister and send it to other accounts via the ICP ledger. +- [`icrc2-swap`](icrc2-swap/) — safe inter-canister call patterns for ICRC-2 token swaps. + +## Chain fusion and signing + +- [`basic_bitcoin`](basic_bitcoin/) — send and receive Bitcoin using threshold ECDSA and Schnorr signatures. +- [`threshold-ecdsa`](threshold-ecdsa/) — a threshold ECDSA signing oracle. +- [`threshold-schnorr`](threshold-schnorr/) — a threshold Schnorr (BIP340/BIP341, Ed25519) signing oracle. +- [`evm_block_explorer`](evm_block_explorer/) — fetch block data from Ethereum and other EVM chains via the EVM RPC canister. + +## HTTPS outcalls + +- [`send_http_get`](send_http_get/) — make a `GET` request to an external API from a canister. +- [`send_http_post`](send_http_post/) — make a `POST` request to an external API from a canister. + +## Inter-canister patterns + +- [`parallel_calls`](parallel_calls/) — parallel vs. sequential inter-canister calls. +- [`pub-sub`](pub-sub/) — publisher/subscriber messaging using shared function references as callbacks. +- [`composite_query`](composite_query/) — query functions that call other canisters' queries. +- [`canister_factory`](canister_factory/) — create canisters dynamically via actor classes and the management canister. + +## System features + +- [`hello_cycles`](hello_cycles/) — the fundamental cycle management operations. +- [`canister_logs`](canister_logs/) — canister logging with `Debug.print` and trap records. +- [`low_wasm_memory`](low_wasm_memory/) — react to low Wasm memory with the `lowmemory` system hook. +- [`query_stats`](query_stats/) — read a canister's own query statistics. +- [`cert-var`](cert-var/) — certified variables: cryptographically verifiable query responses. +- [`random_maze`](random_maze/) — cryptographic randomness from the network's random beacon. + +## Encryption with vetKeys + +The [`vetkeys/`](vetkeys/) directory contains examples for [vetKeys](https://docs.internetcomputer.org/concepts/vetkeys), from the low-level API to complete applications: [`basic_vetkd`](vetkeys/basic_vetkd/), [`basic_ibe`](vetkeys/basic_ibe/), [`basic_bls_signing`](vetkeys/basic_bls_signing/), [`password_manager`](vetkeys/password_manager/), [`password_manager_with_metadata`](vetkeys/password_manager_with_metadata/), and [`encrypted_notes_app_vetkd`](vetkeys/encrypted_notes_app_vetkd/). + +## Security considerations and best practices + +If you base your application on one of these examples, we recommend you familiarize yourself with and adhere to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices. diff --git a/motoko/ic-pos/README.md b/motoko/ic-pos/README.md index d067eaef0..079de02ed 100644 --- a/motoko/ic-pos/README.md +++ b/motoko/ic-pos/README.md @@ -1,6 +1,6 @@ # IC-POS -IC-POS is a simple Point of Sale (POS) app that accepts [ICRC-1](https://github.com/dfinity/ICRC-1) token payments on the Internet Computer. A merchant logs in with [Internet Identity](https://internetcomputer.org/internet-identity), configures a store, and charges customers by showing a QR code; incoming payments show up in the store with a live balance and transaction history. +IC-POS is a simple Point of Sale (POS) app that accepts [ICRC-1](https://github.com/dfinity/ICRC-1) token payments on the Internet Computer. A merchant logs in with [Internet Identity](https://docs.internetcomputer.org/guides/authentication/internet-identity), configures a store, and charges customers by showing a QR code; incoming payments show up in the store with a live balance and transaction history. To let you try the full flow without spending real funds, this example uses the **TICRC1 test token** ([`3jkp5-oyaaa-aaaaj-azwqa-cai`](https://dashboard.internetcomputer.org/canister/3jkp5-oyaaa-aaaaj-azwqa-cai)) on mainnet, and a local ICRC-1 ledger + index when developing. Because the app talks to any ICRC-1 ledger, the same code works with real tokens (e.g. [ckBTC](https://internetcomputer.org/ckbtc/)) by pointing it at a different ledger. diff --git a/motoko/vetkeys/README.md b/motoko/vetkeys/README.md new file mode 100644 index 000000000..d332bfaf0 --- /dev/null +++ b/motoko/vetkeys/README.md @@ -0,0 +1,21 @@ +# vetKeys examples (Motoko) + +Examples for [vetKeys](https://docs.internetcomputer.org/concepts/vetkeys) — verifiably encrypted threshold key derivation, the Internet Computer's primitive for on-chain encryption. Each example is self-contained: follow its README to deploy it locally with `icp-cli`. Rust counterparts live in [`../../rust/vetkeys/`](../../rust/vetkeys/). + +**Start with** [`basic_vetkd`](basic_vetkd/) to understand the raw API, then move to the SDK-based examples. + +## Basics + +- [`basic_vetkd`](basic_vetkd/) — the raw VetKD management canister API: symmetric key derivation and IBE without any SDK abstraction. +- [`basic_ibe`](basic_ibe/) — secure messaging with Identity-Based Encryption, using Internet Identity principals as encryption keys. +- [`basic_bls_signing`](basic_bls_signing/) — a threshold BLS signing service where users can only sign for their own principal. + +## Applications + +- [`password_manager`](password_manager/) — a decentralized password manager built on Encrypted Maps, with shareable vaults. +- [`password_manager_with_metadata`](password_manager_with_metadata/) — extends the password manager with unencrypted metadata alongside encrypted passwords. +- [`encrypted_notes_app_vetkd`](encrypted_notes_app_vetkd/) — end-to-end encrypted note-taking with multi-device access and note sharing. + +## Security considerations and best practices + +If you base your application on one of these examples, we recommend you familiarize yourself with and adhere to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices. diff --git a/native-apps/README.md b/native-apps/README.md new file mode 100644 index 000000000..10c8eac43 --- /dev/null +++ b/native-apps/README.md @@ -0,0 +1,13 @@ +# Native app examples + +Examples for integrating native applications (mobile, desktop, game engines) with canisters on the Internet Computer. Each example is self-contained: follow its README to deploy the canister side with `icp-cli` and build the native app. + +Prerequisites and dev-container setup are covered in the [repository README](../README.md). + +## Examples + +- [`unity_ii_deeplink`](unity_ii_deeplink/) — authenticate a Unity mobile app through [Internet Identity](https://docs.internetcomputer.org/guides/authentication/internet-identity) using a browser-based bridge canister and deep-link callbacks, then call a canister with the resulting delegation. + +## Security considerations and best practices + +If you base your application on one of these examples, we recommend you familiarize yourself with and adhere to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices. diff --git a/native-apps/unity_ii_deeplink/README.md b/native-apps/unity_ii_deeplink/README.md index fd9a98300..ddc8e5fc4 100644 --- a/native-apps/unity_ii_deeplink/README.md +++ b/native-apps/unity_ii_deeplink/README.md @@ -1,6 +1,6 @@ # Unity + Internet Identity -This example shows how a Unity mobile app can authenticate users through [Internet Identity](https://internetcomputer.org/internet-identity) and call an ICP canister using the resulting delegation identity. +This example shows how a Unity mobile app can authenticate users through [Internet Identity](https://docs.internetcomputer.org/guides/authentication/internet-identity) and call an ICP canister using the resulting delegation identity. The example consists of three parts: diff --git a/rust/README.md b/rust/README.md new file mode 100644 index 000000000..339d63985 --- /dev/null +++ b/rust/README.md @@ -0,0 +1,80 @@ +# Rust examples + +Canonical examples for building canisters on the Internet Computer with [Rust](https://docs.internetcomputer.org/languages/rust). Each example is self-contained: follow its README to deploy it locally with `icp-cli` and run its tests. Most examples have a Motoko counterpart in [`../motoko/`](../motoko/) implementing the same Candid interface. + +**New to ICP?** Start with [`hello_world`](hello_world/) — a full-stack canister with a frontend and the structural template for all examples. Then try [`who_am_i`](who_am_i/) for user authentication with [Internet Identity](https://docs.internetcomputer.org/guides/authentication/internet-identity). + +Prerequisites and dev-container setup are covered in the [repository README](../README.md). + +## Getting started + +- [`hello_world`](hello_world/) — full-stack "Hello, world!" with a Rust backend and a Vite frontend. +- [`backend_only`](backend_only/) — the minimal canister: a single `greet` query function, no frontend. +- [`backend_wasm64`](backend_wasm64/) — the same minimal canister compiled for the Wasm64 target. +- [`who_am_i`](who_am_i/) — sign in with Internet Identity and see the principal your app receives. + +## Full-stack applications + +- [`daily_planner`](daily_planner/) — monthly calendar with notes and tasks; fetches historic facts via HTTPS outcalls. +- [`flying_ninja`](flying_ninja/) — 2D side-scroller game with an on-chain leaderboard. +- [`photo_gallery`](photo_gallery/) — upload and view photos served via the HTTP gateway with cacheable responses. +- [`llm_chatbot`](llm_chatbot/) — chat with a large language model from a canister. + +## Tokens and payments + +- [`icp_transfer`](icp_transfer/) — hold ICP in a canister and send it to other accounts via the ICP ledger. +- [`receiving-icp`](receiving-icp/) — generate account identifiers and check balances to receive ICP. +- [`exchange-rates`](exchange-rates/) — query crypto and fiat exchange rates from the Exchange Rate Canister (XRC). +- [`stake_neuron_from_cli`](stake_neuron_from_cli/) — stake ICP into an NNS neuron from a Rust CLI binary using `ic-agent`. + +## Chain fusion and signing + +- [`basic_bitcoin`](basic_bitcoin/) — send and receive Bitcoin (P2PKH, P2WPKH, P2TR addresses). +- [`basic_ethereum`](basic_ethereum/) — send and receive Ether using threshold ECDSA. +- [`evm_block_explorer`](evm_block_explorer/) — fetch block data from Ethereum and other EVM chains via the EVM RPC canister. +- [`threshold-ecdsa`](threshold-ecdsa/) — a threshold ECDSA signing oracle. +- [`threshold-schnorr`](threshold-schnorr/) — a threshold Schnorr (BIP340/BIP341, Ed25519) signing oracle. +- [`x509`](x509/) — issue and verify X.509 certificates with threshold signatures. + +## HTTPS outcalls + +- [`send_http_get`](send_http_get/) — make a `GET` request to an external API from a canister. +- [`send_http_post`](send_http_post/) — make a `POST` request to an external API from a canister. + +## Inter-canister patterns + +- [`inter-canister-calls`](inter-canister-calls/) — bounded-wait and unbounded-wait calls, retries, and attaching cycles. +- [`parallel_calls`](parallel_calls/) — parallel vs. sequential inter-canister calls. +- [`composite_query`](composite_query/) — query functions that call other canisters' queries. +- [`guards`](guards/) — how guard functions interact with asynchronous code. +- [`candid_type_generation`](candid_type_generation/) — generate Rust types from an external canister's `.did` file. + +## Canister operations and system features + +- [`canister-info`](canister-info/) — retrieve metadata about any canister via the management canister. +- [`canister-snapshots`](canister-snapshots/) — take and restore canister snapshots. +- [`canister-snapshot-download`](canister-snapshot-download/) — download and upload canister snapshots. +- [`canister_logs`](canister_logs/) — canister logging, traps, panics, and error handling. +- [`low_wasm_memory`](low_wasm_memory/) — react to low Wasm memory with the `on_low_wasm_memory` hook. +- [`periodic_tasks`](periodic_tasks/) — timers and heartbeats for scheduled execution. +- [`performance_counters`](performance_counters/) — measure the work a canister performs. +- [`query_stats`](query_stats/) — read a canister's own query statistics. + +## Compute and AI + +- [`image-classification`](image-classification/) — run an ONNX machine-learning model inside a canister. +- [`face-recognition`](face-recognition/) — face detection and recognition with the Tract ONNX engine. +- [`qrcode`](qrcode/) — long-running image processing in a single message execution. +- [`simd`](simd/) — WebAssembly SIMD acceleration for compute-heavy workloads. + +## Testing + +- [`unit_testable_rust_canister`](unit_testable_rust_canister/) — structure a canister for comprehensive unit testing. + +## Encryption with vetKeys + +The [`vetkeys/`](vetkeys/) directory contains examples for [vetKeys](https://docs.internetcomputer.org/concepts/vetkeys), from the low-level API to complete applications: [`basic_vetkd`](vetkeys/basic_vetkd/), [`basic_ibe`](vetkeys/basic_ibe/), [`basic_timelock_ibe`](vetkeys/basic_timelock_ibe/), [`basic_bls_signing`](vetkeys/basic_bls_signing/), [`password_manager`](vetkeys/password_manager/), [`password_manager_with_metadata`](vetkeys/password_manager_with_metadata/), and [`encrypted_notes_app_vetkd`](vetkeys/encrypted_notes_app_vetkd/). + +## Security considerations and best practices + +If you base your application on one of these examples, we recommend you familiarize yourself with and adhere to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices. diff --git a/rust/vetkeys/README.md b/rust/vetkeys/README.md index da75b3165..27e09b98c 100644 --- a/rust/vetkeys/README.md +++ b/rust/vetkeys/README.md @@ -1,14 +1,22 @@ -# vetKeys Examples +# vetKeys examples (Rust) -## Basic Examples -- **[Password Manager](https://github.com/dfinity/vetkeys/tree/main/examples/password_manager)** - A secure, decentralized password manager using Encrypted Maps for vault-based password storage and sharing. -- **[Password Manager with Metadata](https://github.com/dfinity/vetkeys/tree/main/examples/password_manager_with_metadata)** - Extends the basic password manager to support unencrypted metadata alongside encrypted passwords. -- **[Encrypted Notes](https://github.com/dfinity/vetkeys/tree/main/examples/encrypted_notes_dapp_vetkd)** - A secure note-taking application that uses vetKeys for encryption and enables sharing notes between users without device management. +Examples for [vetKeys](https://docs.internetcomputer.org/concepts/vetkeys) — verifiably encrypted threshold key derivation, the Internet Computer's primitive for on-chain encryption. Each example is self-contained: follow its README to deploy it locally with `icp-cli`. Motoko counterparts live in [`../../motoko/vetkeys/`](../../motoko/vetkeys/). -## Advanced Examples +**Start with** [`basic_vetkd`](basic_vetkd/) to understand the raw API, then move to the SDK-based examples. -- **[Threshold BLS Signature](https://github.com/dfinity/vetkeys/tree/main/examples/basic_bls_signing)** - Demonstrates how to use vetKeys to create a threshold BLS signing service. +## Basics -- **[Identity-Basic Encryption (IBE)](https://github.com/dfinity/vetkeys/tree/main/examples/basic_ibe)** - Shows how to implement secure messaging using Identity Based Encryption with Internet Identity Principals as encryption keys. +- [`basic_vetkd`](basic_vetkd/) — the raw VetKD management canister API: symmetric key derivation and IBE without any SDK abstraction. +- [`basic_ibe`](basic_ibe/) — secure messaging with Identity-Based Encryption, using Internet Identity principals as encryption keys. +- [`basic_timelock_ibe`](basic_timelock_ibe/) — a secret-bid auction where bids stay encrypted until the deadline (timelock encryption). +- [`basic_bls_signing`](basic_bls_signing/) — a threshold BLS signing service where users can only sign for their own principal. -- **[Timelock Encryption](https://github.com/dfinity/vetkeys/tree/main/examples/basic_timelock_ibe)** - Implements a secret-bid auction system where bids remain encrypted until the auction is opened. +## Applications + +- [`password_manager`](password_manager/) — a decentralized password manager built on Encrypted Maps, with shareable vaults. +- [`password_manager_with_metadata`](password_manager_with_metadata/) — extends the password manager with unencrypted metadata alongside encrypted passwords. +- [`encrypted_notes_app_vetkd`](encrypted_notes_app_vetkd/) — end-to-end encrypted note-taking with multi-device access and note sharing. + +## Security considerations and best practices + +If you base your application on one of these examples, we recommend you familiarize yourself with and adhere to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices. diff --git a/wasm/README.md b/wasm/README.md new file mode 100644 index 000000000..c93b00738 --- /dev/null +++ b/wasm/README.md @@ -0,0 +1,13 @@ +# WebAssembly examples + +Examples of canisters written directly in WebAssembly, without a higher-level language or CDK. They show what a canister looks like at the lowest level — useful for understanding the [Internet Computer interface specification](https://docs.internetcomputer.org/references/ic-interface-spec) and for building canisters from languages that compile to Wasm. + +Prerequisites and dev-container setup are covered in the [repository README](../README.md). + +## Examples + +- [`counter`](counter/) — a counter canister hand-written in WebAssembly Text Format (WAT); the compiled module is only 389 bytes. + +## Security considerations and best practices + +If you base your application on one of these examples, we recommend you familiarize yourself with and adhere to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for developing on the Internet Computer. The examples provided here may not implement all the best practices.