Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs pages for Mops packages #4554

Merged
merged 3 commits into from
May 27, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/md/base/_category_.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
position: 8
position: 9
label: 'Motoko base library'
collapsible: true # make the category collapsible
collapsed: true
Expand Down
2 changes: 1 addition & 1 deletion doc/md/migration-guides/_category_.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
position: 6
position: 7
label: 'Migration guides'
collapsible: true # make the category collapsible
collapsed: true
4 changes: 4 additions & 0 deletions doc/md/motoko-packages/_category.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
position: 6
label: 'Motoko packages'
collapsible: true # make the category collapsible
collapsed: true
23 changes: 23 additions & 0 deletions doc/md/motoko-packages/cryptography.md
Original file line number Diff line number Diff line change
@@ -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.
47 changes: 47 additions & 0 deletions doc/md/motoko-packages/data-structures.md
Original file line number Diff line number Diff line change
@@ -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`.
21 changes: 21 additions & 0 deletions doc/md/motoko-packages/databases.md
Original file line number Diff line number Diff line change
@@ -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.
25 changes: 25 additions & 0 deletions doc/md/motoko-packages/encoding.md
Original file line number Diff line number Diff line change
@@ -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.
35 changes: 35 additions & 0 deletions doc/md/motoko-packages/http.md
Original file line number Diff line number Diff line change
@@ -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.
41 changes: 41 additions & 0 deletions doc/md/motoko-packages/icrc.md
Original file line number Diff line number Diff line change
@@ -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.
39 changes: 39 additions & 0 deletions doc/md/motoko-packages/types-interfaces.md
Original file line number Diff line number Diff line change
@@ -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.




59 changes: 59 additions & 0 deletions doc/md/motoko-packages/utilities.md
Original file line number Diff line number Diff line change
@@ -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.


2 changes: 1 addition & 1 deletion doc/md/reference/_category_.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
position: 7
position: 8
label: 'References'
collapsible: true # make the category collapsible
collapsed: true
8 changes: 8 additions & 0 deletions doc/md/stable-memory/stable-regions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
6 changes: 6 additions & 0 deletions doc/md/stable-memory/stablememory.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
10 changes: 9 additions & 1 deletion doc/md/writing-motoko/async-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.