viz-js-lib 0.11.0 → 0.12.4

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

@@ -0,0 +1,193 @@
+# VIZ Blockchain — Committee Operations
+
+Spec for implementing committee (worker proposal) operations in PHP/Node.js libraries.
+
+The committee mechanism allows community governance: anyone can create worker requests for funding, and VIZ SHARES holders vote to approve or reject them.
+
+---
+
+## `committee_worker_create_request_operation`
+
+**Type ID:** `35`
+**Required authority:** `regular` of `creator`
+
+Creates a new committee worker request (funding proposal).
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `creator` | `account_name_type` | yes | Account creating the request |
+| `url` | `string` | yes | URL describing the work/proposal |
+| `worker` | `account_name_type` | yes | Account that will receive the payout |
+| `required_amount_min` | `asset` (VIZ) | yes | Minimum acceptable payout |
+| `required_amount_max` | `asset` (VIZ) | yes | Maximum acceptable payout |
+| `duration` | `uint32_t` | yes | Request duration in seconds |
+
+### Constraints
+
+| Parameter | Value | Description |
+|---|---|---|
+| `COMMITTEE_MIN_DURATION` | 5 days | Minimum duration |
+| `COMMITTEE_MAX_DURATION` | 30 days | Maximum duration |
+| `COMMITTEE_MAX_REQUIRED_AMOUNT` | chain configured | Max tokens per request |
+
+### JSON Example
+
+```json
+[35, {
+  "creator": "alice",
+  "url": "https://alice.example.com/proposal",
+  "worker": "alice",
+  "required_amount_min": "100.000 VIZ",
+  "required_amount_max": "500.000 VIZ",
+  "duration": 604800
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'committee_worker_create_request_operation',
+    'value' => [
+        'creator'             => 'alice',
+        'url'                 => 'https://alice.example.com/proposal',
+        'worker'              => 'alice',
+        'required_amount_min' => '100.000 VIZ',
+        'required_amount_max' => '500.000 VIZ',
+        'duration'            => 604800,
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['committee_worker_create_request', {
+    creator: 'alice',
+    url: 'https://alice.example.com/proposal',
+    worker: 'alice',
+    required_amount_min: '100.000 VIZ',
+    required_amount_max: '500.000 VIZ',
+    duration: 604800,
+}];
+```
+
+### Checklist
+- [ ] `url.size()` must be > 0 and < 256 characters
+- [ ] `required_amount_min.symbol` must be `VIZ`
+- [ ] `required_amount_max.symbol` must be `VIZ`
+- [ ] `required_amount_min.amount` >= 0
+- [ ] `required_amount_max.amount` > `required_amount_min.amount`
+- [ ] `duration` in range `[COMMITTEE_MIN_DURATION, COMMITTEE_MAX_DURATION]`
+- [ ] Fee (`committee_create_request_fee`) is charged to creator
+- [ ] Sign with `creator`'s regular key
+
+---
+
+## `committee_worker_cancel_request_operation`
+
+**Type ID:** `36`
+**Required authority:** `regular` of `creator`
+
+Cancels an existing committee worker request before it expires.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `creator` | `account_name_type` | yes | Creator of the request |
+| `request_id` | `uint32_t` | yes | ID of the request to cancel |
+
+### JSON Example
+
+```json
+[36, {
+  "creator": "alice",
+  "request_id": 42
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'committee_worker_cancel_request_operation',
+    'value' => [
+        'creator'    => 'alice',
+        'request_id' => 42,
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['committee_worker_cancel_request', {
+    creator: 'alice',
+    request_id: 42,
+}];
+```
+
+### Checklist
+- [ ] Only the `creator` of the request can cancel it
+- [ ] `request_id` must refer to an existing active request
+- [ ] Sign with `creator`'s regular key
+
+---
+
+## `committee_vote_request_operation`
+
+**Type ID:** `37`
+**Required authority:** `regular` of `voter`
+
+Votes on a committee worker request. Positive = support, negative = oppose.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `voter` | `account_name_type` | yes | Account casting the vote |
+| `request_id` | `uint32_t` | yes | ID of the request to vote on |
+| `vote_percent` | `int16_t` | yes | Vote weight (-10000 to 10000) |
+
+### JSON Example
+
+```json
+[37, {
+  "voter": "bob",
+  "request_id": 42,
+  "vote_percent": 10000
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'committee_vote_request_operation',
+    'value' => [
+        'voter'        => 'bob',
+        'request_id'   => 42,
+        'vote_percent' => 10000,
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['committee_vote_request', {
+    voter: 'bob',
+    request_id: 42,
+    vote_percent: 10000,
+}];
+```
+
+### Checklist
+- [ ] `vote_percent` range: -10000 (strong oppose) to 10000 (strong support)
+- [ ] `vote_percent == 0` removes vote
+- [ ] Voting power weighted by voter's SHARES
+- [ ] Request is approved when net vote percent >= `committee_request_approve_min_percent`
+- [ ] Sign with `voter`'s regular key

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

