Add cw1155 specification

packages/cw0/src/event.rs

@@ -1,5 +1,7 @@
-use cosmwasm_std::Attribute;
+use cosmwasm_std::Response;
 
+/// This defines a set of attributes which should be added to `Response`.
 pub trait Event {
-    fn write_attributes(&self, attributes: &mut Vec<Attribute>);
+    /// Append attributes to response
+    fn add_attributes(&self, response: &mut Response);
 }

packages/cw1155/Cargo.toml

@@ -10,9 +10,10 @@ homepage = "https://cosmwasm.com"
 documentation = "https://docs.cosmwasm.com"
 
 [dependencies]
+cw0 = { path = "../../packages/cw0", version = "0.6.0-alpha1" }
 cosmwasm-std = { version = "0.14.0-beta1" }
 schemars = "0.7"
 serde = { version = "1.0.103", default-features = false, features = ["derive"] }
 
 [dev-dependencies]
-cosmwasm-schema = { version = "0.14.0-alpha2" }
+cosmwasm-schema = { version = "0.14.0-beta1" }

packages/cw1155/README.md

@@ -3,42 +3,47 @@
 CW1155 is a specification for managing multiple tokens based on CosmWasm.
 The name and design is based on Ethereum's ERC1155 standard.
 
+The specification is split into multiple sections, a contract may only
+implement some of this functionality, but must implement the base.
+
 Design decisions:
 
 - Fungible tokens and non-fungible tokens are treated equally, non-fungible tokens just have one max supply.
 
