Commit cdd19df0 authored by imtase's avatar imtase
Browse files

feat: add protocol coverage helpers and docs

parent c80fc0a6

architecture/DOCUMENTATION_COVERAGE_AUDIT.md

0 → 100644
+344 −0

File added.

Preview size limit exceeded, changes collapsed.

examples/README.md

+7 −0
Original line number Diff line number Diff line
@@ -40,11 +40,14 @@ Broadcast examples are intentionally not part of the initial example set. 
| [`node/read-witness.cjs`](./node/read-witness.cjs) | witness information | Node.js >=18 | blockchain-query | run | condenser_api | witness owner, signing key, votes and URL |

| [`node/read-account-history.cjs`](./node/read-account-history.cjs) | account operation history | Node.js >=18 | blockchain-query | run | condenser_api | account name and small history summary |

| [`node/stream-block-numbers.cjs`](./node/stream-block-numbers.cjs) | bounded blockchain iteration | Node.js >=18 | blockchain-query | run | condenser_api | three irreversible block numbers |

| [`node/read-blocks-with-helper.cjs`](./node/read-blocks-with-helper.cjs) | bounded block parsing helper | Node.js >=18 | blockchain-query | run | condenser_api | returned irreversible block numbers |

| [`node/read-operations-with-helper.cjs`](./node/read-operations-with-helper.cjs) | bounded operation parsing helper | Node.js >=18 | blockchain-query | run | condenser_api | operation count and first operation types |

| [`node/read-nexus-ranked-posts.cjs`](./node/read-nexus-ranked-posts.cjs) | Nexus social/indexed query | Node.js >=18 | blockchain-query | run | bridge | ranked post identities |

| [`node/read-nexus-community.cjs`](./node/read-nexus-community.cjs) | Nexus community discovery | Node.js >=18 | blockchain-query | run | bridge | community name, title and subscriber count |

| [`node/read-account-summary.cjs`](./node/read-account-summary.cjs) | high-level account read model | Node.js >=18 | blockchain-query | run | condenser_api + bridge | account, wallet, reward and social summary fields |

| [`node/estimate-vote-value.cjs`](./node/estimate-vote-value.cjs) | vote-value read model | Node.js >=18 | blockchain-query | run | condenser_api | account, weight, mana and estimated BLURT vote value |

| [`node/build-post-operation.cjs`](./node/build-post-operation.cjs) | local content operation builder | Node.js >=18 | static | run | none | comment operation tuple fields |

| [`node/asset-and-price.cjs`](./node/asset-and-price.cjs) | local Asset and Price helpers | Node.js >=18 | static | run | none | formatted assets and converted value |

| [`node/classify-retryable-error.cjs`](./node/classify-retryable-error.cjs) | typed error taxonomy | Node.js >=18 | static | run | none | classified retryable timeout metadata |

| [`node/generic-call.cjs`](./node/generic-call.cjs) | unwrapped RPC call | Node.js >=18 | blockchain-query | run | database_api | API version data |

| [`typescript/read-account.ts`](./typescript/read-account.ts) | typed consumer compile path | TypeScript / Node.js >=18 | blockchain-query | compile | condenser_api when executed | account summary for a configured account |
@@ -69,7 +72,11 @@ node examples/node/read-nexus-ranked-posts.cjs 
node examples/node/read-nexus-community.cjs

node examples/node/read-account-summary.cjs

node examples/node/estimate-vote-value.cjs

node examples/node/stream-block-numbers.cjs

node examples/node/read-blocks-with-helper.cjs

node examples/node/read-operations-with-helper.cjs

node examples/node/build-post-operation.cjs

node examples/node/asset-and-price.cjs

node examples/node/classify-retryable-error.cjs

node examples/node/generic-call.cjs

