Merge pull request #1746 from demergent-labs/documentation_fetch

add fetch documentation
demergent-labs · Apr 18, 2024 · aaa16c4 · aaa16c4
2 parents 8cf55f7 + 0d296e6
commit aaa16c4
Show file tree

Hide file tree

Showing 174 changed files with 912 additions and 175 deletions.
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/fetch.html b/docs/fetch.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/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/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
@@ -8,8 +8,8 @@
 -   [Servers](./servers.md)
 -   [Assets](./assets.md)
 -   [Authentication](./authentication.md)
+-   [fetch](./fetch.md)
 -   [Databases]()
--   [fetch]()
 -   [npm]()
 -   [Cycles]()
 -   [Tokens]()

diff --git a/the_azle_book/src/authentication.md b/the_azle_book/src/authentication.md
@@ -140,6 +140,7 @@ app.listen();
 
 Examples:
 
+-   [ckbtc](https://github.com/demergent-labs/azle/tree/main/examples/ckbtc)
 -   [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)
 

diff --git a/the_azle_book/src/fetch.md b/the_azle_book/src/fetch.md
@@ -0,0 +1,145 @@
+# fetch TL;DR
+
+Azle canisters use a custom `fetch` implementation to perform cross-canister calls and to perform HTTPS outcalls.
+
+Here's an example of performing a cross-canister call:
+
+```typescript
+import { serialize } from 'azle';
+import express from 'express';
+
+const app = express();
+
+app.use(express.json());
+
+app.post('/cross-canister-call', async (req, res) => {
+    const to: string = req.body.to;
+    const amount: number = req.body.amount;
+
+    const response = await fetch(`icp://dfdal-2uaaa-aaaaa-qaama-cai/transfer`, {
+        body: serialize({
+            candidPath: '/token.did',
+            args: [to, amount]
+        })
+    });
+    const responseJson = await response.json();
+
+    res.json(responseJson);
+});
+
+app.listen();
+```
+
+Keep these important points in mind when performing a cross-canister call:
+
+-   Use the `icp://` protocol in the URL
+-   The `canister id` of the canister that you are calling immediately follows `icp://` in the URL
+-   The `canister method` that you are calling immediately follows the `canister id` in the URL
+-   The `candidPath` property of the `body` is the path to the Candid file defining the method signatures of the canister that you are calling. You must obtain this file and copy it into your canister. See the [Assets chapter](./assets.md) for info on copying files into your canister
+-   The `args` property of the `body` is an array of the arguments that will be passed to the `canister method` that you are calling
+
+Here's an example of performing an HTTPS outcall:
+
+```typescript
+import express from 'express';
+
+const app = express();
+
+app.use(express.json());
+
+app.post('/https-outcall', async (_req, res) => {
+    const response = await fetch(`https://httpbin.org/headers`, {
+        headers: {
+            'X-Azle-Request-Key-0': 'X-Azle-Request-Value-0',
+            'X-Azle-Request-Key-1': 'X-Azle-Request-Value-1',
+            'X-Azle-Request-Key-2': 'X-Azle-Request-Value-2'
+        }
+    });
+    const responseJson = await response.json();
+
+    res.json(responseJson);
+});
+
+app.listen();
+```
+
+# fetch
+
+Azle has custom `fetch` implementations for clients and canisters.
+
+The client `fetch` is used for authentication, and you can learn more about it in the [Authentication chapter](./authentication.md).
+
+Canister `fetch` is used to perform cross-canister calls and [HTTPS outcalls](https://internetcomputer.org/https-outcalls). There are three main types of calls made with canister `fetch`:
+
+1. [Cross-canister calls to a candid canister](#cross-canister-calls-to-a-candid-canister)
+2. [Cross-canister calls to an HTTP canister](#cross-canister-calls-to-an-http-canister)
+3. [HTTPS outcalls](#https-outcalls)
+
+## Cross-canister calls to a candid canister
+
+Examples:
+
+-   [async_await](https://github.com/demergent-labs/azle/tree/main/examples/async_await)
+-   [bitcoin](https://github.com/demergent-labs/azle/tree/main/examples/bitcoin)
+-   [canister](https://github.com/demergent-labs/azle/tree/main/examples/canister)
+-   [ckbtc](https://github.com/demergent-labs/azle/tree/main/examples/ckbtc)
+-   [composite_queries](https://github.com/demergent-labs/azle/tree/main/examples/composite_queries)
+-   [cross_canister_calls](https://github.com/demergent-labs/azle/tree/main/examples/cross_canister_calls)
+-   [cycles](https://github.com/demergent-labs/azle/tree/main/examples/cycles)
+-   [func_types](https://github.com/demergent-labs/azle/tree/main/examples/func_types)
+-   [heartbeat](https://github.com/demergent-labs/azle/tree/main/examples/heartbeat)
+-   [ic_evm_rpc](https://github.com/demergent-labs/azle/tree/main/examples/ic_evm_rpc)
+-   [icrc](https://github.com/demergent-labs/azle/tree/main/examples/icrc)
+-   [ledger_canister](https://github.com/demergent-labs/azle/tree/main/examples/ledger_canister)
+-   [management_canister](https://github.com/demergent-labs/azle/tree/main/examples/management_canister)
+-   [threshold_ecdsa](https://github.com/demergent-labs/azle/tree/main/examples/motoko_examples/threshold_ecdsa)
+-   [whoami](https://github.com/demergent-labs/azle/tree/main/examples/motoko_examples/whoami)
+-   [recursion](https://github.com/demergent-labs/azle/tree/main/examples/recursion)
+-   [rejections](https://github.com/demergent-labs/azle/tree/main/examples/rejections)
+-   [timers](https://github.com/demergent-labs/azle/tree/main/examples/timers)
+
+## Cross-canister calls to an HTTP canister
+
+We are working on better abstractions for these types of calls. For now you would just make a cross-canister call using `icp://` to the `http_request` and `http_request_update` methods of the canister that you are calling.
+
+## HTTPS outcalls
+
+Examples:
+
+-   [ethereum_json_rpc](https://github.com/demergent-labs/azle/tree/main/examples/ethereum_json_rpc)
+-   [http_outcall_fetch](https://github.com/demergent-labs/azle/tree/main/examples/http_outcall_fetch)
+-   [outgoing_http_requests](https://github.com/demergent-labs/azle/tree/main/examples/outgoing_http_requests)
+
+<!-- // TODO explain that you can generally only do these in POST unless the method is a query method
+// TODO we have to show the imports
+// TODO explain the POST, PUT, PATCH etc
+
+TODO explain the ic.setOutgoingHttpOptions
+
+TODO split up the examples for each type of fetch
+
+## Canister fetch cross-canister call to a candid canister
+
+Most canisters on ICP are not HTTP canisters. We are pushing to change this situation, but for now this is how things are. Most canisters will thus only expose Candid canister methods.
+
+So imagine a canister that exposes this Candid update method:
+
+```
+transfer: (text, text, nat64) -> (nat64);
+```
+
+```typescript
+const response = await fetch(`icp://dfdal-2uaaa-aaaaa-qaama-cai/transfer`, {
+    body: serialize({
+        candidPath: '/src/canister2/index.did',
+        args: [from, to, amount]
+    })
+});
+const responseJson = await response.json();
+
+return responseJson;
+```
+
+## Canister fetch cross-canister call to an HTTP canister
+
+## Canister fetch HTTPS outcalls -->