viz-js-lib 0.11.0 → 0.12.4

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

@@ -0,0 +1,219 @@
+# VIZ Blockchain — Invite Operations
+
+Spec for implementing invite-related operations in PHP/Node.js libraries.
+
+Invites allow existing VIZ users to onboard new users without requiring them to have an existing account. An invite is a one-time-use key with a VIZ balance.
+
+---
+
+## `create_invite_operation`
+
+**Type ID:** `43`
+**Required authority:** `active` of `creator`
+
+Creates an invite link by generating a key and funding it with VIZ tokens.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `creator` | `account_name_type` | yes | Account creating the invite |
+| `balance` | `asset` (VIZ) | yes | Amount of VIZ to lock in the invite |
+| `invite_key` | `public_key_type` | yes | Public key of the invite (secret = private key) |
+
+### JSON Example
+
+```json
+[43, {
+  "creator": "alice",
+  "balance": "5.000 VIZ",
+  "invite_key": "VIZ5invite..."
+}]
+```
+
+### PHP Example
+
+```php
+// Generate invite key pair first:
+// $privateKey = '...' // keep secret, share as invite link
+// $publicKey  = derived from privateKey
+
+$op = [
+    'type' => 'create_invite_operation',
+    'value' => [
+        'creator'    => 'alice',
+        'balance'    => '5.000 VIZ',
+        'invite_key' => 'VIZ5invite...',
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['create_invite', {
+    creator: 'alice',
+    balance: '5.000 VIZ',
+    invite_key: 'VIZ5invite...',
+}];
+```
+
+### Checklist
+- [ ] `balance.symbol` must be `VIZ`
+- [ ] `balance.amount` >= chain `create_invite_min_balance` property
+- [ ] Generate a random secp256k1 key pair for the invite
+- [ ] Private key = invite secret (share in invite link)
+- [ ] Public key = `invite_key` field
+- [ ] Sign with `creator`'s active key
+
+---
+
+## `claim_invite_balance_operation`
+
+**Type ID:** `44`
+**Required authority:** `active` of `initiator`
+
+Claims the VIZ balance from an invite, transferring it to `receiver`. The invite is consumed.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `initiator` | `account_name_type` | yes | Account claiming the invite |
+| `receiver` | `account_name_type` | yes | Account to receive the VIZ balance |
+| `invite_secret` | `string` | yes | WIF private key of the invite |
+
+### JSON Example
+
+```json
+[44, {
+  "initiator": "bob",
+  "receiver": "bob",
+  "invite_secret": "5Ky1MXn..."
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'claim_invite_balance_operation',
+    'value' => [
+        'initiator'     => 'bob',
+        'receiver'      => 'bob',
+        'invite_secret' => '5Ky1MXn...',
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['claim_invite_balance', {
+    initiator: 'bob',
+    receiver: 'bob',
+    invite_secret: '5Ky1MXn...',
+}];
+```
+
+### Checklist
+- [ ] `invite_secret` is the WIF (Wallet Import Format) private key of the invite
+- [ ] `initiator` must be an existing account
+- [ ] `receiver` may differ from `initiator` (can redirect balance to another account)
+- [ ] Invite is consumed after claiming — cannot be reused
+- [ ] Sign with `initiator`'s active key
+
+---
+
+## `invite_registration_operation`
+
+**Type ID:** `45`
+**Required authority:** `active` of `initiator`
+
+Uses an invite to create a new account. The invite balance is used to fund the new account.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `initiator` | `account_name_type` | yes | Existing account triggering registration |
+| `new_account_name` | `account_name_type` | yes | Name for the new account |
+| `invite_secret` | `string` | yes | WIF private key of the invite |
+| `new_account_key` | `public_key_type` | yes | Master/active/regular/memo key for new account |
+
+### JSON Example
+
+```json
+[45, {
+  "initiator": "bob",
+  "new_account_name": "carol",
+  "invite_secret": "5Ky1MXn...",
+  "new_account_key": "VIZ5newacct..."
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'invite_registration_operation',
+    'value' => [
+        'initiator'        => 'bob',
+        'new_account_name' => 'carol',
+        'invite_secret'    => '5Ky1MXn...',
+        'new_account_key'  => 'VIZ5newacct...',
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['invite_registration', {
+    initiator: 'bob',
+    new_account_name: 'carol',
+    invite_secret: '5Ky1MXn...',
+    new_account_key: 'VIZ5newacct...',
+}];
+```
+
+### Checklist
+- [ ] `invite_secret` is the WIF private key of the invite
+- [ ] `new_account_name` must pass account name validation
+- [ ] `new_account_key` is set as all four keys (master, active, regular, memo) for the new account
+- [ ] Invite balance is converted to SHARES for the new account
+- [ ] Invite is consumed after use
+- [ ] Sign with `initiator`'s active key
+
+---
+
+## `use_invite_balance_operation`
+
+**Type ID:** `58`
+**Required authority:** `active` of `initiator`
+
+Alternative to `claim_invite_balance_operation` — transfers invite balance to receiver. The difference from `claim_invite_balance_operation` is that this one may convert balance to SHARES.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `initiator` | `account_name_type` | yes | Account using the invite |
+| `receiver` | `account_name_type` | yes | Account receiving the balance |
+| `invite_secret` | `string` | yes | WIF private key of the invite |
+
+### JSON Example
+
+```json
+[58, {
+  "initiator": "bob",
+  "receiver": "bob",
+  "invite_secret": "5Ky1MXn..."
+}]
+```
+
+### Checklist
+- [ ] `invite_secret` is the WIF private key
+- [ ] `receiver` must be an existing account
+- [ ] Invite is consumed after use
+- [ ] Sign with `initiator`'s active key

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

