viz-js-lib 0.11.0 → 0.12.4

package/.qoder/docs/viz-cpp-node-docs/op-account-market.md

@@ -0,0 +1,236 @@
+# VIZ Blockchain — Account Market Operations
+
+Spec for implementing account sale operations in PHP/Node.js libraries.
+
+Account market operations allow accounts to be bought and sold. An account owner sets their account for sale, and a buyer can purchase it.
+
+---
+
+## `set_account_price_operation`
+
+**Type ID:** `54`
+**Required authority:** `master` of `account`
+
+Sets an account for sale or updates its sale parameters.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account` | `account_name_type` | yes | Account being listed for sale |
+| `account_seller` | `account_name_type` | yes | Account to receive payment |
+| `account_offer_price` | `asset` (VIZ) | yes | Asking price |
+| `account_on_sale` | `bool` | yes | `true` to list, `false` to delist |
+
+### JSON Example
+
+```json
+[54, {
+  "account": "alice",
+  "account_seller": "alice",
+  "account_offer_price": "1000.000 VIZ",
+  "account_on_sale": true
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'set_account_price_operation',
+    'value' => [
+        'account'             => 'alice',
+        'account_seller'      => 'alice',
+        'account_offer_price' => '1000.000 VIZ',
+        'account_on_sale'     => true,
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['set_account_price', {
+    account: 'alice',
+    account_seller: 'alice',
+    account_offer_price: '1000.000 VIZ',
+    account_on_sale: true,
+}];
+```
+
+### Checklist
+- [ ] `account_offer_price.symbol` must be `VIZ`
+- [ ] `account_offer_price.amount` > 0
+- [ ] `account_on_sale: false` delists the account
+- [ ] Fee (`account_on_sale_fee`) is charged when listing
+- [ ] `account_seller` can differ from `account` (payment redirected)
+- [ ] Sign with `account`'s master key
+
+---
+
+## `set_subaccount_price_operation`
+
+**Type ID:** `55`
+**Required authority:** `master` of `account`
+
+Lists the right to create subaccounts of `account` for sale. A "subaccount" of `alice` would be `alice.bob`.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account` | `account_name_type` | yes | Parent account |
+| `subaccount_seller` | `account_name_type` | yes | Account to receive payment |
+| `subaccount_offer_price` | `asset` (VIZ) | yes | Price per subaccount creation |
+| `subaccount_on_sale` | `bool` | yes | `true` to list, `false` to delist |
+
+### JSON Example
+
+```json
+[55, {
+  "account": "alice",
+  "subaccount_seller": "alice",
+  "subaccount_offer_price": "50.000 VIZ",
+  "subaccount_on_sale": true
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'set_subaccount_price_operation',
+    'value' => [
+        'account'                => 'alice',
+        'subaccount_seller'      => 'alice',
+        'subaccount_offer_price' => '50.000 VIZ',
+        'subaccount_on_sale'     => true,
+    ],
+];
+```
+
+### Checklist
+- [ ] `subaccount_offer_price.symbol` must be `VIZ`
+- [ ] `subaccount_on_sale: false` delists
+- [ ] Fee (`subaccount_on_sale_fee`) is charged when listing
+- [ ] Sign with `account`'s master key
+
+---
+
+## `buy_account_operation`
+
+**Type ID:** `56`
+**Required authority:** `active` of `buyer`
+
+Purchases an account that is listed for sale. All authorities are transferred to the buyer.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `buyer` | `account_name_type` | yes | Purchasing account |
+| `account` | `account_name_type` | yes | Account being purchased |
+| `account_offer_price` | `asset` (VIZ) | yes | Purchase price (must match listing) |
+| `account_authorities_key` | `public_key_type` | yes | New key set as all authorities of purchased account |
+| `tokens_to_shares` | `asset` (VIZ) | yes | Additional VIZ to convert to SHARES for bought account |
+
+### JSON Example
+
+```json
+[56, {
+  "buyer": "bob",
+  "account": "alice",
+  "account_offer_price": "1000.000 VIZ",
+  "account_authorities_key": "VIZ5newowner...",
+  "tokens_to_shares": "0.000 VIZ"
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'buy_account_operation',
+    'value' => [
+        'buyer'                   => 'bob',
+        'account'                 => 'alice',
+        'account_offer_price'     => '1000.000 VIZ',
+        'account_authorities_key' => 'VIZ5newowner...',
+        'tokens_to_shares'        => '0.000 VIZ',
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['buy_account', {
+    buyer: 'bob',
+    account: 'alice',
+    account_offer_price: '1000.000 VIZ',
+    account_authorities_key: 'VIZ5newowner...',
+    tokens_to_shares: '0.000 VIZ',
+}];
+```
+
+### Checklist
+- [ ] `account` must be currently listed for sale (`account_on_sale: true`)
+- [ ] `account_offer_price` must exactly match the listed price
+- [ ] `account_authorities_key` is set as master, active, regular, and memo key
+- [ ] `tokens_to_shares.symbol` must be `VIZ`
+- [ ] `tokens_to_shares.amount` >= 0 (can be 0)
+- [ ] Payment goes to `account_seller` as specified in the listing
+- [ ] Virtual `account_sale_operation` fires on successful purchase
+- [ ] Sign with `buyer`'s active key
+
+---
+
+## `target_account_sale_operation`
+
+**Type ID:** `61`
+**Required authority:** `master` of `account`
+
+Lists an account for sale to a specific buyer only (private/targeted sale). Added in HF11.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account` | `account_name_type` | yes | Account being listed |
+| `account_seller` | `account_name_type` | yes | Account to receive payment |
+| `target_buyer` | `account_name_type` | yes | Only this account can buy |
+| `account_offer_price` | `asset` (VIZ) | yes | Asking price |
+| `account_on_sale` | `bool` | yes | `true` to list, `false` to delist |
+
+### JSON Example
+
+```json
+[61, {
+  "account": "alice",
+  "account_seller": "alice",
+  "target_buyer": "charlie",
+  "account_offer_price": "500.000 VIZ",
+  "account_on_sale": true
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'target_account_sale_operation',
+    'value' => [
+        'account'             => 'alice',
+        'account_seller'      => 'alice',
+        'target_buyer'        => 'charlie',
+        'account_offer_price' => '500.000 VIZ',
+        'account_on_sale'     => true,
+    ],
+];
+```
+
+### Checklist
+- [ ] Only `target_buyer` can purchase this account via `buy_account_operation`
+- [ ] `account_offer_price.symbol` must be `VIZ`
+- [ ] `account_on_sale: false` delists the targeted sale
+- [ ] Sign with `account`'s master key

package/.qoder/docs/viz-cpp-node-docs/op-account.md

@@ -0,0 +1,199 @@
+# VIZ Blockchain — Account Operations
+
+Spec for implementing account-related operations in PHP/Node.js libraries.
+
+---
+
+## `account_create_operation`
+
+**Type ID:** `20`
+**Required authority:** `active` of `creator`
+
+Creates a new blockchain account.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `fee` | `asset` (VIZ) | yes | Creation fee (converted to SHARES for new account) |
+| `delegation` | `asset` (SHARES) | yes | Initial SHARES delegation to new account |
+| `creator` | `account_name_type` | yes | Account paying the fee and creating |
+| `new_account_name` | `account_name_type` | yes | Name for the new account |
+| `master` | `authority` | yes | Master authority for new account |
+| `active` | `authority` | yes | Active authority for new account |
+| `regular` | `authority` | yes | Regular authority for new account |
+| `memo_key` | `public_key_type` | yes | Memo public key |
+| `json_metadata` | `string` | yes | JSON metadata (may be empty `""`) |
+| `referrer` | `account_name_type` | yes | Referrer account name (may be empty `""`) |
+| `extensions` | `extensions_type` | yes | Always `[]` |
+
+### JSON Example
+
+```json
+[20, {
+  "fee": "1.000 VIZ",
+  "delegation": "10.000000 SHARES",
+  "creator": "alice",
+  "new_account_name": "bob",
+  "master": {
+    "weight_threshold": 1,
+    "account_auths": [],
+    "key_auths": [["VIZ5hqSa4NkEZGAMUpoH5EaEr64mBJuMcPpGjvk8qb7hcPFTbXSQ9", 1]]
+  },
+  "active": {
+    "weight_threshold": 1,
+    "account_auths": [],
+    "key_auths": [["VIZ5hqSa4NkEZGAMUpoH5EaEr64mBJuMcPpGjvk8qb7hcPFTbXSQ9", 1]]
+  },
+  "regular": {
+    "weight_threshold": 1,
+    "account_auths": [],
+    "key_auths": [["VIZ5hqSa4NkEZGAMUpoH5EaEr64mBJuMcPpGjvk8qb7hcPFTbXSQ9", 1]]
+  },
+  "memo_key": "VIZ5hqSa4NkEZGAMUpoH5EaEr64mBJuMcPpGjvk8qb7hcPFTbXSQ9",
+  "json_metadata": "",
+  "referrer": "",
+  "extensions": []
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'account_create_operation',
+    'value' => [
+        'fee'              => '1.000 VIZ',
+        'delegation'       => '10.000000 SHARES',
+        'creator'          => 'alice',
+        'new_account_name' => 'bob',
+        'master'  => ['weight_threshold' => 1, 'account_auths' => [], 'key_auths' => [['VIZ5hq...', 1]]],
+        'active'  => ['weight_threshold' => 1, 'account_auths' => [], 'key_auths' => [['VIZ5hq...', 1]]],
+        'regular' => ['weight_threshold' => 1, 'account_auths' => [], 'key_auths' => [['VIZ5hq...', 1]]],
+        'memo_key'      => 'VIZ5hq...',
+        'json_metadata' => '',
+        'referrer'      => '',
+        'extensions'    => [],
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['account_create', {
+    fee: '1.000 VIZ',
+    delegation: '10.000000 SHARES',
+    creator: 'alice',
+    new_account_name: 'bob',
+    master:  { weight_threshold: 1, account_auths: [], key_auths: [['VIZ5hq...', 1]] },
+    active:  { weight_threshold: 1, account_auths: [], key_auths: [['VIZ5hq...', 1]] },
+    regular: { weight_threshold: 1, account_auths: [], key_auths: [['VIZ5hq...', 1]] },
+    memo_key: 'VIZ5hq...',
+    json_metadata: '',
+    referrer: '',
+    extensions: [],
+}];
+```
+
+### Checklist
+- [ ] `fee.symbol` must be `VIZ`
+- [ ] `delegation.symbol` must be `SHARES`
+- [ ] `new_account_name` must pass `is_valid_create_account_name` validation
+- [ ] All three authorities must be provided (even if identical)
+- [ ] `memo_key` must be a valid VIZ public key
+- [ ] `fee` >= chain `account_creation_fee` property
+- [ ] Sign with `creator`'s active key
+
+---
+
+## `account_update_operation`
+
+**Type ID:** `5`
+**Required authority:** `master` of `account` (if changing master key), else `active`
+
+Updates account keys and metadata.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account` | `account_name_type` | yes | Account to update |
+| `master` | `optional<authority>` | no | New master authority (triggers master-auth requirement) |
+| `active` | `optional<authority>` | no | New active authority |
+| `regular` | `optional<authority>` | no | New regular authority |
+| `memo_key` | `public_key_type` | yes | New memo key |
+| `json_metadata` | `string` | yes | New JSON metadata |
+
+### JSON Example
+
+```json
+[5, {
+  "account": "alice",
+  "active": {
+    "weight_threshold": 1,
+    "account_auths": [],
+    "key_auths": [["VIZ5new...", 1]]
+  },
+  "memo_key": "VIZ5new...",
+  "json_metadata": "{\"profile\":\"updated\"}"
+}]
+```
+
+### Checklist
+- [ ] `master` field is **optional** — omit (or set to `null`) if not changing master key
+- [ ] If `master` is present → sign with current **master** key
+- [ ] If `master` is absent → sign with current **active** key
+- [ ] `memo_key` is always required (even if unchanged)
+
+---
+
+## `account_metadata_operation`
+
+**Type ID:** `21`
+**Required authority:** `regular` of `account`
+
+Updates only the account's JSON metadata. Cheaper in bandwidth than full `account_update`.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account` | `account_name_type` | yes | Account to update |
+| `json_metadata` | `string` | yes | New JSON metadata string |
+
+### JSON Example
+
+```json
+[21, {
+  "account": "alice",
+  "json_metadata": "{\"name\":\"Alice\",\"about\":\"Hello!\"}"
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'account_metadata_operation',
+    'value' => [
+        'account'       => 'alice',
+        'json_metadata' => json_encode(['name' => 'Alice', 'about' => 'Hello!']),
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['account_metadata', {
+    account: 'alice',
+    json_metadata: JSON.stringify({ name: 'Alice', about: 'Hello!' }),
+}];
+```
+
+### Checklist
+- [ ] `json_metadata` must be valid UTF-8
+- [ ] Max metadata size limited by bandwidth
+- [ ] Sign with `account`'s regular key
+- [ ] Faster/cheaper than `account_update` for metadata-only changes

package/.qoder/docs/viz-cpp-node-docs/op-award.md

@@ -0,0 +1,162 @@
+# VIZ Blockchain — Award Operations
+
+Spec for implementing award operations in PHP/Node.js libraries.
+
+Awards are the primary social reward mechanism in VIZ. An account spends "energy" to award SHARES directly to another account (and optionally to beneficiaries).
+
+---
+
+## `award_operation`
+
+**Type ID:** `47`
+**Required authority:** `regular` of `initiator`
+
+Awards SHARES to `receiver` from the reward pool, proportional to the initiator's energy expenditure and SHARES stake.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `initiator` | `account_name_type` | yes | Account giving the award |
+| `receiver` | `account_name_type` | yes | Account receiving the award |
+| `energy` | `uint16_t` | yes | Energy to spend (basis points: 1–10000) |
+| `custom_sequence` | `uint64_t` | yes | Application-defined sequence number |
+| `memo` | `string` | yes | Optional message/reason |
+| `beneficiaries` | `vector<beneficiary_route_type>` | yes | Optional beneficiaries receiving a share |
+
+### JSON Example
+
+```json
+[47, {
+  "initiator": "alice",
+  "receiver": "bob",
+  "energy": 1000,
+  "custom_sequence": 0,
+  "memo": "great article!",
+  "beneficiaries": []
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'award_operation',
+    'value' => [
+        'initiator'       => 'alice',
+        'receiver'        => 'bob',
+        'energy'          => 1000,
+        'custom_sequence' => 0,
+        'memo'            => 'great article!',
+        'beneficiaries'   => [],
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['award', {
+    initiator: 'alice',
+    receiver: 'bob',
+    energy: 1000,
+    custom_sequence: 0,
+    memo: 'great article!',
+    beneficiaries: [],
+}];
+```
+
+### Checklist
+- [ ] `energy` range: 1–10000 (1 = 0.01%, 10000 = 100%)
+- [ ] Energy regenerates at 100%/day (CHAIN_ENERGY_REGENERATION_SECONDS)
+- [ ] Beneficiary weights sum must be <= 10000 (100%)
+- [ ] Beneficiaries list must be sorted by account name ascending
+- [ ] If beneficiaries are present, `receiver` gets `(1 - sum_beneficiary_weights/10000)` share
+- [ ] `custom_sequence` is app-defined, can be 0
+- [ ] Sign with `initiator`'s regular key
+- [ ] Virtual `receive_award_operation` fires for `receiver`
+- [ ] Virtual `benefactor_award_operation` fires for each beneficiary
+
+---
+
+## `fixed_award_operation`
+
+**Type ID:** `60`
+**Required authority:** `regular` of `initiator`
+
+Awards a **fixed amount** of SHARES to `receiver`, spending energy proportionally based on the desired amount. Added in HF11.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `initiator` | `account_name_type` | yes | Account giving the award |
+| `receiver` | `account_name_type` | yes | Account receiving the award |
+| `reward_amount` | `asset` (SHARES) | yes | Fixed amount of SHARES to award |
+| `max_energy` | `uint16_t` | yes | Maximum energy to spend (0 = no limit) |
+| `custom_sequence` | `uint64_t` | yes | Application-defined sequence number |
+| `memo` | `string` | yes | Optional message/reason |
+| `beneficiaries` | `vector<beneficiary_route_type>` | yes | Optional beneficiaries |
+
+### JSON Example
+
+```json
+[60, {
+  "initiator": "alice",
+  "receiver": "bob",
+  "reward_amount": "10.000000 SHARES",
+  "max_energy": 5000,
+  "custom_sequence": 1,
+  "memo": "fixed reward",
+  "beneficiaries": [
+    {"account": "charlie", "weight": 1000}
+  ]
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'fixed_award_operation',
+    'value' => [
+        'initiator'       => 'alice',
+        'receiver'        => 'bob',
+        'reward_amount'   => '10.000000 SHARES',
+        'max_energy'      => 5000,
+        'custom_sequence' => 1,
+        'memo'            => 'fixed reward',
+        'beneficiaries'   => [
+            ['account' => 'charlie', 'weight' => 1000],
+        ],
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['fixed_award', {
+    initiator: 'alice',
+    receiver: 'bob',
+    reward_amount: '10.000000 SHARES',
+    max_energy: 5000,
+    custom_sequence: 1,
+    memo: 'fixed reward',
+    beneficiaries: [
+        { account: 'charlie', weight: 1000 },
+    ],
+}];
+```
+
+### Checklist
+- [ ] `reward_amount.symbol` must be `SHARES`
+- [ ] `reward_amount.amount` must be > 0
+- [ ] `max_energy` = 0 means no energy cap (spend as much as needed)
+- [ ] `max_energy` = 1–10000 limits maximum energy expenditure
+- [ ] Actual energy spent depends on initiator's stake and current reward pool
+- [ ] Beneficiary weights sum must be <= 10000 (100%)
+- [ ] Beneficiaries list must be sorted by account name ascending
+- [ ] Sign with `initiator`'s regular key
+- [ ] Virtual `receive_award_operation` fires for `receiver`
+- [ ] Virtual `benefactor_award_operation` fires for each beneficiary