From 99792fbe36a10f85e1ea63daf7f590020a2277b0 Mon Sep 17 00:00:00 2001 From: Jordan Last Date: Thu, 18 Apr 2024 13:06:35 -0500 Subject: [PATCH] add basic tokens, good bitcoin, and only examples for Ethereum documentation --- docs/404.html | 2 +- docs/assets.html | 2 +- docs/authentication.html | 2 +- docs/azle.html | 2 +- docs/bitcoin.html | 267 +++++++++++++++++ docs/candid.html | 2 +- docs/candid_based_documentation.html | 2 +- docs/canister_lifecycle.html | 2 +- docs/canisters_overview.html | 2 +- docs/caveats.html | 2 +- docs/cross_canister.html | 2 +- docs/cycles.html | 2 +- docs/debugging.html | 6 +- docs/deployment.html | 2 +- docs/deployment_candid_based.html | 2 +- docs/ethereum.html | 206 +++++++++++++ docs/examples.html | 2 +- docs/fetch.html | 2 +- docs/get_started.html | 2 +- docs/hello_world.html | 2 +- docs/http.html | 2 +- docs/index.html | 2 +- docs/installation.html | 2 +- docs/internet_computer_overview.html | 2 +- docs/limitations.html | 2 +- docs/management_canister.html | 2 +- docs/npm.html | 6 +- docs/print.html | 161 ++++++++++- docs/project_structure.html | 2 +- docs/query_methods.html | 2 +- docs/reference/bitcoin.html | 2 +- docs/reference/call_apis/accept_message.html | 2 +- docs/reference/call_apis/arg_data_raw.html | 2 +- .../call_apis/arg_data_raw_size.html | 2 +- docs/reference/call_apis/call.html | 2 +- docs/reference/call_apis/call_apis.html | 2 +- docs/reference/call_apis/call_raw.html | 2 +- docs/reference/call_apis/call_raw128.html | 2 +- .../call_apis/call_with_payment.html | 2 +- .../call_apis/call_with_payment128.html | 2 +- docs/reference/call_apis/caller.html | 2 +- docs/reference/call_apis/method_name.html | 2 +- .../call_apis/msg_cycles_accept.html | 2 +- .../call_apis/msg_cycles_accept128.html | 2 +- .../call_apis/msg_cycles_available.html | 2 +- .../call_apis/msg_cycles_available128.html | 2 +- .../call_apis/msg_cycles_refunded.html | 2 +- .../call_apis/msg_cycles_refunded128.html | 2 +- docs/reference/call_apis/notify.html | 2 +- docs/reference/call_apis/notify_raw.html | 2 +- .../call_apis/notify_with_payment_128.html | 2 +- docs/reference/call_apis/reject.html | 2 +- docs/reference/call_apis/reject_code.html | 2 +- docs/reference/call_apis/reject_message.html | 2 +- docs/reference/call_apis/reply.html | 2 +- docs/reference/call_apis/reply_raw.html | 2 +- docs/reference/candid/blob.html | 2 +- docs/reference/candid/bool.html | 2 +- docs/reference/candid/candid.html | 2 +- docs/reference/candid/empty.html | 2 +- docs/reference/candid/float32.html | 2 +- docs/reference/candid/float64.html | 2 +- docs/reference/candid/func.html | 2 +- docs/reference/candid/int.html | 2 +- docs/reference/candid/int16.html | 2 +- docs/reference/candid/int32.html | 2 +- docs/reference/candid/int64.html | 2 +- docs/reference/candid/int8.html | 2 +- docs/reference/candid/nat.html | 2 +- docs/reference/candid/nat16.html | 2 +- docs/reference/candid/nat32.html | 2 +- docs/reference/candid/nat64.html | 2 +- docs/reference/candid/nat8.html | 2 +- docs/reference/candid/null.html | 2 +- docs/reference/candid/opt.html | 2 +- docs/reference/candid/principal.html | 2 +- docs/reference/candid/record.html | 2 +- docs/reference/candid/reserved.html | 2 +- docs/reference/candid/service.html | 2 +- docs/reference/candid/text.html | 2 +- docs/reference/candid/variant.html | 2 +- docs/reference/candid/vec.html | 2 +- .../canister_apis/candid_decode.html | 2 +- .../canister_apis/candid_encode.html | 2 +- .../canister_apis/canister_apis.html | 2 +- .../canister_apis/canister_balance.html | 2 +- .../canister_apis/canister_balance128.html | 2 +- docs/reference/canister_apis/canister_id.html | 2 +- .../canister_apis/canister_version.html | 2 +- .../canister_apis/data_certificate.html | 2 +- .../canister_apis/instruction_counter.html | 2 +- .../canister_apis/is_controller.html | 2 +- .../canister_apis/performance_counter.html | 2 +- docs/reference/canister_apis/print.html | 2 +- .../canister_apis/set_certified_data.html | 2 +- docs/reference/canister_apis/time.html | 2 +- docs/reference/canister_apis/trap.html | 2 +- .../canister_methods/canister_methods.html | 2 +- .../reference/canister_methods/heartbeat.html | 2 +- .../canister_methods/http_request.html | 2 +- .../canister_methods/http_request_update.html | 2 +- docs/reference/canister_methods/init.html | 2 +- .../canister_methods/inspect_message.html | 2 +- .../canister_methods/post_upgrade.html | 2 +- .../canister_methods/pre_upgrade.html | 2 +- docs/reference/canister_methods/query.html | 2 +- docs/reference/canister_methods/update.html | 2 +- docs/reference/environment_variables.html | 2 +- .../bitcoin_get_balance.html | 2 +- .../bitcoin_get_current_fee_percentiles.html | 2 +- .../bitcoin_get_utxos.html | 2 +- .../bitcoin_send_transaction.html | 2 +- .../management_canister/canister_status.html | 2 +- .../management_canister/create_canister.html | 2 +- .../management_canister/delete_canister.html | 2 +- .../management_canister/deposit_cycles.html | 2 +- .../management_canister/ecdsa_public_key.html | 2 +- .../management_canister/http_request.html | 2 +- .../management_canister/install_code.html | 2 +- .../management_canister.html | 2 +- ...ovisional_create_canister_with_cycles.html | 2 +- .../provisional_top_up_canister.html | 2 +- .../management_canister/raw_rand.html | 2 +- .../management_canister/sign_with_ecdsa.html | 2 +- .../management_canister/start_canister.html | 2 +- .../management_canister/stop_canister.html | 2 +- .../management_canister/uninstall_code.html | 2 +- .../management_canister/update_settings.html | 2 +- docs/reference/plugins.html | 2 +- docs/reference/reference.html | 2 +- .../stable_memory/stable64_grow.html | 2 +- .../stable_memory/stable64_read.html | 2 +- .../stable_memory/stable64_size.html | 2 +- .../stable_memory/stable64_write.html | 2 +- .../reference/stable_memory/stable_bytes.html | 2 +- docs/reference/stable_memory/stable_grow.html | 2 +- .../stable_memory/stable_memory.html | 2 +- docs/reference/stable_memory/stable_read.html | 2 +- docs/reference/stable_memory/stable_size.html | 2 +- .../stable_memory/stable_structures.html | 2 +- .../reference/stable_memory/stable_write.html | 2 +- docs/reference/timers/clear_timer.html | 2 +- docs/reference/timers/set_timer.html | 2 +- docs/reference/timers/set_timer_interval.html | 2 +- docs/reference/timers/timers.html | 2 +- docs/reference/wasm_binary_optimization.html | 2 +- docs/reference_http/autoreload.html | 2 +- .../reference_http/environment_variables.html | 2 +- docs/reference_http/native_compilation.html | 2 +- docs/reference_http/reference.html | 2 +- docs/rest_based_examples.html | 2 +- docs/searchindex.js | 2 +- docs/searchindex.json | 2 +- docs/servers.html | 2 +- docs/stable_structures.html | 2 +- docs/the_azle_book.html | 2 +- docs/timers.html | 2 +- docs/tokens.html | 272 ++++++++++++++++++ docs/update_methods.html | 2 +- the_azle_book/book/404.html | 2 +- the_azle_book/book/azle.html | 2 +- the_azle_book/book/candid.html | 2 +- the_azle_book/book/canisters_overview.html | 2 +- the_azle_book/book/cross_canister.html | 2 +- the_azle_book/book/cycles.html | 2 +- the_azle_book/book/deployment.html | 2 +- the_azle_book/book/examples.html | 2 +- the_azle_book/book/http.html | 2 +- the_azle_book/book/index.html | 2 +- the_azle_book/book/installation.html | 2 +- .../book/internet_computer_overview.html | 2 +- the_azle_book/book/print.html | 161 ++++++++++- the_azle_book/book/searchindex.js | 2 +- the_azle_book/book/searchindex.json | 2 +- the_azle_book/book/timers.html | 2 +- the_azle_book/src/SUMMARY.md | 8 +- the_azle_book/src/bitcoin.md | 83 ++++++ the_azle_book/src/ethereum.md | 8 + the_azle_book/src/tokens.md | 78 +++++ 179 files changed, 1404 insertions(+), 188 deletions(-) create mode 100644 docs/bitcoin.html create mode 100644 docs/ethereum.html create mode 100644 docs/tokens.html create mode 100644 the_azle_book/src/bitcoin.md create mode 100644 the_azle_book/src/ethereum.md create mode 100644 the_azle_book/src/tokens.md diff --git a/docs/404.html b/docs/404.html index 23bc9cb761..c69dd6cc9a 100644 --- a/docs/404.html +++ b/docs/404.html @@ -84,7 +84,7 @@ diff --git a/docs/assets.html b/docs/assets.html index 0fa86a1e29..280f161e24 100644 --- a/docs/assets.html +++ b/docs/assets.html @@ -83,7 +83,7 @@ diff --git a/docs/authentication.html b/docs/authentication.html index f3adf27ed3..b44729a2b6 100644 --- a/docs/authentication.html +++ b/docs/authentication.html @@ -83,7 +83,7 @@ diff --git a/docs/azle.html b/docs/azle.html index c3b691e403..c91bd3a8b6 100644 --- a/docs/azle.html +++ b/docs/azle.html @@ -83,7 +83,7 @@ diff --git a/docs/bitcoin.html b/docs/bitcoin.html new file mode 100644 index 0000000000..8904cd7c31 --- /dev/null +++ b/docs/bitcoin.html @@ -0,0 +1,267 @@ + + + + + + Bitcoin - The Azle Book + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+

