viz-js-lib 0.11.0 → 0.12.4

package/.qoder/docs/viz-cpp-node-docs/virtual-operations.md

@@ -0,0 +1,513 @@
+# VIZ Blockchain — Virtual Operations
+
+Virtual operations are generated by the blockchain itself (not broadcast by users). They appear in operation history and can be tracked via account history or operation history APIs. They **cannot** be included in user transactions.
+
+---
+
+## `author_reward_operation`
+
+**Type ID:** `26`
+**Trigger:** Content payout
+
+Fired when an author receives their reward share from a content payout.
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `author` | `account_name_type` | Content author |
+| `permlink` | `string` | Content permlink |
+| `token_payout` | `asset` (VIZ) | Liquid token portion of payout |
+| `vesting_payout` | `asset` (SHARES) | SHARES portion of payout |
+
+### JSON Example
+
+```json
+[26, {
+  "author": "alice",
+  "permlink": "my-article",
+  "token_payout": "1.500 VIZ",
+  "vesting_payout": "0.000000 SHARES"
+}]
+```
+
+---
+
+## `curation_reward_operation`
+
+**Type ID:** `27`
+**Trigger:** Content payout
+
+Fired when a curator receives their curation reward.
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `curator` | `account_name_type` | Curator account |
+| `reward` | `asset` (SHARES) | Curation reward in SHARES |
+| `content_author` | `account_name_type` | Author of the curated content |
+| `content_permlink` | `string` | Permlink of the curated content |
+
+### JSON Example
+
+```json
+[27, {
+  "curator": "bob",
+  "reward": "0.500000 SHARES",
+  "content_author": "alice",
+  "content_permlink": "my-article"
+}]
+```
+
+---
+
+## `content_reward_operation`
+
+**Type ID:** `28`
+**Trigger:** Content payout
+
+Fired when a content post reaches its payout time.
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `author` | `account_name_type` | Content author |
+| `permlink` | `string` | Content permlink |
+| `payout` | `asset` | Total payout amount |
+
+---
+
+## `fill_vesting_withdraw_operation`
+
+**Type ID:** `29`
+**Trigger:** Each vesting withdrawal interval
+
+Fired each time a vesting withdrawal interval completes (weekly).
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `from_account` | `account_name_type` | Account withdrawing |
+| `to_account` | `account_name_type` | Account receiving (may differ via route) |
+| `withdrawn` | `asset` (SHARES) | SHARES amount withdrawn this interval |
+| `deposited` | `asset` (VIZ) | VIZ tokens deposited to `to_account` |
+
+### JSON Example
+
+```json
+[29, {
+  "from_account": "alice",
+  "to_account": "alice",
+  "withdrawn": "35.714285 SHARES",
+  "deposited": "10.000 VIZ"
+}]
+```
+
+### Checklist for listeners
+- [ ] Fired once per interval (default: every 1 day) for each active withdrawal
+- [ ] `to_account` may differ if `set_withdraw_vesting_route_operation` was used
+- [ ] If `auto_vest == true` in route, `deposited` will be SHARES, not VIZ
+
+---
+
+## `shutdown_witness_operation`
+
+**Type ID:** `30`
+**Trigger:** Witness removed due to vote weight falling below threshold
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `owner` | `account_name_type` | Witness that was shut down |
+
+---
+
+## `hardfork_operation`
+
+**Type ID:** `31`
+**Trigger:** Network hardfork activation
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `hardfork_id` | `uint32_t` | Hardfork number |
+
+---
+
+## `content_payout_update_operation`
+
+**Type ID:** `32`
+**Trigger:** Content payout update
+
+Fired when content payout is updated (e.g., after vote changes).
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `author` | `account_name_type` | Content author |
+| `permlink` | `string` | Content permlink |
+
+---
+
+## `content_benefactor_reward_operation`
+
+**Type ID:** `33`
+**Trigger:** Content payout
+
+Fired for each beneficiary when content is paid out.
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `benefactor` | `account_name_type` | Beneficiary account |
+| `author` | `account_name_type` | Content author |
+| `permlink` | `string` | Content permlink |
+| `reward` | `asset` | Beneficiary's reward share |
+
+---
+
+## `return_vesting_delegation_operation`
+
+**Type ID:** `34`
+**Trigger:** End of vesting delegation limbo period (1 week after delegation removal)
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `account` | `account_name_type` | Account receiving the returned SHARES |
+| `vesting_shares` | `asset` (SHARES) | SHARES returned from limbo |
+
+### JSON Example
+
+```json
+[34, {
+  "account": "alice",
+  "vesting_shares": "500.000000 SHARES"
+}]
+```
+
+---
+
+## `committee_cancel_request_operation`
+
+**Type ID:** `38`
+**Trigger:** Committee request expires without enough votes
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `request_id` | `uint32_t` | ID of cancelled request |
+
+---
+
+## `committee_approve_request_operation`
+
+**Type ID:** `39`
+**Trigger:** Committee request reaches required approval threshold
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `request_id` | `uint32_t` | ID of approved request |
+
+---
+
+## `committee_payout_request_operation`
+
+**Type ID:** `40`
+**Trigger:** Committee request payout is processed
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `request_id` | `uint32_t` | ID of paid request |
+
+---
+
+## `committee_pay_request_operation`
+
+**Type ID:** `41`
+**Trigger:** Worker receives payment from committee
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `worker` | `account_name_type` | Worker account receiving payment |
+| `request_id` | `uint32_t` | Committee request ID |
+| `tokens` | `asset` (VIZ) | Amount paid to worker |
+
+### JSON Example
+
+```json
+[41, {
+  "worker": "alice",
+  "request_id": 42,
+  "tokens": "250.000 VIZ"
+}]
+```
+
+---
+
+## `witness_reward_operation`
+
+**Type ID:** `42`
+**Trigger:** Block production reward
+
+Fired when a witness receives their block production reward.
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `witness` | `account_name_type` | Witness account |
+| `shares` | `asset` (SHARES) | Reward in SHARES |
+
+### JSON Example
+
+```json
+[42, {
+  "witness": "alice",
+  "shares": "1.234567 SHARES"
+}]
+```
+
+---
+
+## `receive_award_operation`
+
+**Type ID:** `48`
+**Trigger:** `award_operation` or `fixed_award_operation`
+
+Fired when the receiver gets their award.
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `initiator` | `account_name_type` | Account that gave the award |
+| `receiver` | `account_name_type` | Account that received the award |
+| `custom_sequence` | `uint64_t` | App-defined sequence from the award op |
+| `memo` | `string` | Memo from the award op |
+| `shares` | `asset` (SHARES) | SHARES received |
+
+### JSON Example
+
+```json
+[48, {
+  "initiator": "alice",
+  "receiver": "bob",
+  "custom_sequence": 0,
+  "memo": "great article!",
+  "shares": "5.000000 SHARES"
+}]
+```
+
+---
+
+## `benefactor_award_operation`
+
+**Type ID:** `49`
+**Trigger:** `award_operation` or `fixed_award_operation` with beneficiaries
+
+Fired for each beneficiary when an award is given.
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `initiator` | `account_name_type` | Account that gave the award |
+| `benefactor` | `account_name_type` | Beneficiary account |
+| `receiver` | `account_name_type` | Primary receiver of the award |
+| `custom_sequence` | `uint64_t` | App-defined sequence |
+| `memo` | `string` | Memo from the award op |
+| `shares` | `asset` (SHARES) | SHARES received by beneficiary |
+
+---
+
+## `paid_subscription_action_operation`
+
+**Type ID:** `52`
+**Trigger:** `paid_subscribe_operation` or auto-renewal payment
+
+Fired on each subscription payment.
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `subscriber` | `account_name_type` | Subscriber account |
+| `account` | `account_name_type` | Subscription provider |
+| `level` | `uint16_t` | Subscription level |
+| `amount` | `asset` (VIZ) | Payment amount |
+| `period` | `uint16_t` | Number of periods |
+| `summary_duration_sec` | `uint64_t` | Total subscription duration in seconds |
+| `summary_amount` | `asset` (VIZ) | Total amount paid to date |
+
+### JSON Example
+
+```json
+[52, {
+  "subscriber": "bob",
+  "account": "alice",
+  "level": 2,
+  "amount": "20.000 VIZ",
+  "period": 1,
+  "summary_duration_sec": 2592000,
+  "summary_amount": "20.000 VIZ"
+}]
+```
+
+---
+
+## `cancel_paid_subscription_operation`
+
+**Type ID:** `53`
+**Trigger:** Subscription expiry without renewal, or insufficient funds for auto-renewal
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `subscriber` | `account_name_type` | Subscriber account |
+| `account` | `account_name_type` | Subscription provider |
+
+---
+
+## `account_sale_operation`
+
+**Type ID:** `57`
+**Trigger:** `buy_account_operation` completes successfully
+
+Fired when an account is sold.
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `account` | `account_name_type` | Account that was sold |
+| `price` | `asset` (VIZ) | Sale price |
+| `buyer` | `account_name_type` | Buyer account |
+| `seller` | `account_name_type` | Seller (payment recipient) |
+
+### JSON Example
+
+```json
+[57, {
+  "account": "alice",
+  "price": "1000.000 VIZ",
+  "buyer": "bob",
+  "seller": "alice"
+}]
+```
+
+---
+
+## `expire_escrow_ratification_operation`
+
+**Type ID:** `59`
+**Trigger:** Escrow not ratified by both parties before `ratification_deadline`
+
+Fired when an escrow expires before being fully approved. Funds are returned to `from`.
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `from` | `account_name_type` | Original escrow sender |
+| `to` | `account_name_type` | Original intended recipient |
+| `agent` | `account_name_type` | Escrow agent |
+| `escrow_id` | `uint32_t` | Escrow ID |
+| `token_amount` | `asset` (VIZ) | Returned token amount |
+| `fee` | `asset` (VIZ) | Fee returned (agent not paid since not approved) |
+| `ratification_deadline` | `time_point_sec` | Deadline that was missed |
+
+---
+
+## `bid_operation`
+
+**Type ID:** `62`
+**Trigger:** New bid placed on an account for sale (HF11)
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `account` | `account_name_type` | Account being bid on |
+| `bidder` | `account_name_type` | Account placing the bid |
+| `bid` | `asset` (VIZ) | Bid amount |
+
+---
+
+## `outbid_operation`
+
+**Type ID:** `63`
+**Trigger:** A previous bidder is outbid (HF11)
+
+Fired when a previous bid is replaced by a higher bid. The outbid amount is returned.
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `account` | `account_name_type` | Account being bid on |
+| `bidder` | `account_name_type` | Account that was outbid |
+| `bid` | `asset` (VIZ) | Returned bid amount |
+
+---
+
+## Implementation Notes for Libraries
+
+### Listening to Virtual Operations
+
+```php
+// PHP: subscribe to account history
+$history = $api->get_account_history('alice', -1, 100);
+foreach ($history as [$index, $entry]) {
+    $opType = $entry['op'][0];
+    $opData = $entry['op'][1];
+    switch ($opType) {
+        case 'receive_award_operation':
+            // handle award received
+            break;
+        case 'fill_vesting_withdraw_operation':
+            // handle withdrawal
+            break;
+    }
+}
+```
+
+```js
+// Node.js: stream operations
+client.database.getAccountHistory('alice', -1, 100).then(history => {
+    for (const [index, entry] of history) {
+        const [opType, opData] = entry.op;
+        switch (opType) {
+            case 'receive_award':
+                // handle award
+                break;
+            case 'witness_reward':
+                // handle witness reward
+                break;
+        }
+    }
+});
+```
+
+### Checklist for Virtual Operation Handling
+- [ ] Virtual operations are read-only — never include them in transactions
+- [ ] Filter by operation type in account/operation history
+- [ ] Virtual ops share the same type variant as regular ops — use the same deserialization
+- [ ] `summary_duration_sec` in paid subscriptions may be 0 for first payment
+- [ ] Multiple virtual ops may fire in the same block for the same account