viz-js-lib 0.11.0 → 0.12.4

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

@@ -0,0 +1,146 @@
+# VIZ Blockchain — Paid Subscription Operations
+
+Spec for implementing paid subscription operations in PHP/Node.js libraries.
+
+Paid subscriptions allow accounts to offer tiered subscription services payable in VIZ tokens, with optional auto-renewal.
+
+---
+
+## `set_paid_subscription_operation`
+
+**Type ID:** `50`
+**Required authority:** `active` of `account`
+
+Creates or updates a paid subscription offering for an account. Subscribers can then subscribe via `paid_subscribe_operation`.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account` | `account_name_type` | yes | Account offering the subscription |
+| `url` | `string` | yes | URL with subscription details |
+| `levels` | `uint16_t` | yes | Number of subscription tiers (1–N) |
+| `amount` | `asset` (VIZ) | yes | Price per period per unit level |
+| `period` | `uint16_t` | yes | Subscription period in days |
+
+### JSON Example
+
+```json
+[50, {
+  "account": "alice",
+  "url": "https://alice.example.com/subscribe",
+  "levels": 3,
+  "amount": "10.000 VIZ",
+  "period": 30
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'set_paid_subscription_operation',
+    'value' => [
+        'account' => 'alice',
+        'url'     => 'https://alice.example.com/subscribe',
+        'levels'  => 3,
+        'amount'  => '10.000 VIZ',
+        'period'  => 30,
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['set_paid_subscription', {
+    account: 'alice',
+    url: 'https://alice.example.com/subscribe',
+    levels: 3,
+    amount: '10.000 VIZ',
+    period: 30,
+}];
+```
+
+### Checklist
+- [ ] `amount.symbol` must be `VIZ`
+- [ ] `amount.amount` must be > 0
+- [ ] `levels` must be >= 1
+- [ ] `period` must be >= 1 (days)
+- [ ] Fee (`create_paid_subscription_fee`) charged on first creation
+- [ ] Actual subscription cost = `amount * level` per period
+- [ ] Sign with `account`'s active key
+
+---
+
+## `paid_subscribe_operation`
+
+**Type ID:** `51`
+**Required authority:** `active` of `subscriber`
+
+Subscribes to or renews a paid subscription. Tokens are transferred from `subscriber` to `account`.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `subscriber` | `account_name_type` | yes | Subscribing account |
+| `account` | `account_name_type` | yes | Account offering the subscription |
+| `level` | `uint16_t` | yes | Subscription tier (1–max_levels) |
+| `amount` | `asset` (VIZ) | yes | Payment amount |
+| `period` | `uint16_t` | yes | Number of periods to subscribe |
+| `auto_renewal` | `bool` | yes | Whether to auto-renew |
+
+### JSON Example
+
+```json
+[51, {
+  "subscriber": "bob",
+  "account": "alice",
+  "level": 2,
+  "amount": "20.000 VIZ",
+  "period": 1,
+  "auto_renewal": true
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'paid_subscribe_operation',
+    'value' => [
+        'subscriber'   => 'bob',
+        'account'      => 'alice',
+        'level'        => 2,
+        'amount'       => '20.000 VIZ',
+        'period'       => 1,
+        'auto_renewal' => true,
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['paid_subscribe', {
+    subscriber: 'bob',
+    account: 'alice',
+    level: 2,
+    amount: '20.000 VIZ',
+    period: 1,
+    auto_renewal: true,
+}];
+```
+
+### Checklist
+- [ ] `amount.symbol` must be `VIZ`
+- [ ] `amount` must match `subscription_amount * level * period`
+- [ ] `level` must be in range [1, subscription.levels]
+- [ ] `period` >= 1
+- [ ] `auto_renewal: true` → tokens deducted automatically each period
+- [ ] `auto_renewal: false` → one-time subscription
+- [ ] If already subscribed: upgrading level requires matching payment for remaining time difference
+- [ ] Virtual `paid_subscription_action_operation` fires on payment
+- [ ] Virtual `cancel_paid_subscription_operation` fires on cancellation/expiry
+- [ ] Sign with `subscriber`'s active key

package/.qoder/docs/viz-cpp-node-docs/op-transfer-vesting.md

@@ -0,0 +1,224 @@
+# VIZ Blockchain — Transfer & Vesting Operations
+
+Spec for implementing transfer and vesting-related operations in PHP/Node.js libraries.
+
+---
+
+## `transfer_operation`
+
+**Type ID:** `2`
+**Required authority:** `active` of `from` (for VIZ tokens), `master` of `from` (for SHARES)
+
+Transfers tokens (VIZ or SHARES) from one account to another.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `from` | `account_name_type` | yes | Sending account |
+| `to` | `account_name_type` | yes | Receiving account |
+| `amount` | `asset` | yes | Amount to transfer (VIZ or SHARES) |
+| `memo` | `string` | yes | Optional memo (plain text or encrypted) |
+
+### JSON Example
+
+```json
+[2, {
+  "from": "alice",
+  "to": "bob",
+  "amount": "10.000 VIZ",
+  "memo": "payment for services"
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'transfer_operation',
+    'value' => [
+        'from'   => 'alice',
+        'to'     => 'bob',
+        'amount' => '10.000 VIZ',
+        'memo'   => 'payment for services',
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['transfer', {
+    from: 'alice',
+    to: 'bob',
+    amount: '10.000 VIZ',
+    memo: 'payment for services',
+}];
+```
+
+### Checklist
+- [ ] `amount.symbol` must be `VIZ` or `SHARES`
+- [ ] If `amount.symbol == SHARES` → sign with **master** key
+- [ ] If `amount.symbol == VIZ` → sign with **active** key
+- [ ] `amount.amount` must be > 0
+- [ ] `memo` may be empty string `""`
+- [ ] Encrypted memo format starts with `#` followed by base58 ciphertext
+
+---
+
+## `transfer_to_vesting_operation`
+
+**Type ID:** `3`
+**Required authority:** `active` of `from`
+
+Converts liquid VIZ tokens into SHARES (staking/vesting). Can vest into another account's balance.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `from` | `account_name_type` | yes | Account providing VIZ |
+| `to` | `account_name_type` | yes | Account receiving SHARES (same as `from` if empty) |
+| `amount` | `asset` (VIZ) | yes | Amount of VIZ to convert to SHARES |
+
+### JSON Example
+
+```json
+[3, {
+  "from": "alice",
+  "to": "alice",
+  "amount": "100.000 VIZ"
+}]
+```
+
+### Checklist
+- [ ] `amount.symbol` must be `VIZ`
+- [ ] `amount.amount` must be > 0
+- [ ] `to` can equal `from` (self-vesting) or be a different account
+- [ ] Sign with `from`'s active key
+
+---
+
+## `withdraw_vesting_operation`
+
+**Type ID:** `4`
+**Required authority:** `active` of `account`
+
+Initiates a vesting withdrawal — schedules gradual conversion of SHARES back to VIZ over multiple intervals.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account` | `account_name_type` | yes | Account initiating withdrawal |
+| `vesting_shares` | `asset` (SHARES) | yes | Total SHARES to withdraw (0 to cancel) |
+
+### JSON Example
+
+```json
+[4, {
+  "account": "alice",
+  "vesting_shares": "1000.000000 SHARES"
+}]
+```
+
+### Checklist
+- [ ] `vesting_shares.symbol` must be `SHARES`
+- [ ] Set `vesting_shares` to `"0.000000 SHARES"` to **cancel** an active withdrawal
+- [ ] Withdrawal is spread over `withdraw_intervals` intervals (default 28 days)
+- [ ] Each interval: `vesting_shares / withdraw_intervals` SHARES are withdrawn
+- [ ] Sign with `account`'s active key
+
+---
+
+## `set_withdraw_vesting_route_operation`
+
+**Type ID:** `11`
+**Required authority:** `active` of `from_account`
+
+Routes a percentage of vesting withdrawals to another account (optionally re-vesting immediately).
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `from_account` | `account_name_type` | yes | Account whose withdrawals are being routed |
+| `to_account` | `account_name_type` | yes | Account receiving routed funds |
+| `percent` | `uint16_t` | yes | Percentage to route (0–10000, basis points) |
+| `auto_vest` | `bool` | yes | If true, immediately re-vest the routed tokens |
+
+### JSON Example
+
+```json
+[11, {
+  "from_account": "alice",
+  "to_account": "bob",
+  "percent": 5000,
+  "auto_vest": false
+}]
+```
+
+### Checklist
+- [ ] `percent` range: 0 (remove route) to 10000 (100%)
+- [ ] Multiple routes allowed, but total percent across all routes must be <= 10000
+- [ ] `auto_vest: true` means Bob receives SHARES, not VIZ
+- [ ] Set `percent: 0` to delete the route to `to_account`
+- [ ] Sign with `from_account`'s active key
+
+---
+
+## `delegate_vesting_shares_operation`
+
+**Type ID:** `19`
+**Required authority:** `active` of `delegator`
+
+Delegates SHARES from one account to another. The delegator retains ownership but the delegatee gains bandwidth and voting power.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `delegator` | `account_name_type` | yes | Account delegating SHARES |
+| `delegatee` | `account_name_type` | yes | Account receiving delegation |
+| `vesting_shares` | `asset` (SHARES) | yes | Amount to delegate (0 removes delegation) |
+
+### JSON Example
+
+```json
+[19, {
+  "delegator": "alice",
+  "delegatee": "bob",
+  "vesting_shares": "500.000000 SHARES"
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'delegate_vesting_shares_operation',
+    'value' => [
+        'delegator'      => 'alice',
+        'delegatee'      => 'bob',
+        'vesting_shares' => '500.000000 SHARES',
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['delegate_vesting_shares', {
+    delegator: 'alice',
+    delegatee: 'bob',
+    vesting_shares: '500.000000 SHARES',
+}];
+```
+
+### Checklist
+- [ ] `vesting_shares.symbol` must be `SHARES`
+- [ ] Set `vesting_shares` to `"0.000000 SHARES"` to **remove** delegation
+- [ ] `vesting_shares` must be >= chain `min_delegation` property (unless 0)
+- [ ] When delegation is removed, SHARES enter a 1-week limbo period before returning
+- [ ] Virtual operation `return_vesting_delegation_operation` fires when limbo period ends
+- [ ] Sign with `delegator`'s active key

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

@@ -0,0 +1,252 @@
+# VIZ Blockchain — Witness Operations
+
+Spec for implementing witness-related operations in PHP/Node.js libraries.
+
+---
+
+## `witness_update_operation`
+
+**Type ID:** `6`
+**Required authority:** `active` of `owner`
+
+Registers or updates a witness. Setting `block_signing_key` to the null key removes the witness from block production contention.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `owner` | `account_name_type` | yes | Witness account name |
+| `url` | `string` | yes | Witness website or info URL |
+| `block_signing_key` | `public_key_type` | yes | Key used to sign blocks (set to null key to deactivate) |
+
+**Null key** (deactivate witness): `"VIZ1111111111111111111111111111111114T1Anm"`
+
+### JSON Example
+
+```json
+[6, {
+  "owner": "alice",
+  "url": "https://alice.example.com",
+  "block_signing_key": "VIZ5hqSa4NkEZGAMUpoH5EaEr64mBJuMcPpGjvk8qb7hcPFTbXSQ9"
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'witness_update_operation',
+    'value' => [
+        'owner'             => 'alice',
+        'url'               => 'https://alice.example.com',
+        'block_signing_key' => 'VIZ5hq...',
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['witness_update', {
+    owner: 'alice',
+    url: 'https://alice.example.com',
+    block_signing_key: 'VIZ5hq...',
+}];
+```
+
+### Checklist
+- [ ] `block_signing_key` must be a valid VIZ public key or the null key
+- [ ] Null key = `VIZ1111111111111111111111111111111114T1Anm` (deactivates witness)
+- [ ] `url` must be non-empty and < `CHAIN_MAX_URL_LENGTH` (256) bytes
+- [ ] Requires `witness_declaration_fee` paid to committee (see chain properties)
+- [ ] Sign with `owner`'s active key
+
+---
+
+## `chain_properties_update_operation`
+
+**Type ID:** `25`
+**Required authority:** `active` of `owner`
+
+Witness votes on base chain properties (`chain_properties_init` format only). Use `versioned_chain_properties_update_operation` for extended properties.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `owner` | `account_name_type` | yes | Witness account voting |
+| `props` | `chain_properties_init` | yes | Proposed chain properties |
+
+### JSON Example
+
+```json
+[25, {
+  "owner": "alice",
+  "props": {
+    "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
+  }
+}]
+```
+
+### Checklist
+- [ ] `account_creation_fee.symbol` must be `VIZ`
+- [ ] `min_delegation.symbol` must be `VIZ`
+- [ ] `bandwidth_reserve_below.symbol` must be `SHARES`
+- [ ] `min_curation_percent` <= `max_curation_percent`
+- [ ] All percent fields in basis points (0–10000)
+- [ ] Median of all active witness values is used as actual chain property
+
+---
+
+## `versioned_chain_properties_update_operation`
+
+**Type ID:** `46`
+**Required authority:** `active` of `owner`
+
+Witness votes on versioned chain properties (supports all hardfork extensions).
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `owner` | `account_name_type` | yes | Witness account voting |
+| `props` | `versioned_chain_properties` | yes | Versioned props variant |
+
+### JSON Example (using hf9 = index 3)
+
+```json
+[46, {
+  "owner": "alice",
+  "props": [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
+  }]
+}]
+```
+
+### Checklist
+- [ ] `props` is serialized as a static_variant: `[index, object]`
+- [ ] Use index `3` for `chain_properties_hf9` (current latest)
+- [ ] See `data-types.md` for full field list per version
+
+---
+
+## `account_witness_vote_operation`
+
+**Type ID:** `7`
+**Required authority:** `active` of `account`
+
+Votes for or against a witness to be included in block production.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account` | `account_name_type` | yes | Voting account |
+| `witness` | `account_name_type` | yes | Witness to vote for/against |
+| `approve` | `bool` | yes | `true` to add vote, `false` to remove vote |
+
+### JSON Example
+
+```json
+[7, {
+  "account": "alice",
+  "witness": "bob",
+  "approve": true
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'account_witness_vote_operation',
+    'value' => [
+        'account' => 'alice',
+        'witness' => 'bob',
+        'approve' => true,
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['account_witness_vote', {
+    account: 'alice',
+    witness: 'bob',
+    approve: true,
+}];
+```
+
+### Checklist
+- [ ] Account must have SHARES to have meaningful voting weight
+- [ ] `approve: false` removes a previously cast vote
+- [ ] Top 21 witnesses by vote weight produce blocks
+- [ ] Sign with `account`'s active key
+
+---
+
+## `account_witness_proxy_operation`
+
+**Type ID:** `8`
+**Required authority:** `active` of `account`
+
+Assigns a proxy account for witness voting. All existing votes are removed when a proxy is set.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account` | `account_name_type` | yes | Account setting the proxy |
+| `proxy` | `account_name_type` | yes | Proxy account (empty string `""` to remove proxy) |
+
+### JSON Example
+
+```json
+[8, {
+  "account": "alice",
+  "proxy": "bob"
+}]
+```
+
+### Checklist
+- [ ] Setting `proxy` to `""` (empty string) removes the proxy
+- [ ] Cannot set proxy to self
+- [ ] Proxy chains are resolved (A→B→C); max depth is limited
+- [ ] Setting a proxy removes all direct witness votes
+- [ ] Sign with `account`'s active key