Bitcoin

+

Examples:

+ +

There are two main ways to interact with Bitcoin on ICP: through the management canister and through the ckBTC canister.

+

management canister

+

To sign Bitcoin transactions using threshold ECDSA and interact with the Bitcoin blockchain directly from ICP, make cross-canister calls to the following methods on the management canister: ecdsa_public_key, sign_with_ecdsa, bitcoin_get_balance, bitcoin_get_balance_query, bitcoin_get_utxos, bitcoin_get_utxos_query, bitcoin_send_transaction, bitcoin_get_current_fee_percentiles.

+

To construct your cross-canister calls to these methods, use canister id aaaaa-aa and the management canister's Candid type information to construct the arguments to send in the body of your fetch call.

+

Here's an example of doing a test cross-canister call to the bitcoin_get_balance method:

+
import { serialize } from 'azle';
+
+// ...
+
+const response = await fetch(`icp://aaaaa-aa/bitcoin_get_balance`, {
+    body: serialize({
+        args: [
+            {
+                'bc1q34aq5drpuwy3wgl9lhup9892qp6svr8ldzyy7c',
+                min_confirmations: [],
+                network: { regtest: null }
+            }
+        ],
+        cycles: 100_000_000n
+    })
+});
+const responseJson = await response.json();
+
+// ...
+
+