@@ -0,0 +1,157 @@
+# VIZ Blockchain — Content & Custom Operations
+
+Spec for implementing content and custom operations in PHP/Node.js libraries.
+
+> **Note:** `vote_operation` (ID 0), `content_operation` (ID 1), and `delete_content_operation` (ID 9) are **deprecated**. They remain in the operation variant for historical compatibility but should not be used in new code. Shown here for completeness.
+
+---
+
+## `content_operation` *(deprecated)*
+
+**Type ID:** `1`
+**Required authority:** `regular` of `author`
+
+Creates or updates content (post or comment).
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `parent_author` | `account_name_type` | yes | Author of parent content (empty `""` for root post) |
+| `parent_permlink` | `string` | yes | Permlink of parent (category/tag for root posts) |
+| `author` | `account_name_type` | yes | Content author |
+| `permlink` | `string` | yes | Unique identifier per author |
+| `title` | `string` | yes | Post title |
+| `body` | `string` | yes | Post body (Markdown) |
+| `curation_percent` | `int16_t` | yes | Curation reward share in basis points (0–10000) |
+| `json_metadata` | `string` | yes | JSON metadata |
+| `extensions` | `content_extensions_type` | yes | Optional beneficiaries |
+
+### Beneficiaries Extension
+
+To add beneficiaries, add to `extensions`:
+```json
+[
+  [0, {
+    "beneficiaries": [
+      {"account": "bob", "weight": 2500}
+    ]
+  }]
+]
+```
+
+### Checklist
+- [ ] `permlink` must be unique per author
+- [ ] `parent_author == ""` → root post; otherwise comment
+- [ ] `curation_percent` range 0–10000 (must be within chain min/max)
+- [ ] Beneficiary weights sum must be <= 10000 (100%)
+- [ ] Beneficiaries list must be sorted by account name ascending
+- [ ] **Deprecated** — avoid creating new content with this operation
+
+---
+
+## `vote_operation` *(deprecated)*
+
+**Type ID:** `0`
+**Required authority:** `regular` of `voter`
+
+Casts a vote on content.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `voter` | `account_name_type` | yes | Voting account |
+| `author` | `account_name_type` | yes | Content author |
+| `permlink` | `string` | yes | Content permlink |
+| `weight` | `int16_t` | yes | Vote weight (-10000 to 10000) |
+
+### Checklist
+- [ ] `weight` > 0 → upvote; `weight` < 0 → flag/downvote
+- [ ] `weight == 0` → remove vote
+- [ ] Flag votes may cost extra energy (see `flag_energy_additional_cost` chain property)
+- [ ] **Deprecated** — avoid in new code
+
+---
+
+## `delete_content_operation` *(deprecated)*
+
+**Type ID:** `9`
+**Required authority:** `regular` of `author`
+
+Deletes a piece of content.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `author` | `account_name_type` | yes | Content author |
+| `permlink` | `string` | yes | Content permlink to delete |
+
+### Checklist
+- [ ] Content must have no pending payout to be deletable
+- [ ] **Deprecated** — avoid in new code
+
+---
+
+## `custom_operation`
+
+**Type ID:** `10`
+**Required authority:** `active` or `regular` of signers
+
+Posts arbitrary JSON data to the blockchain. Used by applications for custom logic/protocols.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `required_active_auths` | `flat_set<account_name_type>` | yes | Accounts requiring active auth |
+| `required_regular_auths` | `flat_set<account_name_type>` | yes | Accounts requiring regular auth |
+| `id` | `string` | yes | Application-defined ID (max 32 characters) |
+| `json` | `string` | yes | Valid UTF-8 JSON string |
+
+### JSON Example
+
+```json
+[10, {
+  "required_active_auths": [],
+  "required_regular_auths": ["alice"],
+  "id": "my_app",
+  "json": "{\"action\":\"follow\",\"target\":\"bob\"}"
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'custom_operation',
+    'value' => [
+        'required_active_auths'  => [],
+        'required_regular_auths' => ['alice'],
+        'id'                     => 'my_app',
+        'json'                   => json_encode(['action' => 'follow', 'target' => 'bob']),
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['custom', {
+    required_active_auths: [],
+    required_regular_auths: ['alice'],
+    id: 'my_app',
+    json: JSON.stringify({ action: 'follow', target: 'bob' }),
+}];
+```
+
+### Checklist
+- [ ] `id` must be <= 32 characters
+- [ ] `json` must be valid UTF-8 JSON
+- [ ] At least one of `required_active_auths` or `required_regular_auths` must be non-empty
+- [ ] `required_active_auths` entries → sign with those accounts' active keys
+- [ ] `required_regular_auths` entries → sign with those accounts' regular keys
+- [ ] Both `required_active_auths` and `required_regular_auths` may be populated simultaneously
+- [ ] Data operations may cost additional bandwidth (see `data_operations_cost_additional_bandwidth`)
+- [ ] `json` field is considered a "data operation" for bandwidth purposes

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

