viz-js-lib 0.11.0 → 0.12.4

package/.qoder/docs/viz-cpp-node-docs/data-types.md

@@ -0,0 +1,322 @@
+# VIZ Blockchain — Common Data Types
+
+This document describes all shared data types used across VIZ protocol operations and virtual operations. These types appear as field types throughout operation structures.
+
+---
+
+## Primitive Types
+
+| C++ type | JSON representation | Description |
+|---|---|---|
+| `string` | `string` | UTF-8 string |
+| `bool` | `boolean` | true / false |
+| `uint8_t` | `integer` | Unsigned 8-bit integer |
+| `uint16_t` | `integer` | Unsigned 16-bit integer (0–65535) |
+| `int16_t` | `integer` | Signed 16-bit integer (-32768–32767) |
+| `uint32_t` | `integer` | Unsigned 32-bit integer |
+| `int32_t` | `integer` | Signed 32-bit integer |
+| `uint64_t` | `string` or `integer` | Unsigned 64-bit integer (use string in JS to avoid overflow) |
+| `int64_t` | `string` or `integer` | Signed 64-bit integer |
+| `share_type` | `integer` | Alias for `safe<int64_t>` — token satoshi amount |
+| `time_point_sec` | `string` | ISO 8601 UTC datetime: `"2024-01-15T12:00:00"` |
+
+---
+
+## `account_name_type`
+
+Fixed-length string (max 32 bytes). Must comply with domain-name rules:
+- Dot-separated labels, each label 3+ characters
+- Begins with a letter, ends with letter or digit
+- Only lowercase letters, digits, hyphens
+- Min length: `CHAIN_MIN_ACCOUNT_NAME_LENGTH` (2)
+- Max length: `CHAIN_MAX_ACCOUNT_NAME_LENGTH` (16)
+
+**JSON:** plain string, e.g. `"alice"`, `"alice.bob"`
+
+---
+
+## `public_key_type`
+
+A secp256k1 compressed public key encoded in base58check with `VIZ` prefix.
+
+**JSON:** string, e.g. `"VIZ5hqSa4NkEZGAMUpoH5EaEr64mBJuMcPpGjvk8qb7hcPFTbXSQ9"`
+
+### Checklist
+- [ ] Prefix must be `VIZ` (not `STM`, `GLS`, etc.)
+- [ ] 33-byte compressed public key + 4-byte checksum = 37 bytes base58-encoded
+- [ ] Validate checksum on deserialization
+
+---
+
+## `asset`
+
+Represents a token amount with its symbol.
+
+```
+{
+  "amount": integer,   // satoshi value (int64)
+  "symbol": integer    // asset_symbol_type (uint64)
+}
+```
+
+**However**, in JSON API the asset is typically serialized as a string:
+```
+"10.000 VIZ"
+"5.000000 SHARES"
+```
+
+### Asset Symbols
+
+| Symbol name | String | Decimals | Description |
+|---|---|---|---|
+| `TOKEN_SYMBOL` | `VIZ` | 3 | Main liquid token |
+| `SHARES_SYMBOL` | `SHARES` | 6 | Vesting shares (staked VIZ) |
+
+### Checklist
+- [ ] Parse/format amount with correct decimal places (VIZ=3, SHARES=6)
+- [ ] When constructing `asset` for operations, use the string format: `"10.000 VIZ"`
+- [ ] Validate symbol matches expected token type per operation field
+
+---
+
+## `authority`
+
+Multi-signature authority structure controlling an account's permission level.
+
+```json
+{
+  "weight_threshold": 1,
+  "account_auths": [
+    ["alice", 1]
+  ],
+  "key_auths": [
+    ["VIZ5hqSa4NkEZGAMUpoH5EaEr64mBJuMcPpGjvk8qb7hcPFTbXSQ9", 1]
+  ]
+}
+```
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `weight_threshold` | `uint32_t` | Minimum total weight required to satisfy authority |
+| `account_auths` | `[[account_name, weight], ...]` | Account-based signers |
+| `key_auths` | `[[public_key, weight], ...]` | Key-based signers |
+
+### Authority Levels
+
+| Level | Used for |
+|---|---|
+| `master` | Highest security — changing keys, account recovery |
+| `active` | Token operations — transfer, vesting, witness voting |
+| `regular` | Social operations — content, awards, committee voting |
+
+### Checklist
+- [ ] Sum of weights for satisfied keys/accounts must be >= `weight_threshold`
+- [ ] `account_auths` entries are `[string, uint16]` pairs
+- [ ] `key_auths` entries are `[string, uint16]` pairs (public key as VIZ-prefixed base58)
+- [ ] Empty authority = `{ "weight_threshold": 0, "account_auths": [], "key_auths": [] }`
+
+---
+
+## `beneficiary_route_type`
+
+Specifies a beneficiary account and their share weight for content rewards.
+
+```json
+{
+  "account": "alice",
+  "weight": 2500
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `account` | `account_name_type` | Beneficiary account name |
+| `weight` | `uint16_t` | Weight in basis points (100% = 10000) |
+
+### Checklist
+- [ ] Sum of all beneficiary weights must not exceed 10000 (100%)
+- [ ] Beneficiaries array must be sorted by account name (ascending)
+- [ ] Each beneficiary account must exist on-chain
+
+---
+
+## `extensions_type`
+
+Currently unused — always an empty array `[]`.
+
+```json
+"extensions": []
+```
+
+---
+
+## `versioned_chain_properties`
+
+A static variant holding one of the chain property versions. The variant is serialized as a 2-element array `[type_index, object]`.
+
+| Index | Type |
+|---|---|
+| 0 | `chain_properties_init` |
+| 1 | `chain_properties_hf4` |
+| 2 | `chain_properties_hf6` |
+| 3 | `chain_properties_hf9` |
+
+Example (hf9 = index 3):
+```json
+[3, {
+  "account_creation_fee": "1.000 VIZ",
+  "maximum_block_size": 65536,
+  "create_account_delegation_ratio": 10,
+  "create_account_delegation_time": 2592000,
+  "min_delegation": "1.000 VIZ",
+  "min_curation_percent": 0,
+  "max_curation_percent": 10000,
+  "bandwidth_reserve_percent": 1000,
+  "bandwidth_reserve_below": "1.000000 SHARES",
+  "flag_energy_additional_cost": 1000,
+  "vote_accounting_min_rshares": 0,
+  "committee_request_approve_min_percent": 1000,
+  "inflation_witness_percent": 2000,
+  "inflation_ratio_committee_vs_reward_fund": 1000,
+  "inflation_recalc_period": 28800,
+  "data_operations_cost_additional_bandwidth": 0,
+  "witness_miss_penalty_percent": 100,
+  "witness_miss_penalty_duration": 86400,
+  "create_invite_min_balance": "1.000 VIZ",
+  "committee_create_request_fee": "1.000 VIZ",
+  "create_paid_subscription_fee": "1.000 VIZ",
+  "account_on_sale_fee": "10.000 VIZ",
+  "subaccount_on_sale_fee": "1.000 VIZ",
+  "witness_declaration_fee": "1.000 VIZ",
+  "withdraw_intervals": 28
+}]
+```
+
+---
+
+## `chain_properties_init` Fields
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `account_creation_fee` | `asset` (VIZ) | `1.000 VIZ` | Fee to create a new account |
+| `maximum_block_size` | `uint32_t` | 131072 | Max block size in bytes |
+| `create_account_delegation_ratio` | `uint32_t` | 10 | Ratio of delegated SHARES on account creation |
+| `create_account_delegation_time` | `uint32_t` | 2592000 | Minimum delegation time (seconds) |
+| `min_delegation` | `asset` (VIZ) | `1.000 VIZ` | Minimum delegation amount |
+| `min_curation_percent` | `int16_t` | 0 | Min curation reward percent (basis points) |
+| `max_curation_percent` | `int16_t` | 10000 | Max curation reward percent (basis points) |
+| `bandwidth_reserve_percent` | `int16_t` | 1000 | % of bandwidth reserved for low-stake accounts |
+| `bandwidth_reserve_below` | `asset` (SHARES) | `1.000000 SHARES` | Threshold for bandwidth reserve |
+| `flag_energy_additional_cost` | `int16_t` | 1000 | Extra energy cost for flag/downvote |
+| `vote_accounting_min_rshares` | `uint32_t` | 0 | Min rshares for payout accounting |
+| `committee_request_approve_min_percent` | `int16_t` | 1000 | Min approval % for committee requests |
+
+## Additional fields in `chain_properties_hf4`
+
+| Field | Type | Description |
+|---|---|---|
+| `inflation_witness_percent` | `int16_t` | Witness reward % from block inflation |
+| `inflation_ratio_committee_vs_reward_fund` | `int16_t` | Ratio committee/reward fund |
+| `inflation_recalc_period` | `uint32_t` | Blocks per inflation recalc |
+
+## Additional fields in `chain_properties_hf6`
+
+| Field | Type | Description |
+|---|---|---|
+| `data_operations_cost_additional_bandwidth` | `uint32_t` | Extra bandwidth % for data operations |
+| `witness_miss_penalty_percent` | `int16_t` | Vote penalty % for missed block |
+| `witness_miss_penalty_duration` | `uint32_t` | Duration of miss penalty (seconds) |
+
+## Additional fields in `chain_properties_hf9`
+
+| Field | Type | Description |
+|---|---|---|
+| `create_invite_min_balance` | `asset` (VIZ) | Min balance to create invite |
+| `committee_create_request_fee` | `asset` (VIZ) | Fee to create committee request |
+| `create_paid_subscription_fee` | `asset` (VIZ) | Fee to create paid subscription |
+| `account_on_sale_fee` | `asset` (VIZ) | Fee to list account for sale |
+| `subaccount_on_sale_fee` | `asset` (VIZ) | Fee to list subaccounts for sale |
+| `witness_declaration_fee` | `asset` (VIZ) | Fee to declare as witness |
+| `withdraw_intervals` | `uint16_t` | Number of withdraw intervals |
+
+---
+
+## Operation Type Indices
+
+The `operation` is a `static_variant`. When serialized, it is a 2-element array: `[type_id, operation_object]`.
+
+### Regular Operations
+
+| ID | Operation Name |
+|---|---|
+| 0 | `vote_operation` *(deprecated)* |
+| 1 | `content_operation` *(deprecated)* |
+| 2 | `transfer_operation` |
+| 3 | `transfer_to_vesting_operation` |
+| 4 | `withdraw_vesting_operation` |
+| 5 | `account_update_operation` |
+| 6 | `witness_update_operation` |
+| 7 | `account_witness_vote_operation` |
+| 8 | `account_witness_proxy_operation` |
+| 9 | `delete_content_operation` *(deprecated)* |
+| 10 | `custom_operation` |
+| 11 | `set_withdraw_vesting_route_operation` |
+| 12 | `request_account_recovery_operation` |
+| 13 | `recover_account_operation` |
+| 14 | `change_recovery_account_operation` |
+| 15 | `escrow_transfer_operation` |
+| 16 | `escrow_dispute_operation` |
+| 17 | `escrow_release_operation` |
+| 18 | `escrow_approve_operation` |
+| 19 | `delegate_vesting_shares_operation` |
+| 20 | `account_create_operation` |
+| 21 | `account_metadata_operation` |
+| 22 | `proposal_create_operation` |
+| 23 | `proposal_update_operation` |
+| 24 | `proposal_delete_operation` |
+| 25 | `chain_properties_update_operation` |
+
+### Virtual Operations
+
+| ID | Operation Name |
+|---|---|
+| 26 | `author_reward_operation` |
+| 27 | `curation_reward_operation` |
+| 28 | `content_reward_operation` |
+| 29 | `fill_vesting_withdraw_operation` |
+| 30 | `shutdown_witness_operation` |
+| 31 | `hardfork_operation` |
+| 32 | `content_payout_update_operation` |
+| 33 | `content_benefactor_reward_operation` |
+| 34 | `return_vesting_delegation_operation` |
+| 35 | `committee_worker_create_request_operation` |
+| 36 | `committee_worker_cancel_request_operation` |
+| 37 | `committee_vote_request_operation` |
+| 38 | `committee_cancel_request_operation` *(virtual)* |
+| 39 | `committee_approve_request_operation` *(virtual)* |
+| 40 | `committee_payout_request_operation` *(virtual)* |
+| 41 | `committee_pay_request_operation` *(virtual)* |
+| 42 | `witness_reward_operation` *(virtual)* |
+| 43 | `create_invite_operation` |
+| 44 | `claim_invite_balance_operation` |
+| 45 | `invite_registration_operation` |
+| 46 | `versioned_chain_properties_update_operation` |
+| 47 | `award_operation` |
+| 48 | `receive_award_operation` *(virtual)* |
+| 49 | `benefactor_award_operation` *(virtual)* |
+| 50 | `set_paid_subscription_operation` |
+| 51 | `paid_subscribe_operation` |
+| 52 | `paid_subscription_action_operation` *(virtual)* |
+| 53 | `cancel_paid_subscription_operation` *(virtual)* |
+| 54 | `set_account_price_operation` |
+| 55 | `set_subaccount_price_operation` |
+| 56 | `buy_account_operation` |
+| 57 | `account_sale_operation` *(virtual)* |
+| 58 | `use_invite_balance_operation` |
+| 59 | `expire_escrow_ratification_operation` *(virtual)* |
+| 60 | `fixed_award_operation` |
+| 61 | `target_account_sale_operation` |
+| 62 | `bid_operation` *(virtual)* |
+| 63 | `outbid_operation` *(virtual)* |

package/.qoder/docs/viz-cpp-node-docs/index.md

@@ -0,0 +1,160 @@
+# VIZ Blockchain — Operations & Structures Spec
+
+Full specification and implementation checklist for building VIZ blockchain client libraries in PHP, Node.js, and other languages.
+
+---
+
+## Files in This Directory
+
+| File | Contents |
+|---|---|
+| [data-types.md](data-types.md) | Primitive types, `asset`, `authority`, `public_key_type`, operation type index |
+| [plugins.md](plugins.md) | All node plugins, dependencies, status, JSON-RPC method tables |
+| [op-account.md](op-account.md) | Account create, update, metadata operations |
+| [op-transfer-vesting.md](op-transfer-vesting.md) | Transfer, transfer_to_vesting, withdraw_vesting, set route, delegate |
+| [op-witness.md](op-witness.md) | Witness update, vote, proxy, chain properties |
+| [op-content.md](op-content.md) | Content, vote, delete_content (deprecated), custom |
+| [op-recovery.md](op-recovery.md) | Request/recover account, change recovery account |
+| [op-escrow.md](op-escrow.md) | Escrow transfer, approve, dispute, release |
+| [op-committee.md](op-committee.md) | Committee worker create/cancel request, vote |
+| [op-invite.md](op-invite.md) | Create invite, claim balance, register, use balance |
+| [op-award.md](op-award.md) | Award, fixed_award operations |
+| [op-subscription.md](op-subscription.md) | Set paid subscription, paid subscribe |
+| [op-account-market.md](op-account-market.md) | Set account/subaccount price, buy account, target sale |
+| [op-proposal.md](op-proposal.md) | Proposal create, update, delete (multi-sig) |
+| [virtual-operations.md](virtual-operations.md) | All virtual operations (read-only, blockchain-generated) |
+
+---
+
+## Quick Reference: All Operations
+
+### Regular Operations (user-broadcast)
+
+| ID | Name | Auth | Key File |
+|---|---|---|---|
+| 0 | `vote_operation` *(deprecated)* | regular | op-content.md |
+| 1 | `content_operation` *(deprecated)* | regular | op-content.md |
+| 2 | `transfer_operation` | active (VIZ) / master (SHARES) | op-transfer-vesting.md |
+| 3 | `transfer_to_vesting_operation` | active | op-transfer-vesting.md |
+| 4 | `withdraw_vesting_operation` | active | op-transfer-vesting.md |
+| 5 | `account_update_operation` | master/active | op-account.md |
+| 6 | `witness_update_operation` | active | op-witness.md |
+| 7 | `account_witness_vote_operation` | active | op-witness.md |
+| 8 | `account_witness_proxy_operation` | active | op-witness.md |
+| 9 | `delete_content_operation` *(deprecated)* | regular | op-content.md |
+| 10 | `custom_operation` | active/regular | op-content.md |
+| 11 | `set_withdraw_vesting_route_operation` | active | op-transfer-vesting.md |
+| 12 | `request_account_recovery_operation` | active | op-recovery.md |
+| 13 | `recover_account_operation` | master (×2) | op-recovery.md |
+| 14 | `change_recovery_account_operation` | master | op-recovery.md |
+| 15 | `escrow_transfer_operation` | active | op-escrow.md |
+| 16 | `escrow_dispute_operation` | active | op-escrow.md |
+| 17 | `escrow_release_operation` | active | op-escrow.md |
+| 18 | `escrow_approve_operation` | active | op-escrow.md |
+| 19 | `delegate_vesting_shares_operation` | active | op-transfer-vesting.md |
+| 20 | `account_create_operation` | active | op-account.md |
+| 21 | `account_metadata_operation` | regular | op-account.md |
+| 22 | `proposal_create_operation` | active | op-proposal.md |
+| 23 | `proposal_update_operation` | varies | op-proposal.md |
+| 24 | `proposal_delete_operation` | active | op-proposal.md |
+| 25 | `chain_properties_update_operation` | active | op-witness.md |
+| 35 | `committee_worker_create_request_operation` | regular | op-committee.md |
+| 36 | `committee_worker_cancel_request_operation` | regular | op-committee.md |
+| 37 | `committee_vote_request_operation` | regular | op-committee.md |
+| 43 | `create_invite_operation` | active | op-invite.md |
+| 44 | `claim_invite_balance_operation` | active | op-invite.md |
+| 45 | `invite_registration_operation` | active | op-invite.md |
+| 46 | `versioned_chain_properties_update_operation` | active | op-witness.md |
+| 47 | `award_operation` | regular | op-award.md |
+| 50 | `set_paid_subscription_operation` | active | op-subscription.md |
+| 51 | `paid_subscribe_operation` | active | op-subscription.md |
+| 54 | `set_account_price_operation` | master | op-account-market.md |
+| 55 | `set_subaccount_price_operation` | master | op-account-market.md |
+| 56 | `buy_account_operation` | active | op-account-market.md |
+| 58 | `use_invite_balance_operation` | active | op-invite.md |
+| 60 | `fixed_award_operation` | regular | op-award.md |
+| 61 | `target_account_sale_operation` | master | op-account-market.md |
+
+### Virtual Operations (read-only, not broadcastable)
+
+| ID | Name | Trigger | Key File |
+|---|---|---|---|
+| 26 | `author_reward_operation` | Content payout | virtual-operations.md |
+| 27 | `curation_reward_operation` | Content payout | virtual-operations.md |
+| 28 | `content_reward_operation` | Content payout | virtual-operations.md |
+| 29 | `fill_vesting_withdraw_operation` | Withdrawal interval | virtual-operations.md |
+| 30 | `shutdown_witness_operation` | Witness deactivated | virtual-operations.md |
+| 31 | `hardfork_operation` | Hardfork activation | virtual-operations.md |
+| 32 | `content_payout_update_operation` | Content payout update | virtual-operations.md |
+| 33 | `content_benefactor_reward_operation` | Content payout | virtual-operations.md |
+| 34 | `return_vesting_delegation_operation` | Delegation limbo ends | virtual-operations.md |
+| 38 | `committee_cancel_request_operation` | Request expires | virtual-operations.md |
+| 39 | `committee_approve_request_operation` | Request approved | virtual-operations.md |
+| 40 | `committee_payout_request_operation` | Payout processed | virtual-operations.md |
+| 41 | `committee_pay_request_operation` | Worker paid | virtual-operations.md |
+| 42 | `witness_reward_operation` | Block produced | virtual-operations.md |
+| 48 | `receive_award_operation` | Award given | virtual-operations.md |
+| 49 | `benefactor_award_operation` | Award with beneficiary | virtual-operations.md |
+| 52 | `paid_subscription_action_operation` | Subscription payment | virtual-operations.md |
+| 53 | `cancel_paid_subscription_operation` | Subscription ends | virtual-operations.md |
+| 57 | `account_sale_operation` | Account sold | virtual-operations.md |
+| 59 | `expire_escrow_ratification_operation` | Escrow deadline missed | virtual-operations.md |
+| 62 | `bid_operation` | Bid placed (HF11) | virtual-operations.md |
+| 63 | `outbid_operation` | Outbid (HF11) | virtual-operations.md |
+
+---
+
+## Library Implementation Master Checklist
+
+### Serialization
+- [ ] Operations serialized as `[type_id, object]` (2-element array)
+- [ ] `asset` values as string `"10.000 VIZ"` or as `{"amount": int, "symbol": int}` depending on API
+- [ ] `authority` serialized with `weight_threshold`, `account_auths`, `key_auths`
+- [ ] `public_key_type` as VIZ-prefixed base58check string
+- [ ] `time_point_sec` as ISO 8601 UTC string `"2024-01-15T12:00:00"` (no timezone suffix)
+- [ ] `optional<T>` as `null` when absent, or the value when present
+- [ ] `extensions_type` always `[]`
+- [ ] `flat_set` and `vector` as JSON arrays
+- [ ] `flat_map` as JSON array of `[key, value]` pairs
+
+### Transaction Construction
+- [ ] Fetch current block header for `ref_block_num` and `ref_block_prefix`
+- [ ] Set `expiration` = current time + desired TTL (max 60 seconds recommended)
+- [ ] Sign transaction with required keys (see each operation's authority requirements)
+- [ ] `ref_block_num` = `head_block_number & 0xFFFF`
+- [ ] `ref_block_prefix` = first 4 bytes (little-endian uint32) of `block_id` starting at byte 4
+- [ ] Chain ID must match target network (mainnet vs testnet)
+
+### Key Management
+- [ ] Private keys in WIF format (Base58Check with version byte 0x80)
+- [ ] Public keys in VIZ-prefixed compressed base58 format
+- [ ] Derive public key from private key using secp256k1
+- [ ] Sign: sha256d(chain_id + serialized_tx) → compact ECDSA signature
+
+### Energy System
+- [ ] Energy is in basis points (0–10000 = 0%–100%)
+- [ ] Energy regenerates at 100% per day (`CHAIN_ENERGY_REGENERATION_SECONDS = 86400`)
+- [ ] Formula: `current_energy = min(10000, last_energy + elapsed_seconds / REGEN_RATE)`
+- [ ] Spending 1000 energy (10%) costs proportional share of reward pool
+
+### Asset Formatting
+- [ ] VIZ: 3 decimal places, e.g. `"10.000 VIZ"`
+- [ ] SHARES: 6 decimal places, e.g. `"10.000000 SHARES"`
+- [ ] Parse: split on space, parse amount with decimal, check symbol
+
+### Account Name Validation
+- [ ] Length: 3–16 characters
+- [ ] Only lowercase letters, digits, hyphens, dots
+- [ ] Each segment (dot-separated) starts with letter, ends with letter/digit
+- [ ] Each segment >= 3 characters
+
+### Authority Validation
+- [ ] `weight_threshold` must be satisfiable (sum of weights >= threshold)
+- [ ] `key_auths` entries: `[public_key_string, uint16]`
+- [ ] `account_auths` entries: `[account_name_string, uint16]`
+
+### Bandwidth & Fees
+- [ ] Operations consume bandwidth proportional to their serialized byte size
+- [ ] Data operations (`custom_operation.json` etc.) have additional bandwidth cost
+- [ ] Account creation requires `fee` >= chain `account_creation_fee`
+- [ ] Committee/invite/subscription operations charge network fees from chain properties