ckBTC

+

ckBTC is an ICRC canister that wraps underlying bitcoin controlled with threshold ECDSA.

+

ICRCs are a set of standards for ICP canisters that define the method signatures and corresponding types for those canisters.

+

You interact with the ckBTC canister by calling its methods. You can do this from the frontend with @dfinity/agent, or from an Azle canister through cross-canister calls.

+

Here's an example of doing a test cross-canister call to the ckBTC icrc1_balance_of method:

+
import { ic, serialize } from 'azle';
+
+// ...
+
+const response = await fetch(
+    `icp://mc6ru-gyaaa-aaaar-qaaaq-cai/icrc1_balance_of`,
+    {
+        body: serialize({
+            candidPath: `/candid/icrc.did`,
+            args: [
+                {
+                    owner: ic.id(),
+                    subaccount: [
+                        padPrincipalWithZeros(ic.caller().toUint8Array())
+                    ]
+                }
+            ]
+        })
+    }
+);
+const responseJson = await response.json();
+
+// ...
+
+function padPrincipalWithZeros(principalBlob: Uint8Array): Uint8Array {
+    let newUin8Array = new Uint8Array(32);
+    newUin8Array.set(principalBlob);
+    return newUin8Array;
+}
+
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + +
+ + diff --git a/docs/candid.html b/docs/candid.html index 33d49c8320..08ad0939ba 100644 --- a/docs/candid.html +++ b/docs/candid.html @@ -83,7 +83,7 @@ diff --git a/docs/candid_based_documentation.html b/docs/candid_based_documentation.html index 1f9a04d6e6..0801e3d7e3 100644 --- a/docs/candid_based_documentation.html +++ b/docs/candid_based_documentation.html @@ -83,7 +83,7 @@ diff --git a/docs/canister_lifecycle.html b/docs/canister_lifecycle.html index 5d2acdfa15..317f26f85a 100644 --- a/docs/canister_lifecycle.html +++ b/docs/canister_lifecycle.html @@ -83,7 +83,7 @@ diff --git a/docs/canisters_overview.html b/docs/canisters_overview.html index 845d460818..2f0676de6c 100644 --- a/docs/canisters_overview.html +++ b/docs/canisters_overview.html @@ -83,7 +83,7 @@ diff --git a/docs/caveats.html b/docs/caveats.html index 0b7356b875..51244b2baf 100644 --- a/docs/caveats.html +++ b/docs/caveats.html @@ -83,7 +83,7 @@ diff --git a/docs/cross_canister.html b/docs/cross_canister.html index d3402be902..149836ba46 100644 --- a/docs/cross_canister.html +++ b/docs/cross_canister.html @@ -83,7 +83,7 @@ diff --git a/docs/cycles.html b/docs/cycles.html index b8b5b6c87f..2b4d7684f3 100644 --- a/docs/cycles.html +++ b/docs/cycles.html @@ -83,7 +83,7 @@ diff --git a/docs/debugging.html b/docs/debugging.html index f18b972524..2d66e53b01 100644 --- a/docs/debugging.html +++ b/docs/debugging.html @@ -83,7 +83,7 @@ @@ -223,7 +223,7 @@

