hive-stream 3.0.0 → 3.0.1

package/AGENTS.md

@@ -0,0 +1,35 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/` holds TypeScript source. Core entry points are `streamer.ts`, `api.ts`, and `index.ts`.
+- `src/adapters/` contains SQLite/Mongo/Postgres adapters; `src/contracts/` has contract examples; `src/exchanges/` has rate helpers; `src/types/` centralizes shared types.
+- `tests/` contains Jest specs (`**/*.spec.ts`) plus `tests/integration/` and `tests/helpers/`.
+- `dist/` is generated build output; `examples/` provides usage samples; `ecosystem.config.js` is a PM2 reference.
+
+## Build, Test, and Development Commands
+- `npm install` installs dependencies.
+- `npm run build` compiles TypeScript to `dist/`.
+- `npm run start` runs the local dev harness (`src/test.ts`) via ts-node.
+- `npm run watch` enables TypeScript watch mode.
+- `npm test` runs the Jest suite.
+- `npm run clean-tests` clears Jest cache if tests act stale.
+
+## Coding Style & Naming Conventions
+- TypeScript with CommonJS output; keep module boundaries within `src/`.
+- Indent 4 spaces; prefer single quotes (see `tslint.json`).
+- File naming conventions: `*.adapter.ts`, `*.contract.ts`, `*.spec.ts`; shared types live in `src/types/`.
+- TSLint rules in `tslint.json` are the baseline; match existing style before introducing new tooling.
+
+## Testing Guidelines
+- Framework: Jest + `ts-jest` (see `jest.config.js`).
+- Place specs under `tests/` and name `*.spec.ts` (example: `tests/utils.spec.ts`).
+- Use `tests/setup.ts` for shared mocks; integration tests live under `tests/integration/`.
+- No coverage thresholds are configured; add focused tests for new adapters, contracts, or API routes.
+
+## Commit & Pull Request Guidelines
+- Follow Conventional Commits with scopes, as in history: `feat(api): ...`, `fix(contract): ...`, `chore(deps): ...`, `docs(readme): ...`.
+- PRs should include: a clear summary, testing notes (`npm test`/`npm run build`), and docs/CHANGELOG updates for user-facing changes.
+
+## Configuration & Security Notes
+- Keys and usernames should come from env/config (see `src/config.ts`); never commit secrets.
+- When adding new config, document defaults and keep backward compatibility.

package/DOCUMENTATION.md

@@ -0,0 +1,380 @@
+# Hive-Stream Documentation
+
+## Introduction
+Hive Stream is a Node.js library for streaming Hive blockchain activity and routing it to contracts you define. Contracts can react to:
+- `custom_json` operations
+- transfer memos
+- time-based actions
+- escrow operations
+
+This document focuses on the contract system and how to build robust contracts using the new `defineContract`/`action` API.
+
+---
+
+## Concepts
+
+### Contracts
+A **contract** is a definition object with:
+- a **name**
+- one or more **actions**
+- optional **lifecycle hooks**
+
+Contracts are registered with the `Streamer` and called when a payload matches `contract` + `action`.
+
+### Actions
+An **action** is a handler function plus metadata such as:
+- the trigger (`custom_json`, `transfer`, or `time`)
+- the trigger (`custom_json`, `transfer`, `time`, `escrow_transfer`, `escrow_approve`, `escrow_dispute`, `escrow_release`, or `recurrent_transfer`)
+- an optional Zod schema to validate payloads
+- whether it requires an active key signature
+
+### Payload Identifier
+Hive Stream extracts payloads from:
+- **custom_json**: `op[1].json`
+- **transfer memo**: `op[1].memo`
+
+It expects a wrapper object that looks like:
+
+```
+{
+  "hive_stream": {
+    "contract": "mycontract",
+    "action": "doSomething",
+    "payload": { "any": "data" },
+    "meta": { "optional": true }
+  }
+}
+```
+
+The wrapper key `hive_stream` is the default `PAYLOAD_IDENTIFIER`. You can change it in config.
+
+---
+
+## Contract API
+
+### Define a Contract
+
+```ts
+import { defineContract, action } from 'hive-stream';
+
+const MyContract = defineContract({
+    name: 'mycontract',
+    actions: {
+        hello: action(async (payload, ctx) => {
+            console.log('hello', payload.name, ctx.sender);
+        }, {
+            trigger: 'custom_json'
+        })
+    }
+});
+```
+
+### Register a Contract
+
+```ts
+import { Streamer } from 'hive-stream';
+
+const streamer = new Streamer();
+await streamer.registerContract(MyContract);
+```
+
+### Unregister a Contract
+
+```ts
+await streamer.unregisterContract('mycontract');
+```
+
+### Contract Lifecycle Hooks
+
+```ts
+const MyContract = defineContract({
+    name: 'mycontract',
+    hooks: {
+        create: async ({ streamer, adapter, config }) => {
+            // initialize tables, cache config, etc
+        },
+        destroy: async ({ streamer, adapter }) => {
+            // cleanup resources
+        }
+    },
+    actions: { ... }
+});
+```
+
+---
+
+## Contract Context
+
+Every action receives a `ContractContext` with:
+
+- `trigger`: `custom_json | transfer | time | escrow_transfer | escrow_approve | escrow_dispute | escrow_release | recurrent_transfer`
+- `streamer`: access to Hive client and helpers
+- `adapter`: database adapter
+- `config`: resolved config values
+- `block`: `{ number, id, previousId, time }`
+- `transaction`: `{ id }`
+- `sender`: Hive account invoking the action
+- `transfer`: transfer details (only for `transfer` trigger)
+- `customJson`: custom JSON details (only for `custom_json` trigger)
+- `escrow`: escrow details (only for escrow triggers)
+- `operation`: raw operation data and operation type for advanced use cases
+
+### Example
+
+```ts
+action((payload, ctx) => {
+    console.log(ctx.trigger);
+    console.log(ctx.block.number, ctx.transaction.id);
+    if (ctx.transfer) {
+        console.log(ctx.transfer.amount, ctx.transfer.asset);
+    }
+});
+```
+
+---
+
+## Payload Validation (Zod)
+
+Use Zod to validate payloads and enforce strong inputs:
+
+```ts
+import { z } from 'zod';
+
+const schema = z.object({
+    amount: z.string().min(1),
+    to: z.string().min(1)
+});
+
+const MyContract = defineContract({
+    name: 'payments',
+    actions: {
+        send: action((payload, ctx) => {
+            // payload is validated here
+        }, { schema, trigger: 'custom_json' })
+    }
+});
+```
+
+If validation fails, the action is not executed and the error is logged.
+
+---
+
+## Triggers
+
+Actions can be scoped to a trigger:
+
+- `custom_json`: called when a custom JSON payload matches
+- `transfer`: called when a transfer memo matches
+- `time`: called by a `TimeAction`
+- `escrow_transfer`: called when escrow transfer payload in `json_meta` matches
+- `escrow_approve`: available as a trigger for escrow-related contracts
+- `escrow_dispute`: available as a trigger for escrow-related contracts
+- `escrow_release`: available as a trigger for escrow-related contracts
+- `recurrent_transfer`: called when recurrent transfer memo payload matches
+
+```ts
+action(handler, { trigger: 'transfer' });
+```
+
+You can also allow multiple triggers:
+
+```ts
+action(handler, { trigger: ['custom_json', 'transfer'] });
+```
+
+---
+
+## Active Key Enforcement
+
+Some actions should only run when the transaction is signed with an active key. Mark them with:
+
+```ts
+action(handler, { trigger: 'custom_json', requiresActiveKey: true });
+```
+
+This prevents posting-key JSONs from triggering sensitive actions like withdrawals.
+
+---
+
+## Error Handling
+
+- Errors inside contract actions are caught and logged.
+- **Time actions** bubble errors back into the scheduler so the action does **not** increment execution count if it fails.
+
+Write actions defensively and always validate inputs.
+
+---
+
+## Time-Based Actions
+
+Time-based actions let you run contract logic on a schedule:
+
+```ts
+import { TimeAction } from 'hive-stream';
+
+const matchAction = new TimeAction('30s', 'exchange-matcher', 'exchange', 'matchOrders', { limit: 50 });
+await streamer.registerAction(matchAction);
+```
+
+The action must have `trigger: 'time'` in its definition.
+
+---
+
+## Adapter Requirements
+
+Contracts can use any adapter, but some require SQL features:
+
+- **SQL adapters** (SQLite/Postgres) support `adapter.query(...)`.
+- **MongoDB adapter** does not support raw SQL.
+
+If a contract uses `adapter.query`, it must document that it requires a SQL adapter.
+
+---
+
+## Building Contracts Step-by-Step
+
+1. **Define the contract** with `defineContract`.
+2. **Define actions** with `action`, specifying trigger and optional schema.
+3. **Use hooks** (`create`, `destroy`) to initialize tables or cache configuration.
+4. **Validate input** using Zod.
+5. **Use `ctx`** for block/transaction context.
+6. **Return void** (actions are fire-and-forget).
+7. **Register the contract** with the streamer.
+
+---
+
+## Example Contract
+
+```ts
+import { defineContract, action } from 'hive-stream';
+import { z } from 'zod';
+
+const tipSchema = z.object({
+    message: z.string().max(280).optional()
+});
+
+export const TipJar = defineContract({
+    name: 'tipjar',
+    actions: {
+        tip: action(async (payload, ctx) => {
+            if (!ctx.transfer) {
+                throw new Error('Transfer context required');
+            }
+
+            console.log(`Tip from ${ctx.sender}: ${ctx.transfer.amount} ${ctx.transfer.asset}`);
+            if (payload.message) {
+                console.log(`Message: ${payload.message}`);
+            }
+        }, {
+            schema: tipSchema,
+            trigger: 'transfer'
+        })
+    }
+});
+```
+
+---
+
+## Built-in Contract Examples
+
+- `createDiceContract` - Dice game using transfer bets
+- `createCoinflipContract` - Coin flip game using transfer bets
+- `createLottoContract` - Lottery system with scheduled draws
+- `createTokenContract` - SQL-backed fungible tokens
+- `createNFTContract` - SQL-backed NFTs
+- `createRpsContract` - Rock/Paper/Scissors
+- `createPollContract` - Polls and votes
+- `createTipJarContract` - Tip jar + message log
+- `createExchangeContract` - Deposits/withdrawals/orders/matching (SQL)
+
+### Example Snippets
+
+Quick-start snippets live in `examples/contracts/`:
+
+- `examples/contracts/rps.ts`
+- `examples/contracts/poll.ts`
+- `examples/contracts/tipjar.ts`
+- `examples/contracts/exchange.ts`
+
+---
+
+## Exchange Contract Guide
+
+The exchange contract gives you a basic on-chain orderbook experience backed by a SQL adapter.
+
+### Features
+- Deposits via transfer memo
+- Internal balances (available + locked)
+- Order placement and cancellation
+- Order matching
+- Withdrawals (active key required)
+- Internal transfers between exchange users
+- Maker/taker fees (basis points)
+- Order book snapshots for API consumption
+
+### Notes
+- Requires a SQL adapter (SQLite or Postgres).
+- Uses `TimeAction` to run `matchOrders` periodically.
+- Fees are charged on received assets (base for buyers, quote for sellers).
+
+### Configuration Options
+```
+createExchangeContract({
+  name: 'exchange',
+  account: 'my-exchange',
+  feeAccount: 'my-exchange-fees',
+  makerFeeBps: 10,
+  takerFeeBps: 20
+})
+```
+
+### Example Payloads
+
+**Create pair**
+```
+{"hive_stream": {"contract":"exchange","action":"createPair","payload":{"base":"HIVE","quote":"HBD"}}}
+```
+
+**Deposit** (send transfer to exchange account with memo)
+```
+{"hive_stream": {"contract":"exchange","action":"deposit","payload":{}}}
+```
+
+**Place order**
+```
+{"hive_stream": {"contract":"exchange","action":"placeOrder","payload":{"side":"buy","base":"HIVE","quote":"HBD","price":"2","amount":"5"}}}
+```
+
+**Cancel order**
+```
+{"hive_stream": {"contract":"exchange","action":"cancelOrder","payload":{"orderId":"..."}}}
+```
+
+**Snapshot orderbook**
+```
+{"hive_stream": {"contract":"exchange","action":"snapshotOrderBook","payload":{"base":"HIVE","quote":"HBD","depth":20}}}
+```
+
+**Withdraw**
+```
+{"hive_stream": {"contract":"exchange","action":"withdraw","payload":{"asset":"HBD","amount":"5.000"}}}
+```
+
+### API Endpoints
+
+If you run the built-in API server, the following endpoints are available:
+
+- `GET /exchange/balances` (optional query `?account=alice`)
+- `GET /exchange/orders` (query `account`, `base`, `quote`, `status`)
+- `GET /exchange/trades` (query `account`, `base`, `quote`)
+- `GET /exchange/orderbook` (query `base`, `quote`, `limit`)
+
+---
+
+## Utilities
+The library includes helpers for JSON parsing, randomness, and transfer verification. See `src/utils.ts` for details.
+
+---
+
+## Tests
+Contract tests live under `tests/contracts/`. Time action tests are in `tests/streamer-actions.spec.ts`.

package/README.md

@@ -29,6 +29,10 @@ The `BLOCK_CHECK_INTERVAL` value is how often to check for new blocks or in case
 
 The `BLOCKS_BEHIND_WARNING` value is a numeric value of the number of blocks your API will fall behind from the master before warning to the console.
 
+To resume automatically from stored state, keep `RESUME_FROM_STATE` enabled (default). To force a specific start block, set `RESUME_FROM_STATE` to `false` and supply `LAST_BLOCK_NUMBER`.
+
+For faster catch-up, `CATCH_UP_BATCH_SIZE` controls how many blocks are processed per polling cycle, and `CATCH_UP_DELAY_MS` controls the delay between catch-up batches (set to `0` for fastest catch-up).
+
 The `API_NODES` are the Hive API endpoints used for failover. If you want to enable debug mode, set `DEBUG_MODE` to `true`. The configuration values and their defaults can be found in `src/config.ts`.
 
 ```
@@ -40,6 +44,9 @@ const options = {
   LAST_BLOCK_NUMBER: 0,
   BLOCK_CHECK_INTERVAL: 1000,
   BLOCKS_BEHIND_WARNING: 25,
+  RESUME_FROM_STATE: true,
+  CATCH_UP_BATCH_SIZE: 50,
+  CATCH_UP_DELAY_MS: 0,
   API_NODES: ['https://api.hive.blog', 'https://api.openhive.network', 'https://rpc.ausbit.dev'],
   DEBUG_MODE: false
 }
@@ -70,6 +77,25 @@ ss.onTransfer((op, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
 })
 ```
 
+#### Watch for escrow operations
+```javascript
+ss.onEscrowTransfer((op, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+  
+});
+
+ss.onEscrowApprove((op, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+  
+});
+
+ss.onEscrowDispute((op, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+  
+});
+
+ss.onEscrowRelease((op, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
+  
+});
+```
+
 #### Watch for custom JSON operations
 ```javascript
 ss.onCustomJson((op, { sender, isSignedWithActiveKey }, blockNumber, blockId, prevBlockId, trxId, blockTime) => {
@@ -145,6 +171,42 @@ issueHiveEngineTokensMultiple(from, accounts = [], symbol, memo = '', amount = '
 }
 ```
 
+### Escrow Operations
+```javascript
+escrowTransfer({
+  from,
+  to,
+  agent,
+  escrow_id,
+  hive_amount = '0.000 HIVE',
+  hbd_amount = '0.000 HBD',
+  fee,
+  ratification_deadline,
+  escrow_expiration,
+  json_meta
+}, signingKeys?)
+
+escrowApprove({ from, to, agent, who, escrow_id, approve }, signingKeys?)
+escrowDispute({ from, to, agent, who, escrow_id }, signingKeys?)
+escrowRelease({ from, to, agent, who, receiver, escrow_id, hive_amount, hbd_amount }, signingKeys?)
+```
+
+### Multisig + Authority Helpers
+```javascript
+broadcastOperations(operations, signingKeys?)
+broadcastMultiSigOperations(operations, signingKeys)
+createAuthority(keyAuths, accountAuths, weightThreshold)
+updateAccountAuthorities(account, authorityUpdate, signingKeys?)
+```
+
+### Recurrent Transfers + Governance
+```javascript
+recurrentTransfer({ from, to, amount, memo, recurrence, executions }, signingKeys?)
+createProposal({ creator, receiver, start_date, end_date, daily_pay, subject, permlink }, signingKeys?)
+updateProposalVotes({ voter, proposal_ids, approve }, signingKeys?)
+removeProposals({ proposal_owner, proposal_ids }, signingKeys?)
+```
+
 ### Upvote/Downvote Posts
 ```javascript
 upvote(votePercentage = '100.0', username, permlink) {
@@ -158,28 +220,38 @@ downvote(votePercentage = '100.0', username, permlink) {
 
 ## Contracts
 
-Hive Stream allows you to write contracts which get executed when a custom JSON operation matches. The only requirement is sending a payload which contains `hivePayload` inside of it.
-
-The payload consists of:
-
-`name` the name of the smart contract you registered.
+Hive Stream allows you to register contract definitions that execute when a transfer memo or custom JSON operation matches. The payload lives under the `PAYLOAD_IDENTIFIER` (default: `hive_stream`).
 
-`action` matches the name of a function defined inside of your contract
+The payload shape is:
 
-`payload` an object of data which will be provided to the action
+- `contract`: the name of the contract you registered
+- `action`: the action name defined in your contract
+- `payload`: data passed to the action
+- `meta`: optional metadata
 
 ### Writing contracts
 
-Really, a contract is nothing more than a bunch of functions which get matched to values inside of JSON payloads.
+Contracts are defined with `defineContract` + `action`. Each action can specify a trigger (`custom_json`, `transfer`, `time`, `escrow_transfer`, `escrow_approve`, `escrow_dispute`, `escrow_release`, or `recurrent_transfer`) and an optional Zod schema for payload validation.
+
+For a full contract-building guide (payloads, context, triggers, validation, error handling, and exchange setup), see `DOCUMENTATION.md`.
 
 ### Register a contract
 
-Register a file containing contract code which will be executed.
+Register a contract definition. Registration is async so hooks can initialize state.
 
 ```javascript
-import contract from './my-contract';
+import { defineContract, action } from 'hive-stream';
+
+const MyContract = defineContract({
+    name: 'mycontract',
+    actions: {
+        hello: action(async (payload, ctx) => {
+            console.log('hello', payload, ctx.sender);
+        }, { trigger: 'custom_json' })
+    }
+});
 
-registerContract('mycontract', Contract);
+await streamer.registerContract(MyContract);
 ```
 
 ### Unregister a contract
@@ -187,33 +259,52 @@ registerContract('mycontract', Contract);
 Unregister a contract that has been registered.
 
 ```javascript
-unregisterContract('mycontract');
+await streamer.unregisterContract('mycontract');
 ```
 
 ### Example Payload
 
 ```javascript
-JSON.stringify({ hivePayload: { name: 'hivedice', action: 'roll', payload: { roll: 22, amount: '1'} } })
+JSON.stringify({
+    hive_stream: {
+        contract: 'hivedice',
+        action: 'roll',
+        payload: { roll: 22 }
+    }
+})
 ```
 
-This will match a registered contract called `hivedice` and inside of the contract code, a function called `roll` and finally, the payload is sent to the function as an argument, allowing you to access the values inside of it. 
+This will match a registered contract called `hivedice`, run the `roll` action, and pass the payload into your handler.
 
 ### Built-in Contract Examples
 
 The library includes several built-in contract examples in the `src/contracts` folder:
 
-- `DiceContract` - A dice rolling game contract
-- `CoinflipContract` - A coin flip game contract  
-- `LottoContract` - A lottery-style game contract
-- `TokenContract` - A contract for token operations
-- `NFTContract` - A contract for NFT operations
+- `createDiceContract` - A dice rolling game contract
+- `createCoinflipContract` - A coin flip game contract
+- `createLottoContract` - A lottery-style game contract
+- `createTokenContract` - A contract for token operations
+- `createNFTContract` - A contract for NFT operations
+- `createRpsContract` - A rock-paper-scissors game contract
+- `createPollContract` - A poll/voting contract
+- `createTipJarContract` - A tip jar + message board contract
+- `createExchangeContract` - A basic exchange with deposits, withdrawals, balances, and order matching (SQL adapter required)
 
 These can be imported and used as examples for building your own contracts:
 
 ```javascript
-import { DiceContract, CoinflipContract, LottoContract } from 'hive-stream';
+import { createDiceContract, createCoinflipContract, createLottoContract } from 'hive-stream';
 ```
 
+### Example Snippets
+
+Sample snippets for the newest contracts live in `examples/contracts/`:
+
+- `examples/contracts/rps.ts`
+- `examples/contracts/poll.ts`
+- `examples/contracts/tipjar.ts`
+- `examples/contracts/exchange.ts`
+
 ## Time-based Actions
 
 It's like a cron job for your contracts. Time-based actions allow you to execute contract functions over a wide variety of different periods. Want to call a function every 3 seconds block time or want to call a function once per day? Time-based actions are an easy way to run time code.
@@ -239,11 +330,11 @@ The `TimeAction` instance accepts the following values:
 - timeValue - When should this action be run?
 - uniqueId - A unique ID to describe your action
 - contractName - The name of the contract
-- contractMethod - The method we are calling inside of the contract
+- contractAction - The action we are calling inside of the contract
 - date - An optional final parameter that accepts a date of creation
 
 ```
-new TimeAction(timeValue, uniqueId, contractName, contractMethod, date)
+new TimeAction(timeValue, uniqueId, contractName, contractAction, date)
 ```
 
 ### Valid time values

package/dist/actions.d.ts

@@ -2,7 +2,7 @@ export interface TimeActionInterface {
     timeValue: string;
     id: string;
     contractName: string;
-    contractMethod: string;
+    contractAction: string;
     payload: any;
     date: Date;
     enabled: boolean;
@@ -15,7 +15,7 @@ export declare class TimeAction implements TimeActionInterface {
     timeValue: string;
     id: string;
     contractName: string;
-    contractMethod: string;
+    contractAction: string;
     payload: any;
     date: Date;
     enabled: boolean;
@@ -24,7 +24,7 @@ export declare class TimeAction implements TimeActionInterface {
     maxExecutions?: number;
     timezone?: string;
     private static readonly VALID_TIME_VALUES;
-    constructor(timeValue: string, id: string, contractName: string, contractMethod: string, payload?: any, date?: Date | string, enabled?: boolean, executionCount?: number, maxExecutions?: number, timezone?: string);
+    constructor(timeValue: string, id: string, contractName: string, contractAction: string, payload?: any, date?: Date | string, enabled?: boolean, executionCount?: number, maxExecutions?: number, timezone?: string);
     private validateTimeValue;
     private validateId;
     private validateContractName;