From c89946270d551dd85aaa429dfc0019265b74c2ae Mon Sep 17 00:00:00 2001 From: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> Date: Mon, 27 May 2024 10:20:35 -0500 Subject: [PATCH] Add docs pages for Mops packages (#4554) * add MOPS docs * Update utilities.md --- doc/md/base/_category_.yml | 2 +- doc/md/migration-guides/_category_.yml | 2 +- doc/md/motoko-packages/_category.yml | 4 ++ doc/md/motoko-packages/cryptography.md | 23 +++++++++ doc/md/motoko-packages/data-structures.md | 47 +++++++++++++++++ doc/md/motoko-packages/databases.md | 21 ++++++++ doc/md/motoko-packages/encoding.md | 25 +++++++++ doc/md/motoko-packages/http.md | 35 +++++++++++++ doc/md/motoko-packages/icrc.md | 41 +++++++++++++++ doc/md/motoko-packages/types-interfaces.md | 39 ++++++++++++++ doc/md/motoko-packages/utilities.md | 59 ++++++++++++++++++++++ doc/md/reference/_category_.yml | 2 +- doc/md/stable-memory/stable-regions.md | 8 +++ doc/md/stable-memory/stablememory.md | 6 +++ doc/md/writing-motoko/async-data.md | 10 +++- 15 files changed, 320 insertions(+), 4 deletions(-) create mode 100644 doc/md/motoko-packages/_category.yml create mode 100644 doc/md/motoko-packages/cryptography.md create mode 100644 doc/md/motoko-packages/data-structures.md create mode 100644 doc/md/motoko-packages/databases.md create mode 100644 doc/md/motoko-packages/encoding.md create mode 100644 doc/md/motoko-packages/http.md create mode 100644 doc/md/motoko-packages/icrc.md create mode 100644 doc/md/motoko-packages/types-interfaces.md create mode 100644 doc/md/motoko-packages/utilities.md diff --git a/doc/md/base/_category_.yml b/doc/md/base/_category_.yml index df1fc1e6a47..d67107b1055 100644 --- a/doc/md/base/_category_.yml +++ b/doc/md/base/_category_.yml @@ -1,4 +1,4 @@ -position: 8 +position: 9 label: 'Motoko base library' collapsible: true # make the category collapsible collapsed: true diff --git a/doc/md/migration-guides/_category_.yml b/doc/md/migration-guides/_category_.yml index 458db3141b0..fa3a13f790b 100644 --- a/doc/md/migration-guides/_category_.yml +++ b/doc/md/migration-guides/_category_.yml @@ -1,4 +1,4 @@ -position: 6 +position: 7 label: 'Migration guides' collapsible: true # make the category collapsible collapsed: true diff --git a/doc/md/motoko-packages/_category.yml b/doc/md/motoko-packages/_category.yml new file mode 100644 index 00000000000..ff666546580 --- /dev/null +++ b/doc/md/motoko-packages/_category.yml @@ -0,0 +1,4 @@ +position: 6 +label: 'Motoko packages' +collapsible: true # make the category collapsible +collapsed: true \ No newline at end of file diff --git a/doc/md/motoko-packages/cryptography.md b/doc/md/motoko-packages/cryptography.md new file mode 100644 index 00000000000..2fa381ea8ef --- /dev/null +++ b/doc/md/motoko-packages/cryptography.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 1 +--- + +# Cryptography + +## Mops packages for cryptography + +[Mops](https://mops.one/) is an on-chain package manager for Motoko. Here are some Mops packages for cryptography functions: + +- [`ic-certification`](https://mops.one/ic-certification): Canister signatures and certifications. + +- [`evm-proof-verifier`](https://mops.one/evm-proof-verifier): EVM proof verification. + +- [`evm-txs`](https://mops.one/evm-txs): EVM transaction creating, encoding, and decoding for Motoko implementations. + +- [`libsecp256k1`](https://mops.one/libsecp256k1): A Motoko implementation of libsecp256k1. + +- [`merkle-patricia-trie`](https://mops.one/merkle-patricia-trie): A Merkle Patricia Trie implementation following the Ethereum specification. + +- [`sha2`](https://mops.one/sha2): An optimized implementation of all SHA2 functions. + +- [`sha3`](https://mops.one/sha3): A Motoko SHA3/Keccak library. \ No newline at end of file diff --git a/doc/md/motoko-packages/data-structures.md b/doc/md/motoko-packages/data-structures.md new file mode 100644 index 00000000000..9fdb6daa5c6 --- /dev/null +++ b/doc/md/motoko-packages/data-structures.md @@ -0,0 +1,47 @@ +--- +sidebar_position: 2 +--- + +# Data structures + +## Mops packages for data structures + +[Mops](https://mops.one/) is an on-chain package manager for Motoko. Here are some Mops packages for data structure implementations: + +- [`augmented-btrees`](https://mops.one/augmented-btrees): An implementation of BTree variants, most notable the B+Tree. + +- [`buffer-deque`](https://mops.one/buffer-deque): A Buffer with Deque functionality of a Deque for efficient insertion and deletion at both ends. + +- [`bitbuffer`](https://mops.one/bitbuffer): Bit level and byte level manipulation. + +- [`circular-buffer`](https://mops.one/circular-buffer): Circular buffer implementation. + +- [`enumeration`](https://mops.one/enumeration): Add-only key sets with numbering and two-way lookup. + +- [`linked-list`](https://mops.one/linked-list): Doubly linked lists, featuring functions for node-level access. + +- [`map`](https://mops.one/map): Stable hash maps. + +- [`memory-buffer`](https://mops.one/memory-buffer): Persistent buffer implementations. + +- [`memory-hashlist`](https://mops.one/memory-hashlist): Storing and accessing blobs into memory associated with blob-key. + +- [`memory-hashtable`](https://mops.one/memory-hashtable): Storing, updating, deleting, and retrieving a single blob-value per key. + +- [`merkle-patricia-trie`](https://mops.one/merkle-patricia-trie): A Merkle Patricia Trie implementation following the Ethereum specification + +- [`splay`](https://mops.one/splay): A library for splay trees. + +- [`stable-buffer`](https://mops.one/stable-buffer): Buffers implemented in stable regions. + +- [`stable-enum`](https://mops.one/stable-enum): Enumerations implemented in stable regions. + +- [`stableheapbtreemap`](https://mops.one/stableheapbtreemap): BTreeMaps that can persist across upgrades via a stable variable in heap memory. + +- [`stable-rbtree`](https://mops.one/stable-rbtree): Stable RBtree. + +- [`swb`](https://mops.one/swb): Sliding window buffers featuring random access functionalities. + +- [`swbstable`](https://mops.one/swbstable): Stable sliding window buffer with random access. + +- [`vector`](https://mops.one/vector): Memory-efficient resizable array. Can be used as a replacement for `Buffer`. diff --git a/doc/md/motoko-packages/databases.md b/doc/md/motoko-packages/databases.md new file mode 100644 index 00000000000..cbdb3c5b92e --- /dev/null +++ b/doc/md/motoko-packages/databases.md @@ -0,0 +1,21 @@ +--- +sidebar_position: 3 +--- + +# Databases + +## Mops packages for databases + +[Mops](https://mops.one/) is an on-chain package manager for Motoko. Here are some Mops packages for database implementations: + +- [`candb`](https://mops.one/candb): A flexible, performant, and scalable non-relational, multi-canister data store built for ICP. + +- [`candb-multi`](https://mops.one/candb-multi): An add on to CanDB that allows you to work with multiple partition canisters at once. + +- [`new-candb`](https://mops.one/new-candb): A new form of CanDB that features an autoscaling option. + +- [`nacdb`](https://mops.one/nacdb): Multi-canister databases with seamless enumeration. + +- [`nacdb-reorder`](https://mops.one/nacdb-reorder): Re-orderable lists in NacDB database. + +- [`rxmodb`](https://mops.one/rxmodb): Motoko databases using `Vector` for main storage and `BTree` for indexes. diff --git a/doc/md/motoko-packages/encoding.md b/doc/md/motoko-packages/encoding.md new file mode 100644 index 00000000000..5aafb72bccd --- /dev/null +++ b/doc/md/motoko-packages/encoding.md @@ -0,0 +1,25 @@ +--- +sidebar_position: 4 +--- + +# Encoding + +## Mops packages for encoding + +[Mops](https://mops.one/) is an on-chain package manager for Motoko. Here are some Mops packages for encoding: + +- [`candid`](https://mops.one/candid): Encoding and decode Candid bytes. + +- [`candy`](https://mops.one/candy): Used for type conversions and creating workable collections. + +- [`candy-utils`](https://mops.one/candy-utils): Candy path and schema functionality built for the candy library. + +- [`cbor`](https://mops.one/cbor): Encoding and decode CBOR bytes. + +- [`deflate`](https://mops.one/deflate): Deflate compression and decompression algorithms with support for .gzip files. + +- [`rep-indy-hash`](https://mops.one/rep-indy-hash): Representational independent hashes. + +- [`serde`](https://mops.one/serde): Serialization and deserialization. + +- [`xml`](https://mops.one/xml): Encode and decode XML. \ No newline at end of file diff --git a/doc/md/motoko-packages/http.md b/doc/md/motoko-packages/http.md new file mode 100644 index 00000000000..2bfdd928886 --- /dev/null +++ b/doc/md/motoko-packages/http.md @@ -0,0 +1,35 @@ +--- +sidebar_position: 5 +--- + +# HTTP + +## Mops packages for HTTP + +[Mops](https://mops.one/) is an on-chain package manager for Motoko. Here are some Mops packages for HTTP and web functionalities: + +- [`assets`](https://mops.one/assets): A library for adding asset canister functionality for your canister. + +- [`certified-assets`](https://mops.one/certified-assets): Certify assets served via HTTP, ensuring the security of query calls on ICP. + +- [`certified-cache`](https://mops.one/certified-cache): A single interface that stores key-value pairs and certifies their hashes for to be used as certified variables or assets. + +- [`certified-http`](https://mops.one/certified-http): Similar to `certified-cache`, an interface that stores key-value pairs and certifies their hashes for use as certified assets or variables. + +- [`http-loopback`](https://mops.one/http-loopback): Call canisters using HTTP outcalls. + +- [`http-parser`](https://mops.one/http-parser): HTTP request parser for parsing URLs, search queries, headers and form data. + +- [`http-types`](https://mops.one/http-types): Canister HTTP interface types used in `http_request` and `http_request_update`. + +- [`ic-certification`](https://mops.one/ic-certification): Canister signatures and certification. + +- [`ic-websocket-cdk`](https://mops.one/ic-websocket-cdk): Websockets on ICP. + +- [`motoko-certified-assets`](https://mops.one/motoko-certified-assets): ICP certified assets. + +- [`promtracker`](https://mops.one/promtracker): Prometheus value tracking. + +- [`server`](https://mops.one/server): A server for Motoko similar to Express. + +- [`web-api`](https://mops.one/web-api) and [`web-io`](https://mops.one/web-io): Create HTTP requests and handle responses. \ No newline at end of file diff --git a/doc/md/motoko-packages/icrc.md b/doc/md/motoko-packages/icrc.md new file mode 100644 index 00000000000..ba20c268fe2 --- /dev/null +++ b/doc/md/motoko-packages/icrc.md @@ -0,0 +1,41 @@ +--- +sidebar_position: 5 +--- + +# ICRC + +## Mops packages for ICRC + +[Mops](https://mops.one/) is an on-chain package manager for Motoko. Here are some Mops packages for ICRC tokens: + +- [`account`](https://mops.one/account): Implementation of ICRC-1 and ICRC-7 accounts. + +- [`account-identifier`](https://mops.one/account-identifier): Account identifiers for the ICP ledger. + +- [`devefi-icrc-ledger`](https://mops.one/devefi-icrc-ledger): Local ICRC ledger syncing with remote ledger. + +- [`devefi-icrc-reader`](https://mops.one/devefi-icrc-reader): Read the ICRC ledger transaction log. + +- [`devefi-icrc-sender`](https://mops.one/devefi-icrc-sender): Send ledger transactions. + +- [`icrc1`](https://mops.one/icrc1) and [`icrc1-mo`](https://mops.one/icrc1-mo): ICRC-1 libraries. + +- [`icrc1-types`](https://mops.one/icrc1-types): ICRC-1 canister interface types. + +- [`icrc2-mo`](https://mops.one/icrc2-mo): ICRC-2 library. + +- [`icrc2-types`](https://mops.one/icrc2-types): ICRC-2 canister interface types, including support for ICRC-1. + +- [`icrc3-mo`](https://mops.one/icrc3-mo): ICRC-3 library. + +- [`icrc30-mo`](https://mops.one/icrc30-mo): ICRC-30 library. + +- [`icrc4-mo`](https://mops.one/icrc4-mo): ICRC-4 library. + +- [`icrc7-mo`](https://mops.one/icrc7-mo): ICRC-7 library. + +- [`icrc-fungible`](https://mops.one/icrc-fungible): Support for fungible tokens ICRC-1, ICRC-2, ICRC-3, ICRC-4, and ICRC-10. + +- [`icrc-nft-mo`](https://mops.one/icrc-nft-mo): An ICRC NFT library. + +- [`origyn-nft`](https://mops.one/origyn-nft): The reference implementation for the ORIGYN NFT. \ No newline at end of file diff --git a/doc/md/motoko-packages/types-interfaces.md b/doc/md/motoko-packages/types-interfaces.md new file mode 100644 index 00000000000..96dd4da1280 --- /dev/null +++ b/doc/md/motoko-packages/types-interfaces.md @@ -0,0 +1,39 @@ +--- +sidebar_position: 6 +--- + +# Types and interfaces + +## Mops packages for types and interfaces + +[Mops](https://mops.one/) is an on-chain package manager for Motoko. Here are some Mops packages for types and interfaces: + +- [`canistergeek`](https://mops.one/canistergeek): An open-source tool for tracking your project's cycles, memory status and logs. + +- [`ckbtc-types`](https://mops.one/ckbtc-types): Types and interfaces for interacting with ckBTC minter, ledger, index, and archive canisters. + +- [`devefi-icrc-ledger`](https://mops.one/devefi-icrc-ledger): Local ICRC ledger syncing with remote ledger. + +- [`devefi-icrc-reader`](https://mops.one/devefi-icrc-reader): Read the ICRC ledger transaction log. + +- [`devefi-icrc-sender`](https://mops.one/devefi-icrc-sender): Send ledger transactions. + +- [`http-types`](https://mops.one/http-types): Canister HTTP interface types used in `http_request` and `http_request_update`. + +- [`ic`](https://mops.one/ic): The ICP management canister interface. + +- [`icrc1-types`](https://mops.one/icrc1-types): ICRC-1 canister interface types. + +- [`icrc2-types`](https://mops.one/icrc2-types): ICRC-2 canister interface types, including support for ICRC-1. + +- [`ledger-types`](https://mops.one/ledger-types): ICP ledger canister types. + +- [`kyc`](https://mops.one/kyc): A client for interacting with ICRC-17 KYC servers. + +- [`promtracker`](https://mops.one/promtracker): Prometheus value tracking. + +- [`xrc-types`](https://mops.one/xrc-types): Exchange rate canister interface. + + + + diff --git a/doc/md/motoko-packages/utilities.md b/doc/md/motoko-packages/utilities.md new file mode 100644 index 00000000000..ed3c6bb3006 --- /dev/null +++ b/doc/md/motoko-packages/utilities.md @@ -0,0 +1,59 @@ +--- +sidebar_position: 7 +--- + +# Utilities + +## Mops packages for utility functions + +[Mops](https://mops.one/) is an on-chain package manager for Motoko. Here are some Mops packages for utility functions: + +- [`backup`](https://mops.one/backup): Library for backup restore. + +- [`bench`](https://mops.one/bench): Benchmarking library. + +- [`datetime`](https://mops.one/datetime): `DateTime` values and manipulation. + +- [`ekvm`](https://mops.one/ekvm): Infinitely scalable elastic key-value store. + +- [`fuzz`](https://mops.one/fuzz): Random data generation. + +- [`itertools`](https://mops.one/itertools): Utility functions and data types for creating efficient iterators. + +- [`lru-cache`](https://mops.one/lru-cache): Least recently used cache implementation. + +- [`json.mo`](https://mops.one/json.mo): A library for JSON formatting. + +- [`math`](https://mops.one/math): Linear algebra and mathematical calculus library. + +- [`make-rules`](https://mops.one/make-rules): Library for using GNU make. + +- [`motoko-crc`](https://mops.one/motoko-crc): Cyclic redundancy checks for Motoko. + +- [`neuro`](https://mops.one/neuro): Basic staking and neuron management. + +- [`passport-client`](https://mops.one/passport-client): Use Gitcoin Passport anti-Sybil information. + +- [`prng`](https://mops.one/prng): Statistical pseudo-random number generators. + +- [`random`](https://mops.one/random): Generate random data. + +- [`random-class`](https://mops.one/random-class): Random number generator objects. + +- [`tecdsa`](https://mops.one/tecdsa): Generate and manage tECDSA identities. + +- [`test`](https://mops.one/test): Motoko testing library. + +- [`time`](https://mops.one/time): Timestamps in nano, micro, millis, and seconds to string `date` or `DateType`. + +- [`time-consts`](https://mops.one/time-consts): Time constants for Motoko. + +- [`utilities`](https://mops.one/utilities): Class objects. + +- [`uuid`](https://mops.one/uuid): Universally unique identifier library. + +- [`xtended-numbers`](https://mops.one/xtended-numbers): Extended functionality for number types, such as byte encoding. + +- [`xtended-text`](https://mops.one/xtended-text): Text manipulation. + + diff --git a/doc/md/reference/_category_.yml b/doc/md/reference/_category_.yml index dd9560976ab..6a41a787db7 100644 --- a/doc/md/reference/_category_.yml +++ b/doc/md/reference/_category_.yml @@ -1,4 +1,4 @@ -position: 7 +position: 8 label: 'References' collapsible: true # make the category collapsible collapsed: true diff --git a/doc/md/stable-memory/stable-regions.md b/doc/md/stable-memory/stable-regions.md index 2b70c448003..a382e2310c5 100644 --- a/doc/md/stable-memory/stable-regions.md +++ b/doc/md/stable-memory/stable-regions.md @@ -95,3 +95,11 @@ The shared `add(blob)` function allocates enough stable memory to store the give The shared `get(index)` query reads anywhere from the log without traversing any unrelated memory. `StableLog` allocates and maintains its potentially large log data directly in stable memory and uses a small and fixed amount of storage for actual stable variables. Upgrading `StableLog` to a new implementation should not consume many cycles, regardless of the current size of the log. + +## Mops packages for stable regions + +- [`memory-region`](https://mops.one/memory-region): A library for abstraction over the `Region` type that supports reusing deallocated memory. + +- [`stable-enum`](https://mops.one/stable-enum): Enumerations implemented in stable regions. + +- [`stable-buffer`](https://mops.one/stable-buffer): Buffers implemented in stable regions. \ No newline at end of file diff --git a/doc/md/stable-memory/stablememory.md b/doc/md/stable-memory/stablememory.md index bad211b60b9..f7a7cb6d259 100644 --- a/doc/md/stable-memory/stablememory.md +++ b/doc/md/stable-memory/stablememory.md @@ -97,3 +97,9 @@ The shared `log(t)` function encodes its [`Text`](../base/Text.md) argument as a The shared `readLast(count)` query reads up to `count` messages from the log, traversing the log in reverse from `base`. Because `StableLog` allocates and maintains its (potentially large) log data directly in stable memory and uses just a small and fixed amount of storage for actual stable variables (here `base`), upgrading `StableLog` to a new implementation (perhaps to provide more functionality) should not consume too many cycles, regardless of the current size of the log. + +## Mops packages for stable memory + +- [`memory-buffer`](https://mops.one/memory-buffer): Persistent buffer implementation. + +- [`memory-hashtable`](https://mops.one/memory-hashtable): A library for storing, updating, deleting, and retrieving a single blob-value per key. diff --git a/doc/md/writing-motoko/async-data.md b/doc/md/writing-motoko/async-data.md index d938b7e7683..d9e6cd0efa6 100644 --- a/doc/md/writing-motoko/async-data.md +++ b/doc/md/writing-motoko/async-data.md @@ -6,7 +6,6 @@ sidebar_position: 5 ## Overview - On ICP, communication between canisters is asynchronous. Sending a message together with a callback from one canister to another schedules a request in the receiver. Completion of the request triggers the callback to the sender, allowing the sender to process the result. In Motoko, sending an ICP asynchronous message is abstracted as calling a shared function that returns an asynchronous result. @@ -86,3 +85,12 @@ For example, the implementation of `bump()` above is guaranteed to increment and ``` Each `await` suspends execution, allowing an interloper to change the state of the actor. By design, the explicit `await`s make the potential points of interference clear to the reader. + +## Mops packages for async data flow + +- [`maf`](https://mops.one/maf) and [`mal`](https://mops.one/mal): Async data deliveries. + +- [`rxmo`](https://mops.one/rxmo): A library for reactive programming using observables, making it easier to compose asynchronous or callback-based code. + +- [`star`](https://mops.one/star): Used for handling asynchronous behavior and traps using async* functions. +