Skip to content

Commit

Permalink
Merge pull request #258 from ultraio/feature/BLOCK-2586-enable-token-…
Browse files Browse the repository at this point in the history 
…document-on-staging

[BLOCK-2586] enable staging document
  • Loading branch information
@Adam-Ultra
Adam-Ultra authored Nov 27, 2024
2 parents 23425ae + 1be2978 commit 3549a46
Show file tree
Hide file tree
Showing 19 changed files with 2,227 additions and 0 deletions.
179 changes: 179 additions & 0 deletions docs/blockchain/contracts/nft-contract/nft-actions/addkeys.a.staging.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
---
title: 'addkeys.a'
order: 49

---

# addkeys.a

Add key pairs for Uniq factory

## Technical Behavior

The manager of an Uniq factory should be able to add one or more key pairs at the factory level at any time, which means key pairs at the factory level can change over time. When that happens, all Uniqs minted from that factory should be able to use all key pairs no matter when minted.

Key `name` has to be unique.

Key `type` is the data type of the value, and it has to be in the supported list from `keytypes` table.

`edit_rights` define which permission can edit the value including manager | owner | authorized editor | user group.

`editor` this is authorized editor mentioned above, and it required to have at least one account here.

`default_value` has to match the key `type`, like integer if it's `uint` or `int`. Also, if the type is an array, total element cannot exceed the limit from [`keytypes` action](./setktypes.md). In case of the `string` or `string[]`, total character cannot exceed the limit.

Factory RAM payment will be calculated based on the usage of `key_defs` which include some fixed RAM usage and usage which will determined by the key `type`. And the payment is non-refundable.

Uniq RAM payment for the new key will be calculated based on how many Uniq are already minted from factory. And this payment will be put into factory on-chain RAM vault, which will be refunded when Uniq is burn.

## Action Parameters

The properties of this type are provided below:

| Property Name | C++ Type | JavaScript Type | Description |
| ------------- | ---------------------------- | --------------- | --------------------------------------------------------------------------------------- |
| factory_id | uint64_t | Number | ID of the Uniq factory for which key pairs will be added. |
| key_defs | std::vector\<key_def_action> | Object[] | The definition of the key including name, type, edit right, editors and default values. |
| memo | string | String | Memo |

### `key_def_action` interface

| Property Name | C++ Type | JavaScript Type | Description |
| ------------- | ------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------- |
| name | string | String | The name of the key, needs to be unique. |
| type | string | String | The type of the value stored in the key. |
| edit_rights | uint8_t | Number | Bitmask, determines who can edit the key including asset manager, owner, authorized editor or user group. |
| editors | std::vector\<name> | String[] | The editor if authorized editor is set. |
| default_value | std::optional\<key_value_store> | Object | The default value of the key which needs to match with type. |

`key_value_store` will be an array with first element is type of the value and second is the value. Here is the support list and example:

| Value Type | Key Def Type string | Example |
| ---------- | ------------------- | ---------------- |
| int8 | int8 | ["int8", 0] |
| int16 | int16 | ["int16", 0] |
| int32 | int32 | ["int32", 0] |
| int64 | int64 | ["int64", 0] |
| uint8 | uint8 | ["uint8", 0] |
| uint16 | uint16 | ["uint16", 0] |
| uint32 | uint32 | ["uint32", 0] |
| uint64 | uint64 | ["uint64", 0] |
| float | float32 | ["float32", 0.1] |
| double | float64 | ["float64", 0.1] |
| string | string | ["string", "a"] |

### `edit_rights` bitmask breakdown

| Value | Description |
| ------ | --------------------------------------------- |
| `0x01` | Manager can edit |
| `0x02` | Owner can edit |
| `0x04` | Authorized editor can edit (used with `0x08`) |
| `0x08` | Editor is a user group |

## CLI - cleos

```bash
cleos push action eosio.nft.ft addkeys.a '{ "factory_id": 10, "key_defs": [ { "name": "id1", "type": "int8", "edit_rights": 8, "editors": [ "bob" ], "default_value": [ "int8", -8 ] }, { "name": "id2", "type": "int16", "edit_rights": 8, "editors": [ "bob" ], "default_value": [ "int16", 16 ] }, { "name": "id3", "type": "int32", "edit_rights": 8, "editors": [ "bob" ], "default_value": [ "int32", -32 ] }, { "name": "id4", "type": "int64", "edit_rights": 8, "editors": [ "bob" ], "default_value": [ "int64", 64 ] }, { "name": "id5", "type": "uint8", "edit_rights": 8, "editors": [ "bob" ], "default_value": [ "uint8", 8 ] }, { "name": "id6", "type": "uint16", "edit_rights": 8, "editors": [ "bob" ], "default_value": [ "uint16", 16 ] }, { "name": "id7", "type": "uint32", "edit_rights": 8, "editors": [ "bob" ], "default_value": [ "uint32", 32 ] }, { "name": "id8", "type": "uint64", "edit_rights": 8, "editors": [ "bob" ], "default_value": [ "uint64", 64 ] }, { "name": "id9", "type": "float32", "edit_rights": 8, "editors": [ "bob" ], "default_value": [ "float32", -1.32 ] }, { "name": "id10", "type": "float64", "edit_rights": 8, "editors": [ "bob" ], "default_value": [ "float64", 1.64 ] }, { "name": "id11", "type": "string", "edit_rights": 8, "editors": [ "bob" ], "default_value": [ "string", "abc" ] } ], "memo": "add new key pairs" }' -p alice@active
```

