@parity/product-sdk-bulletin 0.1.0 → 0.2.1

package/src/authorization.ts

@@ -1,7 +1,9 @@
 import { createLogger } from "@parity/product-sdk-logger";
+import { submitAndWatch, type TxStatus, type WaitFor } from "@parity/product-sdk-tx";
+import type { PolkadotSigner } from "polkadot-api";
 import { Enum } from "polkadot-api";
 
-import { BulletinAuthorizationError } from "./errors.js";
+import { BulletinAuthorizationError, ProductBulletinError } from "./errors.js";
 import type { AuthorizationStatus, BulletinApi } from "./types.js";
 
 const log = createLogger("bulletin");
@@ -63,10 +65,18 @@ export async function checkAuthorization(
         return NOT_AUTHORIZED;
     }
 
+    // After polkadot-bulletin-chain PR #448 (e543696, 2026-04-30), AuthorizationExtent's
+    // `transactions` and `bytes` fields are *consumed counters*; the granted allowance moved
+    // to `transactions_allowance` / `bytes_allowance`. Compute remaining = allowance − consumed
+    // so the public `remainingTransactions` / `remainingBytes` contract stays semantically
+    // honest.
     const status: AuthorizationStatus = {
         authorized: true,
-        remainingTransactions: auth.extent.transactions,
-        remainingBytes: auth.extent.bytes,
+        remainingTransactions: auth.extent.transactions_allowance - auth.extent.transactions,
+        // `auth` is `any` (TypedApi<any> upstream — see line 53). TS narrows
+        // `any - any` to `number`, so cast each u64 operand to bigint to keep
+        // the subtraction in bigint space. Runtime values are bigints from PAPI.
+        remainingBytes: (auth.extent.bytes_allowance as bigint) - (auth.extent.bytes as bigint),
         expiration: auth.expiration,
     };
 
@@ -80,6 +90,144 @@ export async function checkAuthorization(
     return status;
 }
 