@@ -0,0 +1,224 @@
+# VIZ Blockchain — Escrow Operations
+
+Spec for implementing escrow-related operations in PHP/Node.js libraries.
+
+Escrow allows conditional transfers: funds are held in escrow until approved by both parties, or resolved by an agent in case of dispute.
+
+---
+
+## Escrow Flow
+
+```
+escrow_transfer  →  escrow_approve (by agent & to)
+                 →  [escrow_dispute]  →  escrow_release (by agent)
+                 →  escrow_release (by from or to)
+                 (expire) → expire_escrow_ratification_operation [virtual]
+```
+
+---
+
+## `escrow_transfer_operation`
+
+**Type ID:** `15`
+**Required authority:** `active` of `from`
+
+Creates an escrow transfer proposal. Funds leave `from` into escrow balance. Both `agent` and `to` must approve before funds can be released.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `from` | `account_name_type` | yes | Sender |
+| `to` | `account_name_type` | yes | Intended recipient |
+| `agent` | `account_name_type` | yes | Escrow agent (arbitrator) |
+| `escrow_id` | `uint32_t` | yes | Unique ID (chosen by sender), default 30 |
+| `token_amount` | `asset` (VIZ) | yes | Amount held in escrow |
+| `fee` | `asset` (VIZ) | yes | Agent fee (paid on approval) |
+| `ratification_deadline` | `time_point_sec` | yes | Deadline for agent & to to approve |
+| `escrow_expiration` | `time_point_sec` | yes | When escrow expires if not released |
+| `json_metadata` | `string` | yes | Optional metadata / terms |
+
+### JSON Example
+
+```json
+[15, {
+  "from": "alice",
+  "to": "bob",
+  "agent": "charlie",
+  "escrow_id": 1001,
+  "token_amount": "100.000 VIZ",
+  "fee": "1.000 VIZ",
+  "ratification_deadline": "2024-06-01T00:00:00",
+  "escrow_expiration": "2024-07-01T00:00:00",
+  "json_metadata": "{\"description\":\"payment for work\"}"
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'escrow_transfer_operation',
+    'value' => [
+        'from'                   => 'alice',
+        'to'                     => 'bob',
+        'agent'                  => 'charlie',
+        'escrow_id'              => 1001,
+        'token_amount'           => '100.000 VIZ',
+        'fee'                    => '1.000 VIZ',
+        'ratification_deadline'  => '2024-06-01T00:00:00',
+        'escrow_expiration'      => '2024-07-01T00:00:00',
+        'json_metadata'          => json_encode(['description' => 'payment for work']),
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['escrow_transfer', {
+    from: 'alice',
+    to: 'bob',
+    agent: 'charlie',
+    escrow_id: 1001,
+    token_amount: '100.000 VIZ',
+    fee: '1.000 VIZ',
+    ratification_deadline: '2024-06-01T00:00:00',
+    escrow_expiration: '2024-07-01T00:00:00',
+    json_metadata: JSON.stringify({ description: 'payment for work' }),
+}];
+```
+
+### Checklist
+- [ ] `token_amount.symbol` must be `VIZ`
+- [ ] `fee.symbol` must be `VIZ`
+- [ ] `token_amount.amount` must be > 0
+- [ ] `ratification_deadline` must be before `escrow_expiration`
+- [ ] Both deadlines must be in the future at time of broadcast
+- [ ] `escrow_id` must be unique for the `from` account
+- [ ] If not approved before `ratification_deadline`, virtual `expire_escrow_ratification_operation` fires and funds return
+- [ ] Sign with `from`'s active key
+
+---
+
+## `escrow_approve_operation`
+
+**Type ID:** `18`
+**Required authority:** `active` of `who`
+
+Approves (or rejects) an escrow transfer. Both `to` and `agent` must approve. Once approved, approval cannot be revoked.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `from` | `account_name_type` | yes | Original escrow sender |
+| `to` | `account_name_type` | yes | Original escrow recipient |
+| `agent` | `account_name_type` | yes | Escrow agent |
+| `who` | `account_name_type` | yes | Who is approving (`to` or `agent`) |
+| `escrow_id` | `uint32_t` | yes | Escrow ID |
+| `approve` | `bool` | yes | `true` to approve, `false` to reject |
+
+### JSON Example
+
+```json
+[18, {
+  "from": "alice",
+  "to": "bob",
+  "agent": "charlie",
+  "who": "bob",
+  "escrow_id": 1001,
+  "approve": true
+}]
+```
+
+### Checklist
+- [ ] `who` must be either `to` or `agent`
+- [ ] Once approved, cannot be undone
+- [ ] If `approve: false` → escrow is cancelled, funds returned to `from`
+- [ ] Escrow is only active once both `to` and `agent` have approved
+- [ ] Must be done before `ratification_deadline`
+- [ ] Sign with `who`'s active key
+
+---
+
+## `escrow_dispute_operation`
+
+**Type ID:** `16`
+**Required authority:** `active` of `who`
+
+Raises a dispute on an approved escrow. Once disputed, only the `agent` can release funds.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `from` | `account_name_type` | yes | Original escrow sender |
+| `to` | `account_name_type` | yes | Original escrow recipient |
+| `agent` | `account_name_type` | yes | Escrow agent |
+| `who` | `account_name_type` | yes | Who is raising the dispute (`from` or `to`) |
+| `escrow_id` | `uint32_t` | yes | Escrow ID |
+
+### JSON Example
+
+```json
+[16, {
+  "from": "alice",
+  "to": "bob",
+  "agent": "charlie",
+  "who": "alice",
+  "escrow_id": 1001
+}]
+```
+
+### Checklist
+- [ ] Dispute can only be raised on an **approved** escrow (both parties approved)
+- [ ] Dispute can be raised before or on the `escrow_expiration` deadline
+- [ ] `who` must be `from` or `to`
+- [ ] Once disputed, only `agent` can release via `escrow_release_operation`
+- [ ] Sign with `who`'s active key
+
+---
+
+## `escrow_release_operation`
+
+**Type ID:** `17`
+**Required authority:** `active` of `who`
+
+Releases escrow funds to `receiver`.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `from` | `account_name_type` | yes | Original escrow sender |
+| `to` | `account_name_type` | yes | Original escrow recipient |
+| `agent` | `account_name_type` | yes | Escrow agent |
+| `who` | `account_name_type` | yes | Account releasing funds |
+| `receiver` | `account_name_type` | yes | Account that receives the funds |
+| `escrow_id` | `uint32_t` | yes | Escrow ID |
+| `token_amount` | `asset` (VIZ) | yes | Amount to release |
+
+### JSON Example
+
+```json
+[17, {
+  "from": "alice",
+  "to": "bob",
+  "agent": "charlie",
+  "who": "alice",
+  "receiver": "bob",
+  "escrow_id": 1001,
+  "token_amount": "100.000 VIZ"
+}]
+```
+
+### Checklist
+- [ ] `token_amount.symbol` must be `VIZ`
+- [ ] Release permission rules:
+  - No dispute, before expiration: `from` can release to `to`; `to` can release to `from`
+  - No dispute, after expiration: either party can release to either party
+  - Disputed: only `agent` can release to either party
+- [ ] `receiver` must be `from` or `to`
+- [ ] `token_amount` can be partial — remaining stays in escrow
+- [ ] Sign with `who`'s active key