Skip to content

Commit

Permalink
Merge pull request #19 from casper-ecosystem/documentation_updates
Browse files Browse the repository at this point in the history 
Documentation updates
  • Loading branch information
@ipopescu
ipopescu authored Feb 6, 2024
2 parents 5ca6610 + 36732d5 commit 1dbd7c6
Show file tree
Hide file tree
Showing 8 changed files with 155 additions and 148 deletions.
61 changes: 36 additions & 25 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,13 @@

## Design Goals

This repository adheres to the following design goals for the [CEP-85 multi-token standard](https://github.com/casper-network/ceps/blob/multi-token-standard/text/0085-multi-token-standard.md):

- DApp developers attempting to create a multi-token contract should be able to install the contract as is, with modalities as required for their needs.
- Reference implementation should showcase modalities and options for installation and entrypoints for use after installation.
- CEP-85 reference implementation should be self-contained within a single repo, including all tests and documentation for Casper Labs provided SDKs.
- Should adhere to the publicly perceived expected behavior of a multi-token standard.
- Standard session code should be provided to interact with the installed contract, allowing DApp developers to access normal functions without writing new Wasm-producing logic.
- This reference implementation showcases modalities and options for installation and entrypoints for use after installation.
- The reference implementation is self-contained within a single repository, including all tests and documentation for the SDKs provided.
- The implementation adheres to a multi-token standard's publicly perceived expected behavior.
- Standard session code is provided to interact with the installed contract, allowing dApp developers to access normal functions without writing new Wasm-producing logic.

## Table of Contents

Expand All @@ -28,25 +30,30 @@

## Building the Contract

The `main.rs` file within the contract provides the installer for the multi-token contract. Users can compile the contract to Wasm alongside support tests using the `make prepare` and `make test` commands from the Makefile provided.
The `main.rs` file within the contract provides the installer for the multi-token contract. Users can compile the contract to Wasm alongside support tests using the following commands from the Makefile provided:

```sh
make prepare
make test
```

The pre-built Wasm for the contract and all other utility session code can be found as part of the most current release. Users wishing to build the Wasm themselves can pull the code and use the `make build-contract` command provided in the Makefile. Please note, however, that you must install `wasm-strip` to build the contract.
The pre-built Wasm for the contract and all other utility session code can be found in the most current release. Users wishing to build the Wasm themselves can pull the code and use the `make build-contract` command provided in the Makefile. Please note, however, that you must install `wasm-strip` to build the contract.

The `call` method will install the contract with the necessary entrypoints and call the `init()` entrypoint, which allows the contract to self-initialize and set up the necessary state variables for operation.d
The `call` method will install the contract with the necessary entrypoints and call the `init()` entrypoint, which allows the contract to self-initialize and set up the necessary state variables for operation.

## Required Runtime Arguments

The following are the required runtime arguments that must be passed to the installer session code to correctly install the multi-token contract.
The following are the required runtime arguments to be passed to the installer session code to install the multi-token contract correctly.

- `"name"`: The name of the multi-token collection, passed in as a `String`. This parameter is required and cannot be changed post installation.
- `"name"`: The name of the multi-token collection, passed in as a `String`. This parameter is required and cannot be changed after installation.
- `"uri"`: A string URI for any off-chain resource associated with the collection.

The following are the optional parameters that can be passed in at the time of installation.
The following are the optional parameters that can be passed in during installation.

- `"events_mode"`: The [`EventsMode`](#eventsmode) modality that selects the event schema used to record any changes that occur to tokens issued by the contract instance. This argument is passed in as a `u8` value.
- `"enable_burn"`: The [`EnableBurn`](#enableburn) modality dictates whether the contract instance will allow approved entities to permanently burn tokens. This argument is passed in as a `bool` value.
- `"enable_burn"`: The [`EnableBurn`](#enableburn) modality dictates whether the contract instance will allow approved entities to burn tokens permanently. This argument is passed in as a `bool` value.
- `"transfer_filter_contract"`: This argument dictates a secondary contract instance that will serve as a transfer filter for the installing instance of CEP-85. Passing an argument with a value of type `Key` will enable this feature.
- `"transfer_filter_method"`: This argument outlines the name of the entrypoint on the transfer filter contract that is used to process the filter. It is passed as an `String`.
- `"transfer_filter_method"`: This argument outlines the name of the entrypoint on the transfer filter contract that is used to process the filter. It is passed as a `String`.

In addition, the following arguments may be passed to establish their associated user lists.

Expand Down Expand Up @@ -109,34 +116,38 @@ For this CEP-85 reference implementation, the events schema is as follows:

#### Transfer Filter Hook

The transfer filter modality, if enabled, specifies a contract package hash pointing to a contract that will be called when the `safe_transfer_from` or `safe_batch_transfer_from` methods are invoked on the contract. CEP-85 will call the transfer filter method on the specified callback contract, which is expected to return a value of `TransferFilterContractResult`, represented as a u8.
If enabled, the transfer filter modality specifies a contract package hash pointing to a contract that will be called when the `safe_transfer_from` or `safe_batch_transfer_from` methods are invoked on the contract. CEP-85 will call the transfer filter method on the specified callback contract, which is expected to return a value of `TransferFilterContractResult`, represented as a u8.

- `TransferFilterContractResult::DenyTransfer` will block the transfer regardless of the outcome of other checks
- `TransferFilterContractResult::ProceedTransfer` will allow the transfer to proceed if other checks also pass

The transfer filter can be enabled by passing an `ARG_TRANSFER_FILTER_CONTRACT` argument to the install method, with a value of type `Key`. The transfer filter method can be defined with the `ARG_TRANSFER_FILTER_METHOD` argument.

This parameter is optional and cannot be changed post installation.
This parameter is optional and cannot be changed after installation.

## Installing and Interacting with the Contract using the Rust Casper Client

### Example deploy
You can find instructions on installing an instance of the CEP-85 contract using the [Rust CLI Casper client](/docs/using-casper-client.md).

The following is an example of installing the CEP-85 contract via a deploy using the Rust CLI Casper client. You can find more examples [here](/docs/using-casper-client.md).
### Example

The following is an example of installing the CEP-85 contract via a deploy using the Rust CLI Casper client.

```bash
casper-client put-deploy -n https://rpc.testnet.casperlabs.io/ --chain-name "casper-test" --payment-amount 500000000000 -k keys/secret_key.pem --session-path target/wasm32-unknown-unknown/release/cep85.wasm \
casper-client put-deploy -n https://rpc.testnet.casperlabs.io/ \
--chain-name "casper-test" \
--payment-amount 500000000000 \
-k keys/secret_key.pem \
--session-path target/wasm32-unknown-unknown/release/cep85.wasm \
--session-arg "name:string='multi-token-1'" \
--session-arg "uri:string='https://docs.casper.network/'" \
--session-arg "events_mode:u8='0'" \
--session-arg "enable_burn:bool='true'" \
--session-arg "enable_burn:bool='true'"
```

## Installing and Interacting with the Contract using the Rust Casper Client

You can find instructions on installing an instance of the CEP-85 contract using the Rust CLI Casper client [here](/docs/using-casper-client.md).

## Installing and Interacting with the Contract using the JS Casper Client
## Installing and Interacting with the Contract using the JavaScript Casper Client

You can find instructions on installing an instance of the CEP-85 contract using the JS Casper client [here](/client-js/README.md)
You can find instructions on installing an instance of the CEP-85 contract using the [JS Casper client](/client-js/README.md).

## Test Suite and Specification

Expand Down Expand Up @@ -167,7 +178,7 @@ The expected behavior of the multi-token contract implementation is asserted by
| 19 | InvalidCollectionName |
| 20 | InvalidContractHash |
| 21 | InvalidData |
| 22 | InvalidEnableMBFlag |
| 22 | InvalidEnableBurnFlag |
| 23 | InvalidEventsMode |
| 24 | InvalidFrom |
| 25 | InvalidId |
Expand Down
48 changes: 25 additions & 23 deletions client-js/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This package was created to help JavaScript/TypeScript users with the [cep-85](https://github.com/casper-ecosystem/cep-85) contract and is published in `npm` as the [casper-cep85-js-client](https://www.npmjs.com/package/casper-cep85-js-client). It was built on top of the [casper-js-sdk](https://github.com/casper-ecosystem/casper-js-sdk).

CEP85Client is a TypeScript class that provides a high-level interface for interacting with a Casper blockchain smart contract implementing the CEP-85 standard. The standard defines methods for managing fungible and non-fungible tokens, as well as setting various parameters for token contracts.
`CEP85Client` is a TypeScript class that provides a high-level interface for interacting with a Casper blockchain smart contract implementing the CEP-85 standard. The standard defines methods for managing fungible and non-fungible tokens and setting various parameters for token contracts.

This JavaScript client gives you an easy way to install and interact with the Casper CEP-85 contract.
Users can treat this package as a deploy builder for all of these possible interactions:
Expand All @@ -15,31 +15,33 @@ Users can treat this package as a deploy builder for all of these possible inter
- Approval of operators
- Changing security configurations after installation
- Setting the URI for a collection or tokens
- Qurying some of the contract-related data
- Querying some of the contract-related data

## Usage

1. To install, run the following command:
1. To install the client, run the following command:

`npm i -S casper-cep85-js-client`

2. Import the CEP-85 contract in the code for your project:

`import { CEP85Client } from 'casper-cep85-js-client'`

3. If you want to install an instance of CEP-85 to a Casper network, familiarize yourself with the `install` method and all possible configuration options (`InstallArgs`).
3. If you want to install an instance of CEP-85 on a Casper network, familiarize yourself with the `install` method and all possible configuration options (`InstallArgs`).

4. If you want to start working with a previously installed instance of CEP-85, use the `setContractHash(contractHash)` method and include the existing `Contract Hash` for that instance of CEP-85.
4. If you want to work with a previously installed instance of CEP-85, use the `setContractHash(contractHash)` method and include the existing `Contract Hash` for that instance of CEP-85.

NOTE: Since version `1.3` both `casper-js-sdk` and `@make-software/ces-js-parser` are peer dependencies. If you are using npm version `<7` you may need to install both dependencies manually.
> NOTE: Since version `1.3`, both `casper-js-sdk` and `@make-software/ces-js-parser` are peer dependencies. If you use npm version `<7`, you may need to install both dependencies manually.
## Prepare

Running `npm run wasms:convert` will copy the CEP-85 contract Wasm file to the `/wasm/` folder
Run the following command to copy the CEP-85 contract Wasm file to the `/wasm/` folder:

`npm run wasms:convert`

## Examples

As a good starting point, you can look into the [TUTORIAL](https://github.com/casper-ecosystem/TUTORIAL.md) and the `examples/` directory to see the most common usage scenarios (`install.ts` and `usage.ts`). You can install the contract and run the example scenario by running the `npm run example:install` and `npm run example:usage`. You will need to specify environment variables, preferebly in a `client-js/.env` file. Here are some example values for the environment variables that need to be specified, pointing to a local NCTL network:
As a starting point, look into the [TUTORIAL](https://github.com/casper-ecosystem/TUTORIAL.md) and the `examples/` directory to see the most common usage scenarios (`install.ts` and `usage.ts`). Install the contract and run the example scenario by running the `npm run example:install` and `npm run example:usage` commands. You must specify environment variables, preferably in a `client-js/.env` file. Here are some example values for the environment variables that need to be specified, pointing to a local NCTL network:

```
NODE_URL=http://localhost:11101/rpc
Expand All @@ -51,13 +53,13 @@ USER1_KEY_PAIR_PATH=/Users/someuser/.casper/casper-node/utils/nctl/assets/net-1/

## Development

Before installing the node modules, ensure that the contract Wasm is generated by running the following at root folder of the cep-85:
Before installing the node modules, run the following command in the root folder of the `cep-85` repository to generate the contract Wasm:

```bash
make build-contract
```

After generating the Wasm file, you can install the node modules and the Wasm will be automatically bundled.
After generating the Wasm file, install the node modules and the Wasm will be automatically bundled.

```bash
cd client-js
Expand All @@ -66,21 +68,21 @@ npm install && npm run wasms:convert

## Testing

Run Integration tests:
The following command runs the integration tests:

```bash
npm run test
```

## Event Handling

CEP-85 tokens support the [Casper Event Standard (CES)](https://github.com/make-software/casper-event-standard), and tokens can be installed with or without event logging as described [here](../cep85/README.md#eventsmode). If you install a token with the `EventsMode` set to CES, you can listen to token events using the `EventStream` from the `casper-js-sdk`. To consume token events, you should also install the `@make-software/ces-js-parser` by running this command:
CEP-85 tokens support the [Casper Event Standard (CES)](https://github.com/make-software/casper-event-standard), and the tokens can be installed with or without event logging as described [here](../cep85/README.md#eventsmode). If you install a token with the `EventsMode` set to CES, you can listen to token events using the `EventStream` from the `casper-js-sdk`. To consume token events, you should also install the `@make-software/ces-js-parser` by running this command:

```bash
npm install @make-software/ces-js-parser
```

Set up the `EventStream`:
Here is how to set up the `EventStream`:

```ts
import { EventStream } from 'casper-js-sdk';
Expand All @@ -102,17 +104,17 @@ Here is how you can consume events using event listeners:

- Add an event listener:

```ts
const listener = (event) => {
console.log(event.name); // 'Burn'
console.log(event.data); // Burn event info
};
```ts
const listener = (event) => {
console.log(event.name); // 'Burn'
console.log(event.data); // Burn event info
};

cep85.on('Burn', listener);
```
cep85.on('Burn', listener);
```

- Remove an event listener:

```ts
cep85.off('Burn', listener);
```
```ts
cep85.off('Burn', listener);
```
Loading

0 comments on commit 1dbd7c6

Please sign in to comment.