```

examples/node/asset-and-price.cjs

0 → 100644
+24 −0
Original line number Diff line number Diff line 
'use strict';



/**

 * Purpose: Parse, format and convert Blurt protocol assets locally.

 * Runtime: Node.js >=18

 * Safety level: static

 * Validation level: run

 * Required RPC: none

 * Expected output: JSON containing formatted assets and a converted value

 * Concept: Asset and Price helpers

 */



const { Asset, Price } = require('../_load-dblurt.cjs');



const balance = Asset.fromString('1.000 BLURT', 'BLURT');

const total = balance.add('2.500 BLURT');

const price = new Price(Asset.fromString('1.000 BLURT'), Asset.fromString('10.000000 VESTS'));

const converted = price.convert(Asset.fromString('2.000 BLURT'));



console.log(JSON.stringify({

    balance: balance.toString(),

    total: total.toString(),

    converted: converted.toString()

}, null, 2));

examples/node/read-blocks-with-helper.cjs

0 → 100644
+49 −0
Original line number Diff line number Diff line 
'use strict';



/**

 * Purpose: Read a bounded range of irreversible Layer 1 blocks with client.blockchain.getBlocks().

 * Runtime: Node.js >=18

 * Safety level: blockchain query

 * Validation level: run

 * Required RPC: public Blurt RPC endpoint with condenser_api support

 * Expected output: JSON containing requested block numbers and returned block count

 * Concept: Layer 1 block parsing helper

 */



const { Client, BlockchainMode } = require('../_load-dblurt.cjs');



const rpcList = [

    'https://rpc.blurt.blog',

    'https://blurt-rpc.saboin.com',

    'https://rpc.beblurt.com',

    'https://blurtrpc.dagobert.uk',

    'https://rpc.drakernoise.com'

];



const client = new Client(rpcList, { timeout: 15_000, failoverThreshold: 3 });



async function main() {

    const current = await client.blockchain.getCurrentBlockNum(BlockchainMode.Irreversible);

    const from = Math.max(1, current - 2);

    const to = current;

    const blocks = [];

    const blockNumbers = [];

    let nextBlockNumber = from;

    for await (const block of client.blockchain.getBlocks({ from, to, mode: BlockchainMode.Irreversible })) {

        blocks.push(block);

        blockNumbers.push(nextBlockNumber++);

    }



    console.log(JSON.stringify({

        mode: 'irreversible',

        from,

        to,

        returned_blocks: blocks.length,

        block_numbers: blockNumbers

    }, null, 2));

}



main().catch((error) => {

    console.error(error);

    process.exitCode = 1;

});

examples/node/read-operations-with-helper.cjs

0 → 100644
+53 −0
Original line number Diff line number Diff line 
'use strict';



/**

 * Purpose: Read operations from a bounded irreversible Layer 1 block range with client.blockchain.getOperations().

 * Runtime: Node.js >=18

 * Safety level: blockchain query

 * Validation level: run

 * Required RPC: public Blurt RPC endpoint with condenser_api support

 * Expected output: JSON containing block range, operation count and first operation types

 * Concept: Layer 1 operation parsing helper

 */



const { Client, BlockchainMode } = require('../_load-dblurt.cjs');



const rpcList = [

    'https://rpc.blurt.blog',

    'https://blurt-rpc.saboin.com',

    'https://rpc.beblurt.com',

    'https://blurtrpc.dagobert.uk',

    'https://rpc.drakernoise.com'

];



const client = new Client(rpcList, { timeout: 15_000, failoverThreshold: 3 });



function operationType(operation) {

    if (Array.isArray(operation.op)) {

        return operation.op[0];

    }

    return operation.op?.type || operation.type || null;

}



async function main() {

    const current = await client.blockchain.getCurrentBlockNum(BlockchainMode.Irreversible);

    const from = Math.max(1, current - 2);

    const to = current;

    const operations = [];

    for await (const operation of client.blockchain.getOperations({ from, to, mode: BlockchainMode.Irreversible })) {

        operations.push(operation);

    }



    console.log(JSON.stringify({

        mode: 'irreversible',

        from,

        to,

        operation_count: operations.length,

        first_operation_types: operations.slice(0, 5).map(operationType)

    }, null, 2));

}



main().catch((error) => {

    console.error(error);

    process.exitCode = 1;

});