- @@ -237,7 +237,7 @@

- diff --git a/docs/deployment.html b/docs/deployment.html index 5f200442e0..0f944f4bbf 100644 --- a/docs/deployment.html +++ b/docs/deployment.html @@ -83,7 +83,7 @@ diff --git a/docs/deployment_candid_based.html b/docs/deployment_candid_based.html index e71c49a739..7843de3e88 100644 --- a/docs/deployment_candid_based.html +++ b/docs/deployment_candid_based.html @@ -83,7 +83,7 @@ diff --git a/docs/ethereum.html b/docs/ethereum.html new file mode 100644 index 0000000000..f929ab63af --- /dev/null +++ b/docs/ethereum.html @@ -0,0 +1,206 @@ + + + + + + Ethereum - The Azle Book + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+

Ethereum

+

Examples:

+ + +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + +
+ + diff --git a/docs/examples.html b/docs/examples.html index af0be3966d..e4797cea61 100644 --- a/docs/examples.html +++ b/docs/examples.html @@ -83,7 +83,7 @@ diff --git a/docs/fetch.html b/docs/fetch.html index 267df9033d..ba3fcf501d 100644 --- a/docs/fetch.html +++ b/docs/fetch.html @@ -83,7 +83,7 @@ diff --git a/docs/get_started.html b/docs/get_started.html index 44311592ed..7a3ba5008a 100644 --- a/docs/get_started.html +++ b/docs/get_started.html @@ -83,7 +83,7 @@ diff --git a/docs/hello_world.html b/docs/hello_world.html index 7d35b595ae..a687cb3873 100644 --- a/docs/hello_world.html +++ b/docs/hello_world.html @@ -83,7 +83,7 @@ diff --git a/docs/http.html b/docs/http.html index cc466d9a27..8ffc7fe5d5 100644 --- a/docs/http.html +++ b/docs/http.html @@ -83,7 +83,7 @@ diff --git a/docs/index.html b/docs/index.html index 7222e7ead3..465bc9a51b 100644 --- a/docs/index.html +++ b/docs/index.html @@ -83,7 +83,7 @@ diff --git a/docs/installation.html b/docs/installation.html index 87ef673c1f..6e60a4ce52 100644 --- a/docs/installation.html +++ b/docs/installation.html @@ -83,7 +83,7 @@ diff --git a/docs/internet_computer_overview.html b/docs/internet_computer_overview.html index 6826f0fffb..a9983e0217 100644 --- a/docs/internet_computer_overview.html +++ b/docs/internet_computer_overview.html @@ -83,7 +83,7 @@ diff --git a/docs/limitations.html b/docs/limitations.html index d4bf3f0be9..9c03124d09 100644 --- a/docs/limitations.html +++ b/docs/limitations.html @@ -83,7 +83,7 @@ diff --git a/docs/management_canister.html b/docs/management_canister.html index e0f84688c1..4b93301291 100644 --- a/docs/management_canister.html +++ b/docs/management_canister.html @@ -83,7 +83,7 @@ diff --git a/docs/npm.html b/docs/npm.html index 61e8cff2e2..257535f113 100644 --- a/docs/npm.html +++ b/docs/npm.html @@ -83,7 +83,7 @@ @@ -171,7 +171,7 @@