@@ -0,0 +1,229 @@
+# VIZ Blockchain — Proposal Operations
+
+Spec for implementing multi-signature proposal operations in PHP/Node.js libraries.
+
+Proposals allow a group of accounts to jointly approve and execute a set of operations. Any account can create a proposal; signatories approve via `proposal_update_operation`.
+
+---
+
+## `proposal_create_operation`
+
+**Type ID:** `22`
+**Required authority:** `active` of `author`
+
+Creates a transaction proposal containing one or more operations that require multi-sig approval.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `author` | `account_name_type` | yes | Account creating the proposal |
+| `title` | `string` | yes | Unique title per author (used as proposal ID) |
+| `memo` | `string` | yes | Description of the proposal |
+| `expiration_time` | `time_point_sec` | yes | Proposal expiration time |
+| `proposed_operations` | `vector<operation_wrapper>` | yes | Operations in the proposal |
+| `review_period_time` | `optional<time_point_sec>` | no | Optional review period |
+| `extensions` | `extensions_type` | yes | Always `[]` |
+
+### `operation_wrapper`
+
+Each entry in `proposed_operations` is an `operation_wrapper`:
+```json
+{"op": [type_id, operation_object]}
+```
+
+### JSON Example
+
+```json
+[22, {
+  "author": "alice",
+  "title": "transfer-proposal-001",
+  "memo": "Joint transfer to shared fund",
+  "expiration_time": "2024-12-31T23:59:59",
+  "proposed_operations": [
+    {
+      "op": [2, {
+        "from": "multisig-wallet",
+        "to": "fund",
+        "amount": "1000.000 VIZ",
+        "memo": ""
+      }]
+    }
+  ],
+  "review_period_time": null,
+  "extensions": []
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'proposal_create_operation',
+    'value' => [
+        'author'          => 'alice',
+        'title'           => 'transfer-proposal-001',
+        'memo'            => 'Joint transfer to shared fund',
+        'expiration_time' => '2024-12-31T23:59:59',
+        'proposed_operations' => [
+            ['op' => [2, [
+                'from'   => 'multisig-wallet',
+                'to'     => 'fund',
+                'amount' => '1000.000 VIZ',
+                'memo'   => '',
+            ]]],
+        ],
+        'review_period_time' => null,
+        'extensions'         => [],
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['proposal_create', {
+    author: 'alice',
+    title: 'transfer-proposal-001',
+    memo: 'Joint transfer to shared fund',
+    expiration_time: '2024-12-31T23:59:59',
+    proposed_operations: [
+        { op: ['transfer', {
+            from: 'multisig-wallet',
+            to: 'fund',
+            amount: '1000.000 VIZ',
+            memo: '',
+        }] },
+    ],
+    review_period_time: null,
+    extensions: [],
+}];
+```
+
+### Checklist
+- [ ] `title` must be unique per `author` (together they form the proposal ID)
+- [ ] `expiration_time` must be in the future
+- [ ] `review_period_time` if set, must be before `expiration_time`
+- [ ] `proposed_operations` may contain multiple operations
+- [ ] Operations inside a proposal follow the same rules as normal operations
+- [ ] Sign with `author`'s active key
+
+---
+
+## `proposal_update_operation`
+
+**Type ID:** `23`
+**Required authority:** Depends on which approval sets are modified
+
+Adds or removes approvals from a proposal. Proposal executes automatically when enough approvals are collected.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `author` | `account_name_type` | yes | Author of the proposal |
+| `title` | `string` | yes | Title of the proposal |
+| `active_approvals_to_add` | `flat_set<account_name_type>` | yes | Accounts adding active approval |
+| `active_approvals_to_remove` | `flat_set<account_name_type>` | yes | Accounts removing active approval |
+| `master_approvals_to_add` | `flat_set<account_name_type>` | yes | Accounts adding master approval |
+| `master_approvals_to_remove` | `flat_set<account_name_type>` | yes | Accounts removing master approval |
+| `regular_approvals_to_add` | `flat_set<account_name_type>` | yes | Accounts adding regular approval |
+| `regular_approvals_to_remove` | `flat_set<account_name_type>` | yes | Accounts removing regular approval |
+| `key_approvals_to_add` | `flat_set<public_key_type>` | yes | Keys adding approval |
+| `key_approvals_to_remove` | `flat_set<public_key_type>` | yes | Keys removing approval |
+| `extensions` | `extensions_type` | yes | Always `[]` |
+
+### JSON Example
+
+```json
+[23, {
+  "author": "alice",
+  "title": "transfer-proposal-001",
+  "active_approvals_to_add": ["bob"],
+  "active_approvals_to_remove": [],
+  "master_approvals_to_add": [],
+  "master_approvals_to_remove": [],
+  "regular_approvals_to_add": [],
+  "regular_approvals_to_remove": [],
+  "key_approvals_to_add": [],
+  "key_approvals_to_remove": [],
+  "extensions": []
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'proposal_update_operation',
+    'value' => [
+        'author'                    => 'alice',
+        'title'                     => 'transfer-proposal-001',
+        'active_approvals_to_add'   => ['bob'],
+        'active_approvals_to_remove'=> [],
+        'master_approvals_to_add'   => [],
+        'master_approvals_to_remove'=> [],
+        'regular_approvals_to_add'  => [],
+        'regular_approvals_to_remove'=> [],
+        'key_approvals_to_add'      => [],
+        'key_approvals_to_remove'   => [],
+        'extensions'                => [],
+    ],
+];
+```
+
+### Checklist
+- [ ] Transaction must be signed by keys satisfying the authorities being added/removed
+- [ ] If proposal requires only active authority, do NOT add master authority
+- [ ] If both master and active are required, only master can approve
+- [ ] Proposal executes automatically when approval threshold is reached
+- [ ] After successful execution, proposal is resolved and further updates are rejected
+- [ ] All `*_to_add` and `*_to_remove` arrays default to `[]` if not needed
+
+---
+
+## `proposal_delete_operation`
+
+**Type ID:** `24`
+**Required authority:** `active` of `requester`
+
+Vetoes and permanently deletes a proposal. Can be done by any required authority.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `author` | `account_name_type` | yes | Author of the proposal |
+| `title` | `string` | yes | Title of the proposal |
+| `requester` | `account_name_type` | yes | Account requesting deletion |
+| `extensions` | `extensions_type` | yes | Always `[]` |
+
+### JSON Example
+
+```json
+[24, {
+  "author": "alice",
+  "title": "transfer-proposal-001",
+  "requester": "bob",
+  "extensions": []
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'proposal_delete_operation',
+    'value' => [
+        'author'     => 'alice',
+        'title'      => 'transfer-proposal-001',
+        'requester'  => 'bob',
+        'extensions' => [],
+    ],
+];
+```
+
+### Checklist
+- [ ] `requester` must be a required authority on the proposal
+- [ ] Permanently removes the proposal — cannot be undone
+- [ ] Sign with `requester`'s active key

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