## JavaScript - eosjs

```js
await transact(
[
{
account: 'eosio.nft.ft',
name: 'addkeys.a',
authorization: [{ actor: 'alice', permission: 'active' }],
data: {
factory_id: 10,
key_defs: [
{
name: "id1",
type: "int8",
edit_rights: 8,
editors: [ "bob" ],
default_value: [ "int8", -8 ]
},
{
name: "id2",
type: "int16",
edit_rights: 8,
editors: [ "bob" ],
default_value: [ "int16", 16 ]
},
{
name: "id3",
type: "int32",
edit_rights: 8,
editors: [ "bob" ],
default_value: [ "int32", -32 ]
},
{
name: "id4",
type: "int64",
edit_rights: 8,
editors: [ "bob" ],
default_value: [ "int64", 64 ]
},
{
name: "id5",
type: "uint8",
edit_rights: 8,
editors: [ "bob" ],
default_value: [ "uint8", 8 ]
},
{
name: "id6",
type: "uint16",
edit_rights: 8,
editors: [ "bob" ],
default_value: [ "uint16", 16 ]
},
{
name: "id7",
type: "uint32",
edit_rights: 8,
editors: [ "bob" ],
default_value: [ "uint32", 32 ]
},
{
name: "id8",
type: "uint64",
edit_rights: 8,
editors: [ "bob" ],
default_value: [ "uint64", 64 ]
},
{
name: "id9",
type: "float32",
edit_rights: 8,
editors: [ "bob" ],
default_value: [ "float32", -1.32 ]
},
{
name: "id10",
type: "float64",
edit_rights: 8,
editors: [ "bob" ],
default_value: [ "float64", 1.64 ]
},
{
name: "id11",
type: "string",
edit_rights: 8,
editors: [ "bob" ],
default_value: [ "string", "abc" ]
}
],
"memo": "add new key pairs"
},
},
],
{
blocksBehind: 3,
expireSeconds: 30,
}
);
```
72 changes: 72 additions & 0 deletions docs/blockchain/contracts/nft-contract/nft-actions/bidauction.a.staging.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
---
title: 'bidauction.a'
order: 45

---

# bidauction.a

Bid on an Uniq auction

## Technical Behavior

The action checks that the auction exists in the `auction.a` table with the specified Uniq and verifies that the bid is placed between `start_date` and `expiry_date`.

`bidder` is not allowed to bid on the auctions where he is the `owner`.

