@arxiumlabs/sdk 0.13.1 → 0.14.0

package/README.md

@@ -147,6 +147,10 @@ const dry = await rpc.simulateModule(address, { caller, input, gasLimit: gas });
 
 Only an attested account can deploy. A module holds a regulated asset only if it is attested like any holder, and it pays out only from its own account through the same checks as a transfer (freeze, claims, jurisdiction, caps, locks). Limits per module: 32 KiB of code, 1 KiB per stored value, 16 reads, 16 writes, 16 lookups, 4 transfers per call. A call is priced by its gas limit twice over: execution (one weight per 50 fuel) and the dispute-artifact bytes it could add (15,000 weight per 1,000 fuel, up to a whole block at 64 rows), so a tight limit is cheap and a 1,000,000 limit fills a block. Deploying costs 8 weight per code byte. There is no way to list a module's storage; keep your own index and read it by key.
 
+Events a module emits (`emit_event`) are kept per block: `rpc.blockEffects(height).module_events` lists each one as a `ModuleEventLine` with the `CallModule`'s `action_index` and `signature`, the `module`, and `topic` and `data` in hex, in the order emitted. A call that traps, runs out of gas or is refused leaves none. `arx query events <height> [module]` prints them. Blocks a node wrote before it kept events return an empty list.
+
+Stored state costs a deposit, paid from the **module's own balance** (fund it with an ordinary transfer): each row counts its key, its value and 64 bytes of overhead, times the chain's `module_storage_deposit_per_byte` (`rpc.actionFee()`, 0.001 ARX by default). `moduleStorageDeposit(keyBytes, valueBytes, perByte)` estimates it. A call that grows state the module cannot pay for is refused. Shrinking or deleting rows pays the deposit back to the module at the average price it paid. `rpc.module(address)` shows `storage_bytes` and `storage_deposit` (locked, not spendable).
+
 ### Programmable accounts
 
 The SDK exports bounded account-policy codecs and stateful owner/session/guardian witness helpers. `arx multisig build|sign|combine|link` lets each member sign separately, for both immutable and stateful account addresses. To verify a historical action, `verifySignedAction` needs the proven pre-action policy for stateful witnesses, and `arx verify SIGNATURE --policy FILE` accepts that policy. See [the programmable-account guide](../../docs/Programmable_Accounts.md).

package/dist/cli.js

@@ -379,8 +379,9 @@ async function main() {
                                         : operation === "stakes" ? await rpc.stakes(value ?? throwUsage("stakes needs an address"))
                                             : operation === "module" ? await rpc.module(value ?? throwUsage("module needs an address"))
                                                 : operation === "module-state" ? await rpc.moduleState(value ?? throwUsage("module-state needs <address> <key-hex>"), rest[2] ?? throwUsage("module-state needs <address> <key-hex>"))
-                                                    : operation === "fee" ? await rpc.actionFee()
-                                                        : throwUsage("use: arx query status|account|block|action|validators|validator|finality|search|assets [address]|asset|holders|balance|attestors|attestor|stakes|module|module-state|fee");
+                                                    : operation === "events" ? (await rpc.blockEffects(/^\d+$/.test(value ?? "") ? Number(value) : throwUsage("events needs <height> [module]"))).module_events.filter((event) => !rest[2] || event.module === rest[2])
+                                                        : operation === "fee" ? await rpc.actionFee()
+                                                            : throwUsage("use: arx query status|account|block|action|validators|validator|finality|search|assets [address]|asset|holders|balance|attestors|attestor|stakes|module|module-state|events|fee");
         output(result, globals.json);
         return;
     }

package/dist/fees.d.ts