+/**
+ * Options for {@link authorizeAccount}.
+ */
+export interface AuthorizeAccountOptions {
+    /**
+     * Wrap the extrinsic in `Sudo.sudo(...)` before submission. Default: `false`.
+     *
+     * Use `true` on networks where granting bulletin storage authorization
+     * requires sudo permissions (most production / managed test networks).
+     * Use `false` (default) when the account self-authorizes — typical for
+     * local development chains.
+     */
+    viaSudo?: boolean;
+    /** When to resolve: `"best-block"` (default) or `"finalized"`. */
+    waitFor?: WaitFor;
+    /** Timeout in ms. Default: 300_000 (5 min). */
+    timeoutMs?: number;
+    /** Lifecycle status callback for UI progress. */
+    onStatus?: (status: TxStatus) => void;
+}
+
+/**
+ * Grant an account authorization to store data on the Bulletin Chain.
+ *
+ * Submits a `TransactionStorage.authorize_account` extrinsic, optionally
+ * wrapped in `Sudo.sudo(...)` for networks that require sudo to grant
+ * authorization. Mirrors the call shape of {@link upload} — top-level
+ * function, takes an explicit signer, returns a block hash on success.
+ *
+ * Pair with {@link checkAuthorization} for a typical "check, grant if
+ * insufficient, then upload" flow.
+ *
+ * ## Additive semantics — call once per authorization need
+ *
+ * `authorize_account` is **additive** within an unexpired authorization window
+ * for `AuthorizationScope::Account` (see `pallet-bulletin-transaction-storage`,
+ * `fn authorize`). Each successful call **adds** to the existing
+ * `transactions_allowance` and `bytes_allowance` rather than overwriting them.
+ *
+ * Implications for callers:
+ *
+ * - Calling this function twice with `(100, 1MB)` while the previous
+ *   authorization is still active leaves the account with quota for `200`
+ *   transactions and `2MB` — likely unintended.
+ * - **This function does NOT use `withRetry`.** Retrying a successful-but-
+ *   acknowledgment-lost submission would double-grant the quota. Callers
+ *   needing retry should wrap this function and use {@link checkAuthorization}
+ *   to verify the post-state before retrying.
+ * - To "reset" a quota, let the existing authorization expire
+ *   (`AuthorizationPeriod` blocks). The next call after expiry creates a fresh
+ *   authorization rather than adding.
+ *
+ * Note: `AuthorizationScope::Preimage` uses `set` semantics in the same
+ * pallet. This helper is for account-scope authorization only.
+ *
+ * @param api          - Typed Bulletin Chain API instance.
+ * @param who          - SS58-encoded account to authorize.
+ * @param transactions - Number of transactions to **add** to the account's allowance.
+ * @param bytes        - Byte budget to **add** to the account's allowance.
+ * @param signer       - Signer for the extrinsic. On `viaSudo: true` this must be the sudo key.
+ * @param options      - Optional `viaSudo` flag plus standard submission controls.
+ * @returns Block hash where the extrinsic was included.
+ * @throws {ProductBulletinError} If `viaSudo: true` is requested but the chain has no `Sudo` pallet.
+ *
+ * @example Direct (account self-authorizes — local dev)
+ * ```ts
+ * import { authorizeAccount } from "@parity/product-sdk-bulletin";
+ *
+ * await authorizeAccount(api, address, 100, 100n * 1024n * 1024n, signer);
+ * ```
+ *
+ * @example Sudo-wrapped (managed test network)
+ * ```ts
+ * await authorizeAccount(api, userAddress, 100, 1_000_000n, sudoSigner, {
+ *     viaSudo: true,
+ * });
+ * ```
+ *
+ * @see {@link checkAuthorization} for the read counterpart.
+ * @see {@link BulletinClient.authorizeAccount} for the client method equivalent.
+ */
+export async function authorizeAccount(
+    api: BulletinApi,
+    who: string,
+    transactions: number,
+    bytes: bigint,
+    signer: PolkadotSigner,
+    options: AuthorizeAccountOptions = {},
+): Promise<{ blockHash: string }> {
+    const { viaSudo = false, waitFor, timeoutMs, onStatus } = options;
+
+    // Single `as any` cast for the whole function. `BulletinApi` is upstream-
+    // typed as `TypedApi<any>` (see types.ts), so member access is loose by
+    // design. Same pattern as upload.ts:57 — narrowing it requires retyping
+    // BulletinApi against a bundled descriptor (out of scope here).
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const apiTx = (api as any).tx;
+
+    log.info("authorizeAccount: building extrinsic", {
+        who,
+        transactions,
+        bytes: bytes.toString(),
+        viaSudo,
+    });
+
+    if (viaSudo && !apiTx.Sudo?.sudo) {
+        throw new ProductBulletinError(
+            "viaSudo: true requires the Sudo pallet, which is not available on this network. " +
+                "On production networks (Polkadot, Kusama), authorize_account requires governance or a different mechanism.",
+        );
+    }
+
+    const authorizeTx = apiTx.TransactionStorage.authorize_account({
+        who,
+        transactions,
+        bytes,
+    });
+
+    const txToSubmit = viaSudo ? apiTx.Sudo.sudo({ call: authorizeTx.decodedCall }) : authorizeTx;
+
+    // NOTE: Intentionally NOT using `withRetry` here. `authorize_account` is
+    // additive (see JSDoc above), so a retry after a successful-but-lost
+    // submission would double-grant the quota. Caller-side retry must verify
+    // post-state via `checkAuthorization` first.
+    const result = await submitAndWatch(txToSubmit, signer, {
+        waitFor,
+        timeoutMs,
+        onStatus,
+    });
+
+    log.info("authorizeAccount: included in block", {
+        who,
+        blockHash: result.block.hash,
+    });
+
+    return { blockHash: result.block.hash };
+}
+
 if (import.meta.vitest) {
     const { describe, test, expect, vi } = import.meta.vitest;
 
@@ -106,9 +254,15 @@ if (import.meta.vitest) {
             expect(status.expiration).toBe(0);
         });
 