npm

- @@ -185,7 +185,7 @@

npm

- diff --git a/docs/print.html b/docs/print.html index 2e5a281ce9..80205fa2a6 100644 --- a/docs/print.html +++ b/docs/print.html @@ -84,7 +84,7 @@ @@ -905,6 +905,157 @@

npm

For example, any kind of networking outside of HTTP is unlikely to work (without modification), because ICP has very limited support for non-ICP networking.

Also any kind of heavy computation is unlikely to work (without modification), because ICP has very limited instruction limits per call.

We use wasmedge-quickjs as our implementation for much of the Node.js stdlib. To get a feel for which Node.js standard libraries Azle supports, see here and here.

+

Tokens TL;DR

+

Canisters can either:

+
    +
  1. Interact with tokens that already exist
    2. +
  2. Implement, extend, or proxy tokens
    3. +
+

Canisters can use cross-canister calls to interact with tokens implemented using ICRC or other standards. They can also interact with non-ICP tokens through threshold ECDSA.

+

Canisters can implement tokens from scratch, or extend or proxy implementations already written.

+

Demergent Labs does not keep any token implementations up-to-date. Here are some old implementations for inspiration and learning:

+ +

Tokens

+

Examples:

+ + +

Bitcoin

+

Examples:

+ +

There are two main ways to interact with Bitcoin on ICP: through the management canister and through the ckBTC canister.

+

management canister

+

To sign Bitcoin transactions using threshold ECDSA and interact with the Bitcoin blockchain directly from ICP, make cross-canister calls to the following methods on the management canister: ecdsa_public_key, sign_with_ecdsa, bitcoin_get_balance, bitcoin_get_balance_query, bitcoin_get_utxos, bitcoin_get_utxos_query, bitcoin_send_transaction, bitcoin_get_current_fee_percentiles.

+

To construct your cross-canister calls to these methods, use canister id aaaaa-aa and the management canister's Candid type information to construct the arguments to send in the body of your fetch call.

+

Here's an example of doing a test cross-canister call to the bitcoin_get_balance method:

+
import { serialize } from 'azle';
+
+// ...
+
+const response = await fetch(`icp://aaaaa-aa/bitcoin_get_balance`, {
+    body: serialize({
+        args: [
+            {
+                'bc1q34aq5drpuwy3wgl9lhup9892qp6svr8ldzyy7c',
+                min_confirmations: [],
+                network: { regtest: null }
+            }
+        ],
+        cycles: 100_000_000n
+    })
+});
+const responseJson = await response.json();
+
+// ...
+
+

ckBTC

+

ckBTC is an ICRC canister that wraps underlying bitcoin controlled with threshold ECDSA.

+

ICRCs are a set of standards for ICP canisters that define the method signatures and corresponding types for those canisters.

+

You interact with the ckBTC canister by calling its methods. You can do this from the frontend with @dfinity/agent, or from an Azle canister through cross-canister calls.

+

Here's an example of doing a test cross-canister call to the ckBTC icrc1_balance_of method:

+
import { ic, serialize } from 'azle';
+
+// ...
+
+const response = await fetch(
+    `icp://mc6ru-gyaaa-aaaar-qaaaq-cai/icrc1_balance_of`,
+    {
+        body: serialize({
+            candidPath: `/candid/icrc.did`,
+            args: [
+                {
+                    owner: ic.id(),
+                    subaccount: [
+                        padPrincipalWithZeros(ic.caller().toUint8Array())
+                    ]
+                }
+            ]
+        })
+    }
+);
+const responseJson = await response.json();
+
+// ...
+
+function padPrincipalWithZeros(principalBlob: Uint8Array): Uint8Array {
+    let newUin8Array = new Uint8Array(32);
+    newUin8Array.set(principalBlob);
+    return newUin8Array;
+}
+
+

Ethereum

+

Examples:

+

Debugging TL;DR

If your terminal logs ever say did not produce a response or response failed classification=Status code: 502 Bad Gateway, it most likely means that your canister has thrown an error and halted execution for that call. Use console.log and try/catch liberally to track down problems and reveal error information. If your error logs do not have useful messages, use try/catch with a console.log of the catch error argument to reveal the underlying error message.

Debugging

@@ -2717,7 +2868,7 @@

-

Management Canister

+

Management Canister

This chapter is a work in progress.

You can access the management canister like this:

import { blob, Canister, ic, update } from 'azle';
@@ -2899,7 +3050,7 @@ 
Timers
 
  • Wasm Binary Optimization
    • 
 
-
    Bitcoin
    
+
    Bitcoin
    
 
    The Internet Computer (IC) interacts with the Bitcoin blockchain through the use of tECDSA, the Bitcoin integration, and a ledger canister called ckBTC.
    
 
    tECDSA
    
 
    tECDSA on the IC allows canisters to request access to threshold ECDSA keypairs on the tECDSA subnet. This functionality is exposed through two management canister methods:
    
@@ -2925,7 +3076,7 @@ 
    Bitco
 
  • basic_bitcoin
    • 
 
  • bitcoin
    • 
 
-
    ckBTC
    
+
    ckBTC
    
 
    ckBTC is a ledger canister deployed to the IC. It follows the ICRC standard, and can be accessed easily from an Azle canister using azle/canisters/ICRC if you only need the ICRC methods. For access to the full ledger methods you will need to create your own Service for now.
    
 
    The following are examples using ckBTC:
    -

    Management Canister

    +

    Management Canister

    -

    Bitcoin

    +

    Bitcoin

    The Internet Computer (IC) interacts with the Bitcoin blockchain through the use of tECDSA, the Bitcoin integration, and a ledger canister called ckBTC.

    tECDSA

    tECDSA on the IC allows canisters to request access to threshold ECDSA keypairs on the tECDSA subnet. This functionality is exposed through two management canister methods:

    @@ -2925,7 +3076,7 @@

    Bitco
  • basic_bitcoin
  • bitcoin
    • -

    ckBTC

    +

    ckBTC

    ckBTC is a ledger canister deployed to the IC. It follows the ICRC standard, and can be accessed easily from an Azle canister using azle/canisters/ICRC if you only need the ICRC methods. For access to the full ledger methods you will need to create your own Service for now.

    The following are examples using ckBTC: