Merge pull request #1743 from demergent-labs/documentation

Improving documentation
demergent-labs · Apr 18, 2024 · 8cf55f7 · 8cf55f7
2 parents d12dc7f + 326e8fb
commit 8cf55f7
Show file tree

Hide file tree

Showing 191 changed files with 4,201 additions and 795 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -50,7 +50,7 @@ jobs:
             - if: contains(github.head_ref, 'release--')
               name: Install dfx
               run: |
-                  DFXVM_INIT_YES=true DFX_VERSION=0.18.0 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
+                  DFXVM_INIT_YES=true DFX_VERSION=0.19.0 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
                   echo "$HOME/.local/share/dfx/bin" >> $GITHUB_PATH
             # TODO we should use some Action-specific bot account
             - if: contains(github.head_ref, 'release--')
@@ -244,7 +244,7 @@ jobs:
             - if: ${{ needs.release-candidate-deploy.outputs.should_run_tests }}
               name: Install dfx
               run: |
-                  DFXVM_INIT_YES=true DFX_VERSION=0.18.0 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
+                  DFXVM_INIT_YES=true DFX_VERSION=0.19.0 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
                   echo "$HOME/.local/share/dfx/bin" >> $GITHUB_PATH
             - if: ${{ needs.release-candidate-deploy.outputs.should_run_tests }}
               uses: actions/cache@v3

diff --git a/docs/404.html b/docs/404.html
diff --git a/docs/assets.html b/docs/assets.html
diff --git a/docs/authentication.html b/docs/authentication.html
diff --git a/docs/azle.html b/docs/azle.html
diff --git a/docs/candid.html b/docs/candid.html
diff --git a/docs/candid_based_documentation.html b/docs/candid_based_documentation.html
diff --git a/docs/canister_lifecycle.html b/docs/canister_lifecycle.html
diff --git a/docs/canisters_overview.html b/docs/canisters_overview.html
diff --git a/docs/caveats.html b/docs/caveats.html
diff --git a/docs/cross_canister.html b/docs/cross_canister.html
diff --git a/docs/cycles.html b/docs/cycles.html
diff --git a/docs/debugging.html b/docs/debugging.html
diff --git a/docs/deployment.html b/docs/deployment.html
diff --git a/docs/deployment_candid_based.html b/docs/deployment_candid_based.html
diff --git a/docs/examples.html b/docs/examples.html
diff --git a/docs/get_started.html b/docs/get_started.html
diff --git a/docs/hello_world.html b/docs/hello_world.html
diff --git a/docs/http.html b/docs/http.html
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/installation.html b/docs/installation.html
diff --git a/docs/internet_computer_overview.html b/docs/internet_computer_overview.html
diff --git a/docs/limitations.html b/docs/limitations.html
diff --git a/docs/management_canister.html b/docs/management_canister.html
diff --git a/docs/print.html b/docs/print.html
diff --git a/docs/project_structure.html b/docs/project_structure.html
diff --git a/docs/query_methods.html b/docs/query_methods.html
diff --git a/docs/reference/bitcoin.html b/docs/reference/bitcoin.html
diff --git a/docs/reference/call_apis/accept_message.html b/docs/reference/call_apis/accept_message.html
diff --git a/docs/reference/call_apis/arg_data_raw.html b/docs/reference/call_apis/arg_data_raw.html
diff --git a/docs/reference/call_apis/arg_data_raw_size.html b/docs/reference/call_apis/arg_data_raw_size.html
diff --git a/docs/reference/call_apis/call.html b/docs/reference/call_apis/call.html
diff --git a/docs/reference/call_apis/call_apis.html b/docs/reference/call_apis/call_apis.html
diff --git a/docs/reference/call_apis/call_raw.html b/docs/reference/call_apis/call_raw.html
diff --git a/docs/reference/call_apis/call_raw128.html b/docs/reference/call_apis/call_raw128.html
diff --git a/docs/reference/call_apis/call_with_payment.html b/docs/reference/call_apis/call_with_payment.html
diff --git a/docs/reference/call_apis/call_with_payment128.html b/docs/reference/call_apis/call_with_payment128.html
diff --git a/docs/reference/call_apis/caller.html b/docs/reference/call_apis/caller.html
diff --git a/docs/reference/call_apis/method_name.html b/docs/reference/call_apis/method_name.html
diff --git a/docs/reference/call_apis/msg_cycles_accept.html b/docs/reference/call_apis/msg_cycles_accept.html
diff --git a/docs/reference/call_apis/msg_cycles_accept128.html b/docs/reference/call_apis/msg_cycles_accept128.html
diff --git a/docs/reference/call_apis/msg_cycles_available.html b/docs/reference/call_apis/msg_cycles_available.html
diff --git a/docs/reference/call_apis/msg_cycles_available128.html b/docs/reference/call_apis/msg_cycles_available128.html
diff --git a/docs/reference/call_apis/msg_cycles_refunded.html b/docs/reference/call_apis/msg_cycles_refunded.html
diff --git a/docs/reference/call_apis/msg_cycles_refunded128.html b/docs/reference/call_apis/msg_cycles_refunded128.html
diff --git a/docs/reference/call_apis/notify.html b/docs/reference/call_apis/notify.html
diff --git a/docs/reference/call_apis/notify_raw.html b/docs/reference/call_apis/notify_raw.html
diff --git a/docs/reference/call_apis/notify_with_payment_128.html b/docs/reference/call_apis/notify_with_payment_128.html
diff --git a/docs/reference/call_apis/reject.html b/docs/reference/call_apis/reject.html
diff --git a/docs/reference/call_apis/reject_code.html b/docs/reference/call_apis/reject_code.html
diff --git a/docs/reference/call_apis/reject_message.html b/docs/reference/call_apis/reject_message.html
diff --git a/docs/reference/call_apis/reply.html b/docs/reference/call_apis/reply.html
diff --git a/docs/reference/call_apis/reply_raw.html b/docs/reference/call_apis/reply_raw.html
diff --git a/docs/reference/candid/blob.html b/docs/reference/candid/blob.html
diff --git a/docs/reference/candid/bool.html b/docs/reference/candid/bool.html
diff --git a/docs/reference/candid/candid.html b/docs/reference/candid/candid.html
diff --git a/docs/reference/candid/empty.html b/docs/reference/candid/empty.html
diff --git a/docs/reference/candid/float32.html b/docs/reference/candid/float32.html
diff --git a/docs/reference/candid/float64.html b/docs/reference/candid/float64.html
diff --git a/docs/reference/candid/func.html b/docs/reference/candid/func.html
diff --git a/docs/reference/candid/int.html b/docs/reference/candid/int.html
diff --git a/docs/reference/candid/int16.html b/docs/reference/candid/int16.html
diff --git a/docs/reference/candid/int32.html b/docs/reference/candid/int32.html
diff --git a/docs/reference/candid/int64.html b/docs/reference/candid/int64.html
diff --git a/docs/reference/candid/int8.html b/docs/reference/candid/int8.html
diff --git a/docs/reference/candid/nat.html b/docs/reference/candid/nat.html
diff --git a/docs/reference/candid/nat16.html b/docs/reference/candid/nat16.html
diff --git a/docs/reference/candid/nat32.html b/docs/reference/candid/nat32.html
diff --git a/docs/reference/candid/nat64.html b/docs/reference/candid/nat64.html
diff --git a/docs/reference/candid/nat8.html b/docs/reference/candid/nat8.html
diff --git a/docs/reference/candid/null.html b/docs/reference/candid/null.html
diff --git a/docs/reference/candid/opt.html b/docs/reference/candid/opt.html
diff --git a/docs/reference/candid/principal.html b/docs/reference/candid/principal.html
diff --git a/docs/reference/candid/record.html b/docs/reference/candid/record.html
diff --git a/docs/reference/candid/reserved.html b/docs/reference/candid/reserved.html
diff --git a/docs/reference/candid/service.html b/docs/reference/candid/service.html
diff --git a/docs/reference/candid/text.html b/docs/reference/candid/text.html
diff --git a/docs/reference/candid/variant.html b/docs/reference/candid/variant.html
diff --git a/docs/reference/candid/vec.html b/docs/reference/candid/vec.html
diff --git a/docs/reference/canister_apis/candid_decode.html b/docs/reference/canister_apis/candid_decode.html
diff --git a/docs/reference/canister_apis/candid_encode.html b/docs/reference/canister_apis/candid_encode.html
diff --git a/docs/reference/canister_apis/canister_apis.html b/docs/reference/canister_apis/canister_apis.html
diff --git a/docs/reference/canister_apis/canister_balance.html b/docs/reference/canister_apis/canister_balance.html
diff --git a/docs/reference/canister_apis/canister_balance128.html b/docs/reference/canister_apis/canister_balance128.html
diff --git a/docs/reference/canister_apis/canister_id.html b/docs/reference/canister_apis/canister_id.html
diff --git a/docs/reference/canister_apis/canister_version.html b/docs/reference/canister_apis/canister_version.html
diff --git a/docs/reference/canister_apis/data_certificate.html b/docs/reference/canister_apis/data_certificate.html
diff --git a/docs/reference/canister_apis/instruction_counter.html b/docs/reference/canister_apis/instruction_counter.html
diff --git a/docs/reference/canister_apis/is_controller.html b/docs/reference/canister_apis/is_controller.html
diff --git a/docs/reference/canister_apis/performance_counter.html b/docs/reference/canister_apis/performance_counter.html
diff --git a/docs/reference/canister_apis/print.html b/docs/reference/canister_apis/print.html
diff --git a/docs/reference/canister_apis/set_certified_data.html b/docs/reference/canister_apis/set_certified_data.html
diff --git a/docs/reference/canister_apis/time.html b/docs/reference/canister_apis/time.html
diff --git a/docs/reference/canister_apis/trap.html b/docs/reference/canister_apis/trap.html
diff --git a/docs/reference/canister_methods/canister_methods.html b/docs/reference/canister_methods/canister_methods.html
diff --git a/docs/reference/canister_methods/heartbeat.html b/docs/reference/canister_methods/heartbeat.html
diff --git a/docs/reference/canister_methods/http_request.html b/docs/reference/canister_methods/http_request.html
diff --git a/docs/reference/canister_methods/http_request_update.html b/docs/reference/canister_methods/http_request_update.html
diff --git a/docs/reference/canister_methods/init.html b/docs/reference/canister_methods/init.html
diff --git a/docs/reference/canister_methods/inspect_message.html b/docs/reference/canister_methods/inspect_message.html
diff --git a/docs/reference/canister_methods/post_upgrade.html b/docs/reference/canister_methods/post_upgrade.html
diff --git a/docs/reference/canister_methods/pre_upgrade.html b/docs/reference/canister_methods/pre_upgrade.html
diff --git a/docs/reference/canister_methods/query.html b/docs/reference/canister_methods/query.html
diff --git a/docs/reference/canister_methods/update.html b/docs/reference/canister_methods/update.html
diff --git a/docs/reference/environment_variables.html b/docs/reference/environment_variables.html
diff --git a/docs/reference/management_canister/bitcoin_get_balance.html b/docs/reference/management_canister/bitcoin_get_balance.html
diff --git a/docs/reference/management_canister/bitcoin_get_current_fee_percentiles.html b/docs/reference/management_canister/bitcoin_get_current_fee_percentiles.html
diff --git a/docs/reference/management_canister/bitcoin_get_utxos.html b/docs/reference/management_canister/bitcoin_get_utxos.html
diff --git a/docs/reference/management_canister/bitcoin_send_transaction.html b/docs/reference/management_canister/bitcoin_send_transaction.html
diff --git a/docs/reference/management_canister/canister_status.html b/docs/reference/management_canister/canister_status.html
diff --git a/docs/reference/management_canister/create_canister.html b/docs/reference/management_canister/create_canister.html
diff --git a/docs/reference/management_canister/delete_canister.html b/docs/reference/management_canister/delete_canister.html
diff --git a/docs/reference/management_canister/deposit_cycles.html b/docs/reference/management_canister/deposit_cycles.html
diff --git a/docs/reference/management_canister/ecdsa_public_key.html b/docs/reference/management_canister/ecdsa_public_key.html
diff --git a/docs/reference/management_canister/http_request.html b/docs/reference/management_canister/http_request.html
diff --git a/docs/reference/management_canister/install_code.html b/docs/reference/management_canister/install_code.html
diff --git a/docs/reference/management_canister/management_canister.html b/docs/reference/management_canister/management_canister.html
diff --git a/docs/reference/management_canister/provisional_create_canister_with_cycles.html b/docs/reference/management_canister/provisional_create_canister_with_cycles.html
diff --git a/docs/reference/management_canister/provisional_top_up_canister.html b/docs/reference/management_canister/provisional_top_up_canister.html
diff --git a/docs/reference/management_canister/raw_rand.html b/docs/reference/management_canister/raw_rand.html
diff --git a/docs/reference/management_canister/sign_with_ecdsa.html b/docs/reference/management_canister/sign_with_ecdsa.html
diff --git a/docs/reference/management_canister/start_canister.html b/docs/reference/management_canister/start_canister.html
diff --git a/docs/reference/management_canister/stop_canister.html b/docs/reference/management_canister/stop_canister.html
diff --git a/docs/reference/management_canister/uninstall_code.html b/docs/reference/management_canister/uninstall_code.html
diff --git a/docs/reference/management_canister/update_settings.html b/docs/reference/management_canister/update_settings.html
diff --git a/docs/reference/plugins.html b/docs/reference/plugins.html
diff --git a/docs/reference/reference.html b/docs/reference/reference.html
diff --git a/docs/reference/stable_memory/stable64_grow.html b/docs/reference/stable_memory/stable64_grow.html
diff --git a/docs/reference/stable_memory/stable64_read.html b/docs/reference/stable_memory/stable64_read.html
diff --git a/docs/reference/stable_memory/stable64_size.html b/docs/reference/stable_memory/stable64_size.html
diff --git a/docs/reference/stable_memory/stable64_write.html b/docs/reference/stable_memory/stable64_write.html
diff --git a/docs/reference/stable_memory/stable_bytes.html b/docs/reference/stable_memory/stable_bytes.html
diff --git a/docs/reference/stable_memory/stable_grow.html b/docs/reference/stable_memory/stable_grow.html
diff --git a/docs/reference/stable_memory/stable_memory.html b/docs/reference/stable_memory/stable_memory.html
diff --git a/docs/reference/stable_memory/stable_read.html b/docs/reference/stable_memory/stable_read.html
diff --git a/docs/reference/stable_memory/stable_size.html b/docs/reference/stable_memory/stable_size.html
diff --git a/docs/reference/stable_memory/stable_structures.html b/docs/reference/stable_memory/stable_structures.html
diff --git a/docs/reference/stable_memory/stable_write.html b/docs/reference/stable_memory/stable_write.html
diff --git a/docs/reference/timers/clear_timer.html b/docs/reference/timers/clear_timer.html
diff --git a/docs/reference/timers/set_timer.html b/docs/reference/timers/set_timer.html
diff --git a/docs/reference/timers/set_timer_interval.html b/docs/reference/timers/set_timer_interval.html
diff --git a/docs/reference/timers/timers.html b/docs/reference/timers/timers.html
diff --git a/docs/reference/wasm_binary_optimization.html b/docs/reference/wasm_binary_optimization.html
diff --git a/docs/reference_http/autoreload.html b/docs/reference_http/autoreload.html
diff --git a/docs/reference_http/environment_variables.html b/docs/reference_http/environment_variables.html
diff --git a/docs/reference_http/native_compilation.html b/docs/reference_http/native_compilation.html
diff --git a/docs/reference_http/reference.html b/docs/reference_http/reference.html
diff --git a/docs/rest_based_examples.html b/docs/rest_based_examples.html
diff --git a/docs/searchindex.js b/docs/searchindex.js
diff --git a/docs/searchindex.json b/docs/searchindex.json
diff --git a/docs/server.html b/docs/server.html
diff --git a/docs/servers.html b/docs/servers.html
diff --git a/docs/stable_structures.html b/docs/stable_structures.html
diff --git a/docs/the_azle_book.html b/docs/the_azle_book.html
diff --git a/docs/timers.html b/docs/timers.html
diff --git a/docs/update_methods.html b/docs/update_methods.html
diff --git a/examples/composite_queries/test/tests.ts b/examples/composite_queries/test/tests.ts
@@ -55,7 +55,7 @@ export function get_tests(canister1: ActorSubclass<_SERVICE>): Test[] {
                         Ok: error
                             .toString()
                             .includes(
-                                `Rejection code 3, Canister ${getCanisterId(
+                                `Rejection code 5, Canister ${getCanisterId(
                                     'canister2'
                                 )} has no query method`
                             )

diff --git a/examples/hello_world/README.md b/examples/hello_world/README.md
@@ -51,7 +51,7 @@ node --version
 Install the dfx command line tools for managing ICP applications:
 
 ```bash
-DFX_VERSION=0.18.0 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
+DFX_VERSION=0.19.0 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
 ```
 
 Check that the installation went smoothly by looking for clean output from the following command:

diff --git a/examples/inspect_message/test/tests.ts b/examples/inspect_message/test/tests.ts
@@ -12,6 +12,7 @@ export function getTests(
             test: async () => {
                 try {
                     const result = await inspectMessageCanister.accessible();
+
                     return {
                         Ok: result === true
                     };
@@ -28,14 +29,13 @@ export function getTests(
             test: async () => {
                 try {
                     await inspectMessageCanister.inaccessible();
+
                     return {
                         Ok: false
                     };
-                } catch (error) {
+                } catch (error: any) {
                     return {
-                        Ok: ((error as any).message as string).includes(
-                            'IC0516'
-                        )
+                        Ok: error.message.includes('IC0406')
                     };
                 }
             }
@@ -49,11 +49,9 @@ export function getTests(
                     return {
                         Ok: false
                     };
-                } catch (error) {
+                } catch (error: any) {
                     return {
-                        Ok: ((error as any).message as string).includes(
-                            'IC0503'
-                        )
+                        Ok: error.message.includes('IC0503')
                     };
                 }
             }

diff --git a/the_azle_book/book/404.html b/the_azle_book/book/404.html
diff --git a/the_azle_book/book/azle.html b/the_azle_book/book/azle.html
diff --git a/the_azle_book/book/candid.html b/the_azle_book/book/candid.html
diff --git a/the_azle_book/book/canisters_overview.html b/the_azle_book/book/canisters_overview.html
diff --git a/the_azle_book/book/cross_canister.html b/the_azle_book/book/cross_canister.html
diff --git a/the_azle_book/book/cycles.html b/the_azle_book/book/cycles.html
diff --git a/the_azle_book/book/deployment.html b/the_azle_book/book/deployment.html
diff --git a/the_azle_book/book/examples.html b/the_azle_book/book/examples.html
diff --git a/the_azle_book/book/http.html b/the_azle_book/book/http.html
diff --git a/the_azle_book/book/index.html b/the_azle_book/book/index.html
diff --git a/the_azle_book/book/installation.html b/the_azle_book/book/installation.html
diff --git a/the_azle_book/book/internet_computer_overview.html b/the_azle_book/book/internet_computer_overview.html
diff --git a/the_azle_book/book/print.html b/the_azle_book/book/print.html
diff --git a/the_azle_book/book/searchindex.js b/the_azle_book/book/searchindex.js
diff --git a/the_azle_book/book/searchindex.json b/the_azle_book/book/searchindex.json
diff --git a/the_azle_book/book/timers.html b/the_azle_book/book/timers.html
diff --git a/the_azle_book/src/SUMMARY.md b/the_azle_book/src/SUMMARY.md
@@ -4,20 +4,23 @@
 -   [Get Started](./get_started.md)
 -   [Examples](./rest_based_examples.md)
 -   [Deployment](./deployment.md)
--   [Server](./server.md)
--   [Assets]()
--   [Debugging]()
--   [Limitations]()
--   [Authentication]()
+-   [Project Structure](./project_structure.md)
+-   [Servers](./servers.md)
+-   [Assets](./assets.md)
+-   [Authentication](./authentication.md)
 -   [Databases]()
 -   [fetch]()
 -   [npm]()
 -   [Cycles]()
 -   [Tokens]()
 -   [Bitcoin]()
 -   [Ethereum]()
+-   [Debugging](./debugging.md)
+-   [Limitations](./limitations.md)
 -   [Reference](./reference_http/reference.md)
     -   [Autoreload](./reference_http/autoreload.md)
+    -   [Environment Variables](./reference_http/environment_variables.md)
+    -   [Native Compilation](./reference_http/native_compilation.md)
 -   [Old Candid-based Documentation](./candid_based_documentation.md)
     -   [Azle (Beta)](./azle.md)
     -   [Internet Computer Overview](./internet_computer_overview.md)

diff --git a/the_azle_book/src/assets.md b/the_azle_book/src/assets.md
@@ -1,6 +1,8 @@
-# Assets
+# Assets TL;DR
 
-You can specify static assets (essentially files and folders) to be automatically included in your canister during deploy. You can specify assets using the `assets` property of your `dfx.json` file:
+You can automatically copy static assets (essentially files and folders) into your canister's filesystem during deploy by using the `assets`, `assets_large` and `build_assets` properties of the canister object in your project's `dfx.json` file.
+
+Here's an example that copies the `src/frontend/dist` directory on the deploying machine into the `dist` directory of the canister, using the `assets` and `build_assets` properties:
 
 ```json
 {
@@ -30,51 +32,22 @@ You can specify static assets (essentially files and folders) to be automaticall
 }
 ```
 
-Let's focus on the `assets` property:
-
-```json
-"assets": [["src/frontend/dist", "dist"]],
-```
+The `assets` property is an array of tuples, where the first element of the tuple is the source directory on the deploying machine, and the second element of the tuple is the destination directory in the canister. Use `assets` for total assets under ~90 MiB in size.
 
-We are instructing Azle to include the `src/frontend/dist` directory at the `dist` directory of the Azle canister.
+The `build_assets` property allows you to specify custom terminal commands that will run before Azle copies the assets into the canister. You can use `build_assets` to build your frontend code for example. In this case we are running `npm run build`, which refers to an npm script that we have specified in our `package.json` file.
 
-Azle canisters have their own file system separate from their host (i.e. your computer). You must load files into the Azle file system somehow. Using the `assets` property of `dfx.json` is one of those ways. You can also manually upload files yourself by creating endpoints and using `fs` to write to the filesystem. To do this you will have to split all files into chunks of 2 MiB or less to upload them. We are working on a way to allow automatic uploading of files.
+There is also an `assets_large` property that works similarly to the `assets` property, but allows for total assets up to ~2 GiB in size. We are working on increasing this limit further.
 
-There is a ~90 MiB limit for the `assets` property. The hard limit for a single canister will be 400 GiB currently. We are working on a way to automatically upload files for you.
+Once you have loaded assets into your canister, they are accessible from that canister's filesystem. Here's an example of using the Express static middleware to serve a frontend from the canister's filesystem:
 
 ```typescript
-import { Server } from 'azle';
-import express, { Request } from 'express';
-
-let db = {
-    hello: ''
-};
-
-export default Server(() => {
-    const app = express();
-
-    app.use(express.json());
-
-    app.get('/db', (req, res) => {
-        res.json(db);
-    });
+import express from 'express';
 
-    app.post('/db/update', (req: Request<any, any, typeof db>, res) => {
-        db = req.body;
+const app = express();
 
-        res.json(db);
-    });
-
-    app.use(express.static('/dist'));
-
-    return app.listen();
-});
-```
-
-```typescript
 app.use(express.static('/dist'));
-```
 
-TODO show an example of chunk uploading? Maybe we should just implement a simple chunk uploader so that they could at least do it?
+app.listen();
+```
 
-TODO also describe the build_assets property
+Assuming the `/dist` directory in the canister has an appropriate `index.html` file, this canister would serve a frontend at its URL when loaded in a web browser.
diff --git a/the_azle_book/src/authentication.md b/the_azle_book/src/authentication.md
@@ -0,0 +1,154 @@
+# Authentication TL;DR
+
+Azle canisters can import `ic` from `azle` and use `ic.caller()` to get the [principal (public-key linked identifier)](https://internetcomputer.org/docs/current/references/ic-interface-spec#principal) of the initiator of an HTTP request. HTTP requests are anonymous (principal `2vxsx-fae`) by default, but authentication with web browsers (and maybe Node.js) can be done using a JWT-like API from `azle/http_client`.
+
+First you import `toJwt` from `azle/http_client`:
+
+```typescript
+import { toJwt } from 'azle/http_client';
+```
+
+Then you use `fetch` and construct an `Authorization` header using an [@dfinity/agent](https://www.npmjs.com/package/@dfinity/agent) `Identity`:
+
+```typescript
+const response = await fetch(
+    `http://bkyz2-fmaaa-aaaaa-qaaaq-cai.localhost:8000/whoami`,
+    {
+        method: 'GET',
+        headers: [['Authorization', toJwt(this.identity)]]
+    }
+);
+```
+
+Here's an example of the frontend of a simple web application using `azle/http_client` and [Internet Identity](https://internetcomputer.org/internet-identity):
+
+```typescript
+import { Identity } from '@dfinity/agent';
+import { AuthClient } from '@dfinity/auth-client';
+import { toJwt } from 'azle/http_client';
+import { html, LitElement } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+@customElement('azle-app')
+export class AzleApp extends LitElement {
+    @property()
+    identity: Identity | null = null;
+
+    @property()
+    whoami: string = '';
+
+    connectedCallback() {
+        super.connectedCallback();
+        this.authenticate();
+    }
+
+    async authenticate() {
+        const authClient = await AuthClient.create();
+        const isAuthenticated = await authClient.isAuthenticated();
+
+        if (isAuthenticated === true) {
+            this.handleIsAuthenticated(authClient);
+        } else {
+            await this.handleIsNotAuthenticated(authClient);
+        }
+    }
+
+    handleIsAuthenticated(authClient: AuthClient) {
+        this.identity = authClient.getIdentity();
+    }
+
+    async handleIsNotAuthenticated(authClient: AuthClient) {
+        await new Promise((resolve, reject) => {
+            authClient.login({
+                identityProvider: import.meta.env.VITE_IDENTITY_PROVIDER,
+                onSuccess: resolve as () => void,
+                onError: reject,
+                windowOpenerFeatures: `width=500,height=500`
+            });
+        });
+
+        this.identity = authClient.getIdentity();
+    }
+
+    async whoamiUnauthenticated() {
+        const response = await fetch(
+            `${import.meta.env.VITE_CANISTER_ORIGIN}/whoami`
+        );
+        const responseText = await response.text();
+
+        this.whoami = responseText;
+    }
+
+    async whoamiAuthenticated() {
+        const response = await fetch(
+            `${import.meta.env.VITE_CANISTER_ORIGIN}/whoami`,
+            {
+                method: 'GET',
+                headers: [['Authorization', toJwt(this.identity)]]
+            }
+        );
+        const responseText = await response.text();
+
+        this.whoami = responseText;
+    }
+
+    render() {
+        return html`
+            <h1>Internet Identity</h1>
+
+            <h2>
+                Whoami principal:
+                <span id="whoamiPrincipal">${this.whoami}</span>
+            </h2>
+
+            <button
+                id="whoamiUnauthenticated"
+                @click=${this.whoamiUnauthenticated}
+            >
+                Whoami Unauthenticated
+            </button>
+            <button
+                id="whoamiAuthenticated"
+                @click=${this.whoamiAuthenticated}
+                .disabled=${this.identity === null}
+            >
+                Whoami Authenticated
+            </button>
+        `;
+    }
+}
+```
+
+Here's an example of the backend of that same simple web application:
+
+```typescript
+import { ic } from 'azle';
+import express from 'express';
+
+const app = express();
+
+app.get('/whoami', (req, res) => {
+    res.send(ic.caller().toString());
+});
+
+app.use(express.static('/dist'));
+
+app.listen();
+```
+
+# Authentication
+
+Examples:
+
+-   [fetch_ic](https://github.com/demergent-labs/azle/tree/main/examples/fetch_ic)
+-   [internet_identity](https://github.com/demergent-labs/azle/tree/main/examples/internet_identity)
+
+## Under-the-hood
+
+Authentication of ICP calls is done through signatures on messages. [@dfinity/agent](https://www.npmjs.com/package/@dfinity/agent) provides very nice abstractions for creating all of the required signatures in the correct formats when calling into canisters on ICP. Unfortunately this requires you to abandon traditional HTTP requests, as you must use the agent's APIs.
+
+Azle attempts to enable you to perform traditional HTTP requests with traditional libraries. Currently Azle focuses on `fetch`. When importing `toJwt`, `azle/http_client` will overwrite the global `fetch` function and will intercept `fetch` requests that have `Authorization` headers with an `Identity` as a value.
+
+Once intercepted, these requests are turned into `@dfinity/agent` requests that call [the http_request and http_request_update canister methods](https://internetcomputer.org/docs/current/references/http-gateway-protocol-spec) directly, thus performing all of the required client-side authentication work.
+
+We are working to push for ICP to more natively understand JWTs for authentication, without the need to intercept `fetch` requests and convert them into agent requests.