`bid` must be at least `min_bid_increment_uos` UOS or `min_bid_increment_basis_point` basis points (units of 0.01%) higher than the previous bid. The values are defined in [`auctioncfg.a` table](../nft-tables.md#auctioncfg-a). This does not apply if the auction does not have any `bidder` which is true for a new auction without any bids.

`bidder` can bid on the auction where he is already the highest bidder.

UOS for the bid is transferred from the `bidder` account to the `eosio.nftauc` account and is released back to the original bidder if the new bid arrives.

`eosio.nftram` pays RAM usage.

A successful bid stores information about the `bidder`, `bid`, `receiver` and `promoter_id` and may increase the `expiry_date` of the auction by `auction_extension_step` if it happens within `auction_extension_threshold`. The values are defined in the `auctioncfg.a` table.

## Action Parameters

Action accepts a single argument `bid` of type `bid_auction_wrap_v0`. The properties of this type are provided below:

| Property Name | C++ Type | JavaScript Type | Description |
| ------------- | -------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| token_id | uint64_t | Number | ID of the Uniq for which there is an auction to bid on |
| bidder | name | String | Bidder account that authorizes the transaction and will pay the UOS bid |
| receiver | std::optional\<name> | String / Null | Optional receiver account of the Uniq in case this bid wins the auction. If no account is provided, the bidder will be used as a receiver |
| bid | asset | String | Proposed bid for the auction. It must respect the minimum increment specified in `auctioncfg.a` table |
| promoter_id | std::optional\<name> | Sting / Null | Optional promoter account |
| memo | string | String | Memo |

## CLI - cleos

```bash
cleos push action eosio.nft.ft bidauction.a '[{"token_id": 1, "bidder": "bob", "receiver": null, "bid": "10.00000000 UOS", "promoter_id": null, "memo": "my bid"}]' -p bob@active
```

## JavaScript - eosjs

```js
await transact(
[
{
account: 'eosio.nft.ft',
name: 'bidauction.a',
authorization: [{ actor: 'bob', permission: 'active' }],
data: {
create: {
token_id: 1,
bidder: "bob",
receiver: null,
bid: "10.00000000 UOS",
promoter_id: null,
memo: "my bid"
}
},
},
],
{
blocksBehind: 3,
expireSeconds: 30,
}
);
```
56 changes: 56 additions & 0 deletions docs/blockchain/contracts/nft-contract/nft-actions/cancelauct.a.staging.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: 'cancelauct.a'
order: 47

---

# cancelauct.a

Cancel an an Uniq auction without any bids

## Technical Behavior

The action checks that the auction exists in the `auction.a` table with the specified Uniq with ID `token_id`.

If the auction has reached its expiration date, the `canceler` can be any account, including the auction creator. Otherwise, only the auction creator can cancel an auction.

If the auction contains a bidder, the action will fail.

If all checks pass successfully, the auction will be erased from the `auction.a` table.

## Action Parameters

| Property Name | C++ Type | JavaScript Type | Description |
| ------------- | -------- | --------------- | -------------------------------------------------- |
| token_id | uint64_t | Number | Uniq ID for which the auction needs to be canceled |
| canceler | name | String | Account that authorizes the transaction |
| memo | string | String | Memo |

## CLI - cleos

```bash
cleos push action eosio.nft.ft cancelauct.a '[1, "alice", "cancel the auction"]' -p alice@active
```

## JavaScript - eosjs

```js
await transact(
[
{
account: 'eosio.nft.ft',
name: 'cancelauct.a',
authorization: [{ actor: 'alice', permission: 'active' }],
data: {
token_id: 1,
canceler: "alice",
memo: "cancel the auction",
},
},
],
{
blocksBehind: 3,
expireSeconds: 30,
}
);
```
74 changes: 74 additions & 0 deletions docs/blockchain/contracts/nft-contract/nft-actions/createauct.a.staging.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
title: 'createauct.a'
order: 44

---

# createauct.a

Create an Uniq auction

## Technical Behavior

The action stores the auction to the `auction.a` table with the specified arguments. The new auction ID is read from the `next.nftauc` table, whose `value` field is then incremented.

`eosio.nftram` pays RAM usage.

Only one auction may exist per Uniq. The Uniq, which is placed on auction, must not be on a resell.

`starting_price` should be no less than `min_starting_price` of `auctioncfg.a` and also should be no less than `minimum_resell_price` of the factory.

`promoter_basis_point` should be in the range between `min_promoter_share_bp` and `max_promoter_share_bp` of `saleshrlmcfg` table configurations for resale (scope `1`). The default range is between 200 (2.0 %) and 1000 (10 %).

Time between `start_date` (or the time when the transaction is executed) and `expiry_date` must be within `trading_window_start` and `trading_window_end` of the factory. It must also be at least equal to `min_duration` and must not exceed `max_duration` stored in `auctioncfg.a`.

`duration` should be in the range between `min_duration` and `max_duration` of `offercfg.a`. If duration is longer than the trading window of the factory, it will be capped by `trading_window_end`.

## Action Parameters

Action accepts a single argument `create` of type `create_auction_wrap_v0`. The properties of this type are provided below:

| Property Name | C++ Type | JavaScript Type | Description |
| -------------------- | ------------------------------ | --------------- | ------------------------------------------------------- |
| owner | name | String | Current owner of the Uniq |
| token_id | uint64_t | Number | ID of Uniq which the owner wants to place on an auction |
| starting_price | asset | String | Starting auction price in UOS |
| promoter_basis_point | uint16_t | Number | Promoter share in units of 0.01 % |
| start_date | std::optional\<time_point_sec> | String | Optional start date of the auction |
| expiry_date | time_point_sec | String | Initial expected date for the auction to end |
| memo | string | String | Memo |

## CLI - cleos

```bash
cleos push action eosio.nft.ft createauct.a '[{"owner": "alice", "token_id": 1, "starting_price": "2.00000000 UOS", "promoter_basis_point": 250, "start_date": null, "expiry_date": "2024-09-31T00:00:00", "memo": "new auction"}]' -p alice@active
```

## JavaScript - eosjs

```js
await transact(
[
{
account: 'eosio.nft.ft',
name: 'createauct.a',
authorization: [{ actor: 'alice', permission: 'active' }],
data: {
create: {
owner: "alice",
token_id: 1,
starting_price: "2.00000000 UOS",
promoter_basis_point: 250,
start_date: null,
expiry_date: "2024-09-31T00:00:00",
memo: "new auction"
}
},
},
],
{
blocksBehind: 3,
expireSeconds: 30,
}
);
```
Loading

0 comments on commit 3549a46

Please sign in to comment.