-        test("returns authorization with full quota", async () => {
+        test("returns authorization with full quota (fresh authorize, nothing consumed)", async () => {
             const api = createMockApi({
-                extent: { transactions: 10, bytes: 1_000_000n },
+                extent: {
+                    transactions: 0,
+                    transactions_allowance: 10,
+                    bytes: 0n,
+                    bytes_permanent: 0n,
+                    bytes_allowance: 1_000_000n,
+                },
                 expiration: 999,
             });
             const status = await checkAuthorization(api, "5GrwvaEF...");
@@ -119,9 +273,15 @@ if (import.meta.vitest) {
             expect(status.expiration).toBe(999);
         });
 
-        test("returns authorization with zero transactions remaining", async () => {
+        test("returns authorization with zero transactions remaining (fully consumed)", async () => {
             const api = createMockApi({
-                extent: { transactions: 0, bytes: 1_000_000n },
+                extent: {
+                    transactions: 5,
+                    transactions_allowance: 5,
+                    bytes: 0n,
+                    bytes_permanent: 0n,
+                    bytes_allowance: 1_000_000n,
+                },
                 expiration: 999,
             });
             const status = await checkAuthorization(api, "5GrwvaEF...");
@@ -130,9 +290,15 @@ if (import.meta.vitest) {
             expect(status.remainingTransactions).toBe(0);
         });
 
-        test("returns authorization with zero bytes remaining", async () => {
+        test("returns authorization with zero bytes remaining (fully consumed)", async () => {
             const api = createMockApi({
-                extent: { transactions: 5, bytes: 0n },
+                extent: {
+                    transactions: 0,
+                    transactions_allowance: 5,
+                    bytes: 1_000n,
+                    bytes_permanent: 0n,
+                    bytes_allowance: 1_000n,
+                },
                 expiration: 999,
             });
             const status = await checkAuthorization(api, "5GrwvaEF...");
@@ -141,9 +307,33 @@ if (import.meta.vitest) {
             expect(status.remainingBytes).toBe(0n);
         });
 
+        test("returns remaining = allowance − consumed when partially used", async () => {
+            const api = createMockApi({
+                extent: {
+                    transactions: 3,
+                    transactions_allowance: 10,
+                    bytes: 250_000n,
+                    bytes_permanent: 0n,
+                    bytes_allowance: 1_000_000n,
+                },
+                expiration: 999,
+            });
+            const status = await checkAuthorization(api, "5GrwvaEF...");
+
+            expect(status.authorized).toBe(true);
+            expect(status.remainingTransactions).toBe(7); // 10 − 3
+            expect(status.remainingBytes).toBe(750_000n); // 1M − 250K
+        });
+
         test("preserves expiration block number", async () => {
             const api = createMockApi({
-                extent: { transactions: 1, bytes: 500n },
+                extent: {
+                    transactions: 0,
+                    transactions_allowance: 1,
+                    bytes: 0n,
+                    bytes_permanent: 0n,
+                    bytes_allowance: 500n,
+                },
                 expiration: 12345,
             });
             const status = await checkAuthorization(api, "5GrwvaEF...");
@@ -188,4 +378,163 @@ if (import.meta.vitest) {
             expect(arg.value).toBe("5GrwvaEF...");
         });
     });
+
+    /**
+     * Mock factory for `authorizeAccount` tests.
+     *
+     * Mirrors the mocking style used in `upload.ts` — we don't mock
+     * `submitAndWatch` (the SDK helper) directly. Instead we let it call
+     * through to a fake `signSubmitAndWatch` on the api, which emits the
+     * lifecycle events `submitAndWatch` listens for.
+     */
+    function createMockApiForAuthorize(blockHash = "0xblockhash") {
+        const fakeTx = {
+            decodedCall: { fakeCall: true } as unknown,
+            signSubmitAndWatch: vi.fn().mockReturnValue({
+                subscribe: (handlers: { next: (e: unknown) => void }) => {
+                    queueMicrotask(() => {
+                        handlers.next({ type: "signed", txHash: "0xtxhash" });
+                        handlers.next({
+                            type: "txBestBlocksState",
+                            txHash: "0xtxhash",
+                            found: true,
+                            ok: true,
+                            block: { hash: blockHash, number: 1, index: 0 },
+                            events: [],
+                        });
+                    });
+                    return { unsubscribe: vi.fn() };
+                },
+            }),
+        };
+
+        return {
+            api: {
+                tx: {
+                    TransactionStorage: {
+                        authorize_account: vi.fn().mockReturnValue(fakeTx),
+                    },
+                    Sudo: {
+                        sudo: vi.fn().mockReturnValue(fakeTx),
+                    },
+                },
+            },
+            fakeTx,
+        };
+    }
+
+    const mockSigner = {} as PolkadotSigner;
+
+    describe("authorizeAccount", () => {
+        test("direct path: calls TransactionStorage.authorize_account with the right params", async () => {
+            const { api } = createMockApiForAuthorize();
+
+            await authorizeAccount(
+                api as unknown as BulletinApi,
+                "5GrwvaEF...",
+                100,
+                1_000_000n,
+                mockSigner,
+            );
+
+            expect(api.tx.TransactionStorage.authorize_account).toHaveBeenCalledOnce();
+            const arg = api.tx.TransactionStorage.authorize_account.mock.calls[0][0];
+            expect(arg.who).toBe("5GrwvaEF...");
+            expect(arg.transactions).toBe(100);
+            expect(arg.bytes).toBe(1_000_000n);
+        });
+
+        test("direct path: does NOT call Sudo.sudo when viaSudo is false (default)", async () => {
+            const { api } = createMockApiForAuthorize();
+
+            await authorizeAccount(
+                api as unknown as BulletinApi,
+                "5GrwvaEF...",
+                10,
+                100n,
+                mockSigner,
+            );
+
+            expect(api.tx.Sudo.sudo).not.toHaveBeenCalled();
+        });
+
+        test("direct path: returns the block hash from submission", async () => {
+            const { api } = createMockApiForAuthorize("0xdeadbeef");
+
+            const result = await authorizeAccount(
+                api as unknown as BulletinApi,
+                "5GrwvaEF...",
+                10,
+                100n,
+                mockSigner,
+            );
+
+            expect(result).toEqual({ blockHash: "0xdeadbeef" });
+        });
+
+        test("sudo path: wraps the authorize_account call inside Sudo.sudo", async () => {
+            const { api, fakeTx } = createMockApiForAuthorize();
+
+            await authorizeAccount(
+                api as unknown as BulletinApi,
+                "5GrwvaEF...",
+                10,
+                100n,
+                mockSigner,
+                { viaSudo: true },
+            );
+
+            expect(api.tx.Sudo.sudo).toHaveBeenCalledOnce();
+            const sudoArg = api.tx.Sudo.sudo.mock.calls[0][0];
+            expect(sudoArg.call).toBe(fakeTx.decodedCall);
+        });
+
+        test("sudo path: still returns the block hash from the sudo extrinsic", async () => {
+            const { api } = createMockApiForAuthorize("0xsudoblock");
+
+            const result = await authorizeAccount(
+                api as unknown as BulletinApi,
+                "5GrwvaEF...",
+                10,
+                100n,
+                mockSigner,
+                { viaSudo: true },
+            );
+
+            expect(result).toEqual({ blockHash: "0xsudoblock" });
+        });
+
+        test("throws ProductBulletinError when viaSudo is true but the chain lacks a Sudo pallet", async () => {
+            const apiWithoutSudo = {
+                tx: {
+                    TransactionStorage: {
+                        authorize_account: vi.fn().mockReturnValue({
+                            decodedCall: {} as unknown,
+                            signSubmitAndWatch: vi.fn(),
+                        }),
+                    },
+                    // Sudo intentionally absent — represents production Polkadot/Kusama
+                },
+            };
+
+            const err = await authorizeAccount(
+                apiWithoutSudo as unknown as BulletinApi,
+                "5GrwvaEF...",
+                10,
+                100n,
+                mockSigner,
+                { viaSudo: true },
+            ).catch((e: unknown) => e);
+
+            expect(err).toBeInstanceOf(ProductBulletinError);
+            expect((err as Error).message).toMatch(/Sudo pallet/i);
+            // Verify we did NOT proceed to submit anything
+            expect(apiWithoutSudo.tx.TransactionStorage.authorize_account).not.toHaveBeenCalled();
+        });
+
+        // Note: submission-failure propagation is tested upstream in
+        // @parity/product-sdk-tx's own suite. Re-testing it here would just
+        // re-test submitAndWatch's error path through a brittle mock, which
+        // depends on internal event-shape details outside this file's contract.
+    });
 }