From da8fa4eb37dfbbe1ec0dd1a4a3817355280a7b04 Mon Sep 17 00:00:00 2001 From: Quint Daenen Date: Thu, 30 Sep 2021 15:23:33 +0200 Subject: [PATCH] Add some docs. --- README.md | 2 +- examples/MyToken/package-set.dhall | 2 +- src/Ext.mo | 13 ++++++++-- src/Interface.mo | 38 +++++++++++++++++++++++------- 4 files changed, 43 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 455fd8f..deb41bd 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ let Package = { name : Text, version : Text, repo : Text, dependencies : List Te let additions = [ { name = "std" , repo = "https://github.com/aviate-labs/ext.std" - , version = "main" + , version = "v0.1.0" , dependencies = ["base", "principal"] }, -- See examples/ for the complete file. diff --git a/examples/MyToken/package-set.dhall b/examples/MyToken/package-set.dhall index ee41cee..7c720ca 100644 --- a/examples/MyToken/package-set.dhall +++ b/examples/MyToken/package-set.dhall @@ -4,7 +4,7 @@ let Package = { name : Text, version : Text, repo : Text, dependencies : List Te let additions = [ { name = "std" , repo = "https://github.com/aviate-labs/ext.std" - , version = "main" + , version = "v0.1.0" , dependencies = ["base", "principal"] }, { name = "principal" diff --git a/src/Ext.mo b/src/Ext.mo index 1a5d922..85e326f 100644 --- a/src/Ext.mo +++ b/src/Ext.mo @@ -46,6 +46,7 @@ module { }; }; + // Balance refers to an amount of a particular token. public type Balance = Nat; public type CommonError = { @@ -55,17 +56,22 @@ module { public type Extension = Text; + // Represents a 'payment' memo which can be attached to a transaction. public type Memo = Blob; + // A unique id for a particular token and reflects the canister where the + // token resides as well as the index within the tokens container. public type TokenIdentifier = Text; public module TokenIdentifier = { private let prefix : [Nat8] = [10, 116, 105, 100]; // \x0A "tid" - public func encode(principal : Principal, tokenIndex : TokenIndex) : TokenIdentifier { + // Encodes the given canister id and token index into a token identifier. + // \x0A + "tid" + canisterId + token index + public func encode(canisterId : Principal, tokenIndex : TokenIndex) : TokenIdentifier { let rawTokenId = Array.flatten([ prefix, - Blob.toArray(Principal.toBlob(principal)), + Blob.toArray(Principal.toBlob(canisterId)), Binary.BigEndian.fromNat32(tokenIndex), ]); Text.fromIter(Iter.fromArray( @@ -78,6 +84,7 @@ module { )); }; + // Decodes the given token identifier into the underlying canister id and token index. public func decode(tokenId : TokenIdentifier) : Result.Result<(Principal, TokenIndex), Text> { var err : ?Text = null; var bs = Array.map( @@ -107,10 +114,12 @@ module { }; }; + // Represents an individual token's index within a given canister. public type TokenIndex = Nat32; public module TokenIndex = { public func equal(a : TokenIndex, b : TokenIndex) : Bool { a == b; }; + public func hash(a : TokenIndex) : Hash.Hash { a; }; }; diff --git a/src/Interface.mo b/src/Interface.mo index c1572af..2168a3c 100644 --- a/src/Interface.mo +++ b/src/Interface.mo @@ -4,34 +4,56 @@ module { // A basic token interface, used for f.e. ERC20 tokens. // Contains the minimal interface for a fungible token. public type FungibleToken = actor { - // @ext:core + // [@ext:core] + + // Returns the balance of a requested User. balance : query (request : Ext.Core.BalanceRequest) -> async Ext.Core.BalanceResponse; + // Returns an array of extensions that the canister supports. + // Should be at least ["@ext:common"]. extensions : query () -> async [Ext.Extension]; + // Transfers an given amount of tokens between two users, from and to, with an optional memo. transfer : shared (request : Ext.Core.TransferRequest) -> async Ext.Core.TransferResponse; - // @ext:common - metadata : query (token : Ext.TokenIdentifier) -> async Ext.Common.MetadataResponse; - supply : query (token : Ext.TokenIdentifier) -> async Ext.Common.SupplyResponse; + // [@ext:common] + + // Returns the metadata of the token. + metadata : query (tokenId : Ext.TokenIdentifier) -> async Ext.Common.MetadataResponse; + // Returns the total supply of the token. + supply : query (tokenId : Ext.TokenIdentifier) -> async Ext.Common.SupplyResponse; }; // A basic nft interface, used for f.e. ERC721 tokens. // Contains the minimal interface for a non fungible token. public type NonFungibleToken = actor { - // @ext:core + // [@ext:core] + + // Returns the balance of a requested User. balance : query (request : Ext.Core.BalanceRequest) -> async Ext.Core.BalanceResponse; + // Returns an array of extensions that the canister supports. + // Should be at least ["@ext:common", "@ext:nonfungible", "@ext:allowance"]. extensions : query () -> async [Ext.Extension]; + // Transfers an given amount of tokens between two users, from and to, with an optional memo. transfer : shared (request : Ext.Core.TransferRequest) -> async Ext.Core.TransferResponse; - // @ext:common + // [@ext:common] + + // Returns the metadata of the given token. metadata : query (token : Ext.TokenIdentifier) -> async Ext.Common.MetadataResponse; + // Returns the total supply of the token. supply : query (token : Ext.TokenIdentifier) -> async Ext.Common.SupplyResponse; - // @ext:nonfungible + // [@ext:nonfungible] + + // Returns the account that is linked to the given token. bearer : query (token : Ext.TokenIdentifier) -> async Ext.NonFungible.BearerResponse; + // Mints a new NFT and assignes its owner to the given User. mintNFT : shared (request : Ext.NonFungible.MintRequest) -> async (); - // @ext:allowance + // [@ext:allowance] + + // Returns the amount which the given spender is allowed to withdraw from the given owner. allowance : query (request : Ext.Allowance.Request) -> async Ext.Allowance.Response; + // Allows the given spender to withdraw from your account multiple times, up to the given allowance. approve : shared (request : Ext.Allowance.ApproveRequest) -> async (); }; };