-- Approval is set or unset to some operator over entire set of tokens. (More nuanced control is defined in [ERC1761](https://eips.ethereum.org/EIPS/eip-1761), do we want to merge them together?)
-
-- Metadata and token enumeration should be done by indexing events off-chain.
+- Approval is set or unset to some operator over entire set of tokens. (More nuanced control is defined in [ERC1761](https://eips.ethereum.org/EIPS/eip-1761), do we want to merge them together?)
 
 - Mint and burn are mixed with transfer/send messages, otherwise, we'll have much more message types, e.g. `Mint`/`MintToContract`/`BatchMint`/`BatchMintToContract`, etc.
 
-  In transfer/send messges, `from`/`to` are optional, a `None` `from` means minting, a `None` `to` means burning, they must not both be `None` at the same time.
+  In transfer/send messges, `from`/`to` are optional, a `None` `from` means minting, a `None` `to` means burning, they must not both be `None` at the same time.
 
 ## Base
 
 ### Messages
 
-`TransferFrom{from, to, token_id, value}` - This transfers some amount of tokens between two accounts. The operator should have approval from the source account.
+`TransferFrom{from, to, token_id, value}` - This transfers some amount of tokens between two accounts. The operator should either be the `from` account or have approval from it.
 
 `SendFrom{from, to, token_id, value, msg}` - This transfers some amount of tokens between two accounts. `to` 
 must be an address controlled by a smart contract, which implements
-the `CW1155Receiver` interface. The operator should have approval from the source account. The `msg` will be passed to the recipient contract, along with the other fields.
+the `CW1155Receiver` interface. The operator should eitherbe the `from` account or have approval from it. The `msg` will be passed to the recipient contract, along with the other fields.
 
 `BatchTransferFrom{from, to, batch}` - Batched version of `TransferFrom` which can handle multiple types of tokens at once.
 
 `BatchSendFrom{from, contract, batch, msg}` - Batched version of `SendFrom` which can handle multiple types of tokens at once.
 
-`SetApprovalForAll { operator, approved }` - Grant or revoke  `operator` the permission to transfer or send all tokens owned by `msg.sender`. This approval is tied to the owner, not the
-tokens and applies to any future token that the owner receives as well.
+`ApproveAll{ operator, expires }` - Allows operator to transfer / send any token from the owner's account. If expiration is set, then this allowance has a time/height limit.
+
+`RevokeAll { operator }` - Remove previously granted ApproveAll permission
 
 ### Queries
 
 `Balance { owner, token_id }` - Query the balance of `owner` on perticular type of token, default to `0` when record not exist.
 
-`BatchBalance { owner, token_ids }` - Query the balance of `owner` on multiple types of tokens, batched version of `Balance`
+`BatchBalance { owner, token_ids }` - Query the balance of `owner` on multiple types of tokens, batched version of `Balance`.
 
-`ApprovedForAll{ owner, spender }` - Query if `spender` has the permission to transfer or send tokens owned by `msg.sender`.
+`ApprovedForAll{owner, include_expired, start_after, limit}` - List all operators that can
+access all of the owner's tokens. Return type is `ApprovedForAllResponse`.
+If `include_expired` is set, show expired owners in the results, otherwise,
+ignore them. If query for some specific operator, set `start_after` to the operator, and set limit to 1.
 
 ### Receiver
 
@@ -52,12 +57,39 @@ Any contract wish to receive CW1155 tokens must implement `Cw1155ReceiveMsg` and
 
 - `transfer(from, to, token_id, value)`
 
-  `from`/`to` are optional, no `from` attribute means minting, no `to` attribute means burning.
+  `from`/`to` are optional, no `from` attribute means minting, no `to` attribute means burning, but they mustn't be neglected at the same time.
+
+
+## Metadata
+
+### Queries
+
+`TokenInfo{ token_id }` - Query metadata url of `token_id`.
+
+### Events
+
+`token_info(url, token_id)`
+
+Metadata url of `token_id` is changed, `url` should point to a json file.
+
+## Enumerable
+
+### Queries
 
-- `metadata(url, token_id)`
+Pagination is acheived via `start_after` and `limit`. Limit is a request
+set by the client, if unset, the contract will automatically set it to
+`DefaultLimit` (suggested 10). If set, it will be used up to a `MaxLimit`
+value (suggested 30). Contracts can define other `DefaultLimit` and `MaxLimit`
+values without violating the CW1155 spec, and clients should not rely on
+any particular values.
 
-  Metadata url of `token_id` is changed, `url` should point to a json file.
+If `start_after` is unset, the query returns the first results, ordered by
+lexogaphically by `token_id`. If `start_after` is set, then it returns the
+first `limit` tokens *after* the given one. This allows straight-forward 
+pagination by taking the last result returned (a `token_id`) and using it
+as the `start_after` value in a future query. 
 
-## Metadata and Enumerable
+`Tokens{owner, start_after, limit}` - List all token_ids that belong to a given owner.
+Return type is `TokensResponse{tokens: Vec<token_id>}`.
 
-[TODO] ERC1155 suggests that metadata and enumerable should be indexed from events log, to save some on-chain storage. Should we define standard events like ERC1155?
+`AllTokens{start_after, limit}` - Requires pagination. Lists all token_ids controlled by the contract.

packages/cw1155/examples/schema.rs

@@ -18,4 +18,6 @@ fn main() {
     export_schema(&schema_for!(cw1155::BalanceResponse), &out_dir);
     export_schema(&schema_for!(cw1155::BatchBalanceResponse), &out_dir);
     export_schema(&schema_for!(cw1155::ApprovedForAllResponse), &out_dir);
+    export_schema(&schema_for!(cw1155::TokenInfoResponse), &out_dir);
+    export_schema(&schema_for!(cw1155::TokensResponse), &out_dir);
 }

packages/cw1155/schema/cw1155_query_msg.json

@@ -54,7 +54,7 @@
       }
     },
     {
-      "description": "Queries the approval status of an operator for a given owner Return type: ApprovedForAllResponse.",
+      "description": "Query the approval status of an operator for a given owner Return type: ApprovedForAllResponse.",
       "type": "object",
       "required": [
         "approved_for_all"
@@ -76,6 +76,88 @@
           }
         }
       }
+    },
+    {
+      "description": "With MetaData Extension. Query metadata of token Return type: TokenInfoResponse.",
+      "type": "object",
+      "required": [
+        "token_info"
+      ],
+      "properties": {
+        "token_info": {
+          "type": "object",
+          "required": [
+            "token_id"
+          ],
+          "properties": {
+            "token_id": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    {
+      "description": "With Enumerable extension. Returns all tokens owned by the given address, [] if unset. Return type: TokensResponse.",
+      "type": "object",
+      "required": [
+        "tokens"
+      ],
+      "properties": {
+        "tokens": {
+          "type": "object",
+          "required": [
+            "owner"
+          ],
+          "properties": {
+            "limit": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "owner": {
+              "$ref": "#/definitions/HumanAddr"
+            },
+            "start_after": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        }
+      }
+    },
+    {
+      "description": "With Enumerable extension. Requires pagination. Lists all token_ids controlled by the contract. Return type: TokensResponse.",
+      "type": "object",
+      "required": [
+        "all_tokens"
+      ],
+      "properties": {
+        "all_tokens": {
+          "type": "object",
+          "properties": {
+            "limit": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "start_after": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        }
+      }
     }
   ],
   "definitions": {

packages/cw1155/schema/token_info_response.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "TokenInfoResponse",
+  "type": "object",
+  "required": [
+    "url"
+  ],
+  "properties": {
+    "url": {
+      "description": "Should be a url point to a json file",
+      "type": "string"
+    }
+  }
+}

packages/cw1155/schema/tokens_response.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "TokensResponse",
+  "type": "object",
+  "required": [
+    "tokens"
+  ],
+  "properties": {
+    "tokens": {
+      "description": "Contains all token_ids in lexicographical ordering If there are more than `limit`, use `start_from` in future queries to achieve pagination.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

packages/cw1155/src/lib.rs

@@ -1,6 +1,7 @@
 pub use crate::msg::{Cw1155HandleMsg, TokenId};
 pub use crate::query::{
-    ApprovedForAllResponse, BalanceResponse, BatchBalanceResponse, Cw1155QueryMsg,
+    Approval, ApprovedForAllResponse, BalanceResponse, BatchBalanceResponse, Cw1155QueryMsg,
+    TokenInfoResponse, TokensResponse,
 };
 pub use crate::receiver::{Cw1155BatchReceiveMsg, Cw1155ReceiveMsg};
 

packages/cw1155/src/msg.rs

@@ -2,13 +2,15 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
 use cosmwasm_std::{Binary, HumanAddr, Uint128};
+use cw0::Expiration;
 
 pub type TokenId = String;
 
 #[derive(Serialize, Deserialize, Clone, PartialEq, JsonSchema, Debug)]
 #[serde(rename_all = "snake_case")]
 pub enum Cw1155HandleMsg {
-    /// TransferFrom is a base message to move tokens, if `env.sender` has sufficient pre-approval.
+    /// TransferFrom is a base message to move tokens.
+    /// if `env.sender` is the owner or has sufficient pre-approval.
     TransferFrom {
         // `None` means minting
         from: Option<HumanAddr>,
@@ -17,8 +19,8 @@ pub enum Cw1155HandleMsg {
         token_id: TokenId,
         value: Uint128,
     },
-    /// SendFrom is a base message to move tokens to contract
-    /// if `env.sender` has sufficient pre-approval.
+    /// SendFrom is a base message to move tokens to contract.
+    /// if `env.sender` is the owner or has sufficient pre-approval.
     SendFrom {
         // `None` means minting
         from: Option<HumanAddr>,
@@ -27,22 +29,30 @@ pub enum Cw1155HandleMsg {
         value: Uint128,
         msg: Option<Binary>,
     },
-    /// BatchTransferFrom is a base message to move tokens to another account without triggering actions
+    /// BatchTransferFrom is a base message to move tokens to another account without triggering actions.
+    /// if `env.sender` is the owner or has sufficient pre-approval.
     BatchTransferFrom {
         // `None` means minting
         from: Option<HumanAddr>,
         // `None` means burning
         to: Option<HumanAddr>,
         batch: Vec<(TokenId, Uint128)>,
     },
-    /// BatchSendFrom is a base message to move tokens to another to without triggering actions
+    /// BatchSendFrom is a base message to move tokens to another to without triggering actions.
+    /// if `env.sender` is the owner or has sufficient pre-approval.
     BatchSendFrom {
         // `None` means minting
         from: Option<HumanAddr>,
         contract: HumanAddr,
         batch: Vec<(TokenId, Uint128)>,
         msg: Option<Binary>,
     },
-    /// Enable or disable approval for a third party ("operator") to manage all of the caller's tokens.
-    SetApprovalForAll { operator: HumanAddr, approved: bool },
+    /// Allows operator to transfer / send any token from the owner's account.
+    /// If expiration is set, then this allowance has a time/height limit
+    ApproveAll {
+        operator: HumanAddr,
+        expires: Option<Expiration>,
+    },
+    /// Remove previously granted ApproveAll permission
+    RevokeAll { operator: HumanAddr },
 }