@@ -6,8 +6,15 @@ export type FeeParams = {
 /** Fuel one weight unit pays for (`FUEL_PER_WEIGHT` in `arxd/runtime/src/module.rs`). */
 export declare const FUEL_PER_WEIGHT = 50;
 /** Dispute-artifact pricing for module actions (`BLOCK_PROOF_KEYS`, `PROOF_WEIGHT_PER_KEY`, `MODULE_BASE_KEYS`, `DEPLOY_WEIGHT_PER_CODE_BYTE`, `COST_READ` in metering.rs and `xc_wasm`). */
-export declare const BLOCK_PROOF_KEYS = 64, PROOF_WEIGHT_PER_KEY = 15000, MODULE_BASE_KEYS = 4, DEPLOY_WEIGHT_PER_CODE_BYTE = 7, COST_READ = 1000;
+export declare const BLOCK_PROOF_KEYS = 64, PROOF_WEIGHT_PER_KEY = 15000, MODULE_BASE_KEYS = 5, DEPLOY_WEIGHT_PER_CODE_BYTE = 7, COST_READ = 1000;
 /** `POLICY_AUTHORIZATION_WEIGHT`: added when a stateful account policy authorizes the action. */
+/** Bytes a module state row counts for the storage deposit beyond its key and value (`STATE_ROW_OVERHEAD` in module.rs). */
+export declare const STATE_ROW_OVERHEAD = 64;
+/**
+ * IUM a module locks from its own balance to store `value` under `key` (or frees, for a row it deletes), at the chain's
+ * `module_storage_deposit_per_byte` (`rpc.actionFee()`). A refund is at the average price the module paid, so it can differ.
+ */
+export declare const moduleStorageDeposit: (keyBytes: number, valueBytes: number, perByte: bigint) => bigint;
 export declare const POLICY_AUTHORIZATION_WEIGHT = 5000;
 /** A single-key ed25519 signature: 64 bytes as hex. */
 export declare const SINGLE_SIGNATURE_LENGTH = 128;

package/dist/fees.js

@@ -28,8 +28,15 @@ const BASE_WEIGHT = {
 /** Fuel one weight unit pays for (`FUEL_PER_WEIGHT` in `arxd/runtime/src/module.rs`). */
 export const FUEL_PER_WEIGHT = 50;
 /** Dispute-artifact pricing for module actions (`BLOCK_PROOF_KEYS`, `PROOF_WEIGHT_PER_KEY`, `MODULE_BASE_KEYS`, `DEPLOY_WEIGHT_PER_CODE_BYTE`, `COST_READ` in metering.rs and `xc_wasm`). */
-export const BLOCK_PROOF_KEYS = 64, PROOF_WEIGHT_PER_KEY = 15_000, MODULE_BASE_KEYS = 4, DEPLOY_WEIGHT_PER_CODE_BYTE = 7, COST_READ = 1_000;
+export const BLOCK_PROOF_KEYS = 64, PROOF_WEIGHT_PER_KEY = 15_000, MODULE_BASE_KEYS = 5, DEPLOY_WEIGHT_PER_CODE_BYTE = 7, COST_READ = 1_000;
 /** `POLICY_AUTHORIZATION_WEIGHT`: added when a stateful account policy authorizes the action. */
+/** Bytes a module state row counts for the storage deposit beyond its key and value (`STATE_ROW_OVERHEAD` in module.rs). */
+export const STATE_ROW_OVERHEAD = 64;
+/**
+ * IUM a module locks from its own balance to store `value` under `key` (or frees, for a row it deletes), at the chain's
+ * `module_storage_deposit_per_byte` (`rpc.actionFee()`). A refund is at the average price the module paid, so it can differ.
+ */
+export const moduleStorageDeposit = (keyBytes, valueBytes, perByte) => BigInt(keyBytes + valueBytes + STATE_ROW_OVERHEAD) * perByte;
 export const POLICY_AUTHORIZATION_WEIGHT = 5_000;
 /** A single-key ed25519 signature: 64 bytes as hex. */
 export const SINGLE_SIGNATURE_LENGTH = 128;

package/dist/rpc.d.ts

@@ -208,6 +208,8 @@ export type ModuleInfo = {
     deployed_at: number;
     version: number;
     code_size: number;
+    storage_bytes: number;
+    storage_deposit: bigint;
 };
 /** A collateral pledge as stored (`xc_primitives::Pledge`). `asset` is `"Native"` or `{ Asset: ref }`, the node's JSON for `SpendAsset`. */
 export type Pledge = {
@@ -241,11 +243,20 @@ export type PledgeEffect = {
     pledge: string;
     record: Pledge | null;
 };
-/** `rpc.blockEffects(height)`. `corporate_actions` and `pledges` are typed; the other fields mirror the node's `BlockEffects`. */
+/** One `emit_event` of a module call the block applied (`topic` and `data` are hex). A call that traps or is refused leaves none. */
+export type ModuleEventLine = {
+    action_index: number;
+    signature: string;
+    module: string;
+    topic: string;
+    data: string;
+};
+/** `rpc.blockEffects(height)`. `corporate_actions`, `pledges` and `module_events` are typed; the other fields mirror the node's `BlockEffects`. */
 export type BlockEffects = {
     height: number;
     corporate_actions: CorporateActionLine[];
     pledges: PledgeEffect[];
+    module_events: ModuleEventLine[];
     [field: string]: unknown;
 };
 export type ActionFeeInfo = {
@@ -253,6 +264,7 @@ export type ActionFeeInfo = {
     weight_fee: bigint;
     max_block_weight: number;
     token_create_fee: bigint;
+    module_storage_deposit_per_byte: bigint;
 };
 export type { AssetClass };
 /**

package/dist/rpc.js

@@ -20,7 +20,7 @@ export class ActionDroppedError extends Error {
     }
 }
 /** Keys whose integer values are token amounts (u128 on the node): always `bigint`, so callers never see a rounded balance. */
-const AMOUNT_KEYS = new Set(["balance", "amount", "stake", "active_amount", "frozen_amount", "total_supply", "max_supply", "max_balance_per_holder", "total", "action_fee", "weight_fee", "token_create_fee", "min_stake", "exposure", "unit_price", "collateral_value", "shortfall"]);
+const AMOUNT_KEYS = new Set(["balance", "amount", "stake", "active_amount", "frozen_amount", "total_supply", "max_supply", "max_balance_per_holder", "total", "action_fee", "weight_fee", "token_create_fee", "min_stake", "exposure", "unit_price", "collateral_value", "shortfall", "storage_deposit", "module_storage_deposit_per_byte"]);
 const MARK = "\u0000int:";
 /**
  * `JSON.parse` that never rounds an integer: the node writes u128 amounts as bare JSON numbers, and anything above 2^53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arxiumlabs/sdk",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Arxium TypeScript SDK and arx CLI",
   "type": "module",
   "private": false,