@@ -0,0 +1,188 @@
+# VIZ Blockchain — Account Recovery Operations
+
+Spec for implementing account recovery operations in PHP/Node.js libraries.
+
+The recovery mechanism allows a trusted recovery account to help restore access to a compromised account using a previous valid master authority.
+
+---
+
+## Recovery Flow
+
+```
+request_account_recovery  →  recover_account  (within 24 hours)
+change_recovery_account   (30-day delay)
+```
+
+---
+
+## `request_account_recovery_operation`
+
+**Type ID:** `12`
+**Required authority:** `active` of `recovery_account`
+
+Initiates an account recovery request. The recovery account proposes a new master authority for the compromised account. The account holder has 24 hours to confirm.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `recovery_account` | `account_name_type` | yes | The trusted recovery account |
+| `account_to_recover` | `account_name_type` | yes | Compromised account to recover |
+| `new_master_authority` | `authority` | yes | The new master authority to assign |
+| `extensions` | `extensions_type` | yes | Always `[]` |
+
+### JSON Example
+
+```json
+[12, {
+  "recovery_account": "recover-service",
+  "account_to_recover": "alice",
+  "new_master_authority": {
+    "weight_threshold": 1,
+    "account_auths": [],
+    "key_auths": [["VIZ5newkey...", 1]]
+  },
+  "extensions": []
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'request_account_recovery_operation',
+    'value' => [
+        'recovery_account'    => 'recover-service',
+        'account_to_recover'  => 'alice',
+        'new_master_authority' => [
+            'weight_threshold' => 1,
+            'account_auths'    => [],
+            'key_auths'        => [['VIZ5newkey...', 1]],
+        ],
+        'extensions' => [],
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['request_account_recovery', {
+    recovery_account: 'recover-service',
+    account_to_recover: 'alice',
+    new_master_authority: {
+        weight_threshold: 1,
+        account_auths: [],
+        key_auths: [['VIZ5newkey...', 1]],
+    },
+    extensions: [],
+}];
+```
+
+### Checklist
+- [ ] Only the listed recovery account of `account_to_recover` can send this
+- [ ] Only one active recovery request per account at any time
+- [ ] Sending again updates the request to a new authority and resets the 24h timer
+- [ ] To cancel: set `new_master_authority.weight_threshold` to `0`
+- [ ] Sign with `recovery_account`'s active key
+
+---
+
+## `recover_account_operation`
+
+**Type ID:** `13`
+**Required authority:** Both `new_master_authority` AND `recent_master_authority` signatures
+
+Confirms account recovery. The account holder proves past ownership via a recent master authority, and takes the new master authority.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account_to_recover` | `account_name_type` | yes | Account being recovered |
+| `new_master_authority` | `authority` | yes | New master authority (must match recovery request) |
+| `recent_master_authority` | `authority` | yes | A previous valid master authority (within last 30 days) |
+| `extensions` | `extensions_type` | yes | Always `[]` |
+
+### JSON Example
+
+```json
+[13, {
+  "account_to_recover": "alice",
+  "new_master_authority": {
+    "weight_threshold": 1,
+    "account_auths": [],
+    "key_auths": [["VIZ5newkey...", 1]]
+  },
+  "recent_master_authority": {
+    "weight_threshold": 1,
+    "account_auths": [],
+    "key_auths": [["VIZ5oldkey...", 1]]
+  },
+  "extensions": []
+}]
+```
+
+### Checklist
+- [ ] Must be broadcast within 24 hours of the recovery request
+- [ ] `new_master_authority` must exactly match the one in the recovery request
+- [ ] `recent_master_authority` must have been valid in the past 30 days
+- [ ] Transaction must be signed by keys satisfying **both** authorities
+- [ ] After recovery, the old master key is invalidated
+
+---
+
+## `change_recovery_account_operation`
+
+**Type ID:** `14`
+**Required authority:** `master` of `account_to_recover`
+
+Changes the recovery account for an account. Takes effect after a 30-day delay.
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account_to_recover` | `account_name_type` | yes | Account changing its recovery account |
+| `new_recovery_account` | `account_name_type` | yes | New recovery account name |
+| `extensions` | `extensions_type` | yes | Always `[]` |
+
+### JSON Example
+
+```json
+[14, {
+  "account_to_recover": "alice",
+  "new_recovery_account": "new-recovery-service",
+  "extensions": []
+}]
+```
+
+### PHP Example
+
+```php
+$op = [
+    'type' => 'change_recovery_account_operation',
+    'value' => [
+        'account_to_recover'  => 'alice',
+        'new_recovery_account' => 'new-recovery-service',
+        'extensions'          => [],
+    ],
+];
+```
+
+### Node.js Example
+
+```js
+const op = ['change_recovery_account', {
+    account_to_recover: 'alice',
+    new_recovery_account: 'new-recovery-service',
+    extensions: [],
+}];
+```
+
+### Checklist
+- [ ] 30-day delay between submitting the change and it taking effect
+- [ ] This prevents attackers from changing the recovery account during an active attack
+- [ ] `new_recovery_account` must be an existing account
+- [ ] If `new_recovery_account == ""`, top-voted witness becomes recovery account
+- [ ] Sign with `account_to_recover`'s master key