@poa-box/core 0.1.0

package/dist/tx/user.d.ts

@@ -0,0 +1,177 @@
+/**
+ * User write builders — UniversalAccountRegistry (registerAccount /
+ * changeUsername / setProfileMetadata) and QuickJoinNew (quickJoinWithUser /
+ * claimHatsWithUser).
+ *
+ * Level 1: pure, sync builders taking resolved addresses + prepared values.
+ * Level 2: async `<action>Intent(ctx, params)` builders that resolve the
+ * registry / QuickJoin address via the subgraph, merge + pin profile
+ * metadata, and delegate to Level 1.
+ *
+ * Chain semantics (preserved CLI behavior): usernames and profile metadata
+ * are HOME-CHAIN account-registry state, so the registry-scoped Level-2
+ * builders default to HOME_CHAIN_ID — deliberately IGNORING ctx.chainId (the
+ * CLI ignores POP_DEFAULT_CHAIN the same way; an explicit `chainId` param
+ * wins). The org-scoped QuickJoin builders use ctx.chainId as usual.
+ *
+ * NOT ported (CLI-side revert prediction / flow UX): checkUsernameFree,
+ * AccountUnknown prediction, the live re-read of quickJoin.accountRegistry()
+ * before a 2-tx join (a write-target pointer that updateAddresses can
+ * re-point — see src/commands/user/join.ts), and the claim-hats Multicall3
+ * probes (NoUsername / MAX_HATS_PER_MINT / HatOpenlyClaimable sentinel).
+ */
+import { ethers } from 'ethers';
+import type { TxIntent } from './intent';
+import type { PopContext } from '../context';
+import { UserProfileUpdates } from '../metadata/user';
+/**
+ * Parse a comma-separated hat-ID list into BigNumbers. Accepts decimal and
+ * 0x-hex forms. Hats Protocol IDs are uint256 — far beyond 2^53 — so
+ * parseInt/Number would silently corrupt them.
+ * Port of parseHatIds in `pop user claim-hats` —
+ * src/commands/user/claim-hats.ts (same messages and exit codes).
+ */
+export declare function parseHatIds(input: string): ethers.BigNumber[];
+export interface RegisterAccountArgs {
+    /** UniversalAccountRegistry address (home chain unless overridden). */
+    registryAddress: string;
+    /** Validated username (3-32 alphanumeric+underscore — requireValidUsername). */
+    username: string;
+}
+/**
+ * Port of `pop user register` — src/commands/user/register.ts (also tx 1 of
+ * the 2-tx `pop user join` flow — src/commands/user/join.ts).
+ * UniversalAccountRegistry.registerAccount(string username); reverts
+ * UsernameTaken when the name is held. For the join flow, register on the
+ * SAME registry the org's QuickJoin consults (quickJoin.accountRegistry(),
+ * re-read live in the CLI) — registering anywhere else leaves
+ * quickJoinWithUser reverting NoUsername.
+ */
+export declare function buildRegisterAccount(a: RegisterAccountArgs): TxIntent;
+export interface ChangeUsernameArgs {
+    registryAddress: string;
+    /** Validated new username. */
+    newUsername: string;
+}
+/**
+ * Port of `pop user update-profile --username` —
+ * src/commands/user/update-profile.ts.
+ * UniversalAccountRegistry.changeUsername(string newUsername) — DESTRUCTIVE:
+ * the old username is released for anyone to claim the moment the tx lands.
+ * Reverts AccountUnknown without an existing registration and UsernameTaken
+ * when the new name is held.
+ */
+export declare function buildChangeUsername(a: ChangeUsernameArgs): TxIntent;
+export interface SetProfileMetadataArgs {
+    registryAddress: string;
+    /** bytes32 metadata hash — ipfsCidToBytes32 of the pinned profile document. */
+    metadataHash: string;
+}
+/**
+ * Port of the metadata tx of `pop user update-profile` —
+ * src/commands/user/update-profile.ts.
+ * UniversalAccountRegistry.setProfileMetadata(bytes32 metadataHash), where
+ * metadataHash = ipfsCidToBytes32(pinJson(serialized profile document)).
+ */
+export declare function buildSetProfileMetadata(a: SetProfileMetadataArgs): TxIntent;
+export interface QuickJoinWithUserArgs {
+    quickJoinAddress: string;
+    orgId?: string;
+}
+/**
+ * Port of `pop user join` (the join tx) — src/commands/user/join.ts.
+ * QuickJoinNew.quickJoinWithUser() — NO arguments. The contract reads
+ * accountRegistry.getUsername(msg.sender) and reverts NoUsername when it is
+ * empty, so the sender must already hold a username on the registry this
+ * QuickJoin consults (register first via buildRegisterAccount when needed).
+ */
+export declare function buildQuickJoinWithUser(a: QuickJoinWithUserArgs): TxIntent;
+export interface ClaimHatsWithUserArgs {
+    quickJoinAddress: string;
+    /** uint256 hat IDs — parse strings with parseHatIds, never parseInt. */
+    hatIds: ethers.BigNumber[];
+    orgId?: string;
+}
+/**
+ * Port of `pop user claim-hats` — src/commands/user/claim-hats.ts.
+ * QuickJoinNew.claimHatsWithUser(uint256[] claimHatIds). The caller must
+ * already have a username (reverts NoUsername); since audit H-03 QuickJoin
+ * refuses openly-claimable hats (reverts HatOpenlyClaimable), and the
+ * executor bounds the batch at MAX_HATS_PER_MINT.
+ */
+export declare function buildClaimHatsWithUser(a: ClaimHatsWithUserArgs): TxIntent;
+export interface RegisterAccountParams {
+    username: string;
+    /** Registry chain. Defaults to HOME_CHAIN_ID (Arbitrum) — NOT ctx.chainId. */
+    chainId?: number;
+}
+/**
+ * Resolved builder for `pop user register` — src/commands/user/register.ts.
+ * Validates the username, resolves the UniversalAccountRegistry address from
+ * the infrastructure subgraph (universalAccountRegistries[0].id, falling back
+ * to poaManagerContracts[0].globalAccountRegistryProxy), then builds the
+ * registerAccount intent. Defaults to the HOME chain, deliberately ignoring
+ * ctx.chainId — usernames live on the home chain (the CLI ignores
+ * POP_DEFAULT_CHAIN the same way).
+ */
+export declare function registerAccountIntent(ctx: PopContext, params: RegisterAccountParams): Promise<TxIntent>;
+export interface ChangeUsernameParams {
+    /** The account being renamed (the eventual tx sender). */
+    address: string;
+    newUsername: string;
+    /** Registry chain. Defaults to HOME_CHAIN_ID — NOT ctx.chainId. */
+    chainId?: number;
+}
+/**
+ * Resolved builder for the username tx of `pop user update-profile` —
+ * src/commands/user/update-profile.ts. DESTRUCTIVE: the old username is
+ * released on-chain for anyone to claim. Resolves the registry from the same
+ * one-round-trip document the CLI uses. The CLI's AccountUnknown /
+ * UsernameTaken / no-op-rename predictions are preflight and are not ported.
+ */
+export declare function changeUsernameIntent(ctx: PopContext, params: ChangeUsernameParams): Promise<TxIntent>;
+export interface SetProfileMetadataParams extends UserProfileUpdates {
+    /** The account whose profile is being updated (the eventual tx sender). */
+    address: string;
+    /** Registry chain. Defaults to HOME_CHAIN_ID — NOT ctx.chainId. */
+    chainId?: number;
+}
+/**
+ * Resolved builder for the metadata tx of `pop user update-profile` —
+ * src/commands/user/update-profile.ts. Reads the existing indexed profile
+ * metadata (read-then-merge, so single-field edits preserve the others),
+ * builds the {bio, avatar, github, twitter, website} document with the CLI's
+ * exact conditional key order, pins it to IPFS, converts the CID to bytes32,
+ * and builds the setProfileMetadata intent.
+ */
+export declare function setProfileMetadataIntent(ctx: PopContext, params: SetProfileMetadataParams): Promise<TxIntent>;
+export interface QuickJoinParams {
+    /** Org name or hex ID. */
+    org: string;
+}
+/**
+ * Resolved builder for `pop user join` (join tx only) —
+ * src/commands/user/join.ts. Resolves the org's QuickJoin via the subgraph
+ * and builds the quickJoinWithUser intent. The 1-tx vs 2-tx decision (does
+ * the sender already hold a username on the registry this QuickJoin
+ * consults?) is host orchestration: read state with
+ * reads/user.getQuickJoinAccount, re-verify the registry pointer LIVE
+ * (quickJoin.accountRegistry() — it is a write target updateAddresses can
+ * re-point), and when registration is needed send buildRegisterAccount
+ * against THAT registry first.
+ */
+export declare function quickJoinWithUserIntent(ctx: PopContext, params: QuickJoinParams): Promise<TxIntent>;
+export interface ClaimHatsParams {
+    /** Org name or hex ID. */
+    org: string;
+    /** Comma-separated hat-ID string (as the CLI's --hats), or pre-parsed IDs. */
+    hats: string | Array<string | ethers.BigNumberish>;
+}
+/**
+ * Resolved builder for `pop user claim-hats` —
+ * src/commands/user/claim-hats.ts. Parses hat IDs with BigNumber (uint256 —
+ * never parseInt), resolves the org's QuickJoin via the subgraph, and builds
+ * the claimHatsWithUser intent. The CLI's Multicall3 preflight (NoUsername /
+ * batch cap / open-hat sentinel probes) stays in the CLI.
+ */
+export declare function claimHatsWithUserIntent(ctx: PopContext, params: ClaimHatsParams): Promise<TxIntent>;

package/dist/tx/user.js

@@ -0,0 +1,292 @@
+"use strict";
+/**
+ * User write builders — UniversalAccountRegistry (registerAccount /
+ * changeUsername / setProfileMetadata) and QuickJoinNew (quickJoinWithUser /
+ * claimHatsWithUser).
+ *
+ * Level 1: pure, sync builders taking resolved addresses + prepared values.
+ * Level 2: async `<action>Intent(ctx, params)` builders that resolve the
+ * registry / QuickJoin address via the subgraph, merge + pin profile
+ * metadata, and delegate to Level 1.
+ *
+ * Chain semantics (preserved CLI behavior): usernames and profile metadata
+ * are HOME-CHAIN account-registry state, so the registry-scoped Level-2
+ * builders default to HOME_CHAIN_ID — deliberately IGNORING ctx.chainId (the
+ * CLI ignores POP_DEFAULT_CHAIN the same way; an explicit `chainId` param
+ * wins). The org-scoped QuickJoin builders use ctx.chainId as usual.
+ *
+ * NOT ported (CLI-side revert prediction / flow UX): checkUsernameFree,
+ * AccountUnknown prediction, the live re-read of quickJoin.accountRegistry()
+ * before a 2-tx join (a write-target pointer that updateAddresses can
+ * re-point — see src/commands/user/join.ts), and the claim-hats Multicall3
+ * probes (NoUsername / MAX_HATS_PER_MINT / HatOpenlyClaimable sentinel).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseHatIds = parseHatIds;
+exports.buildRegisterAccount = buildRegisterAccount;
+exports.buildChangeUsername = buildChangeUsername;
+exports.buildSetProfileMetadata = buildSetProfileMetadata;
+exports.buildQuickJoinWithUser = buildQuickJoinWithUser;
+exports.buildClaimHatsWithUser = buildClaimHatsWithUser;
+exports.registerAccountIntent = registerAccountIntent;
+exports.changeUsernameIntent = changeUsernameIntent;
+exports.setProfileMetadataIntent = setProfileMetadataIntent;
+exports.quickJoinWithUserIntent = quickJoinWithUserIntent;
+exports.claimHatsWithUserIntent = claimHatsWithUserIntent;
+const ethers_1 = require("ethers");
+const contracts_1 = require("../contracts");
+const ipfs_1 = require("../ipfs");
+const encoding_1 = require("../encoding");
+const validation_1 = require("../validation");
+const chains_1 = require("../chains");
+const errors_1 = require("../errors");
+const exit_codes_1 = require("../exit-codes");
+const infrastructure_1 = require("../graph/documents/infrastructure");
+const user_1 = require("../metadata/user");
+const resolve_1 = require("../reads/resolve");
+const user_2 = require("../reads/user");
+/**
+ * Parse a comma-separated hat-ID list into BigNumbers. Accepts decimal and
+ * 0x-hex forms. Hats Protocol IDs are uint256 — far beyond 2^53 — so
+ * parseInt/Number would silently corrupt them.
+ * Port of parseHatIds in `pop user claim-hats` —
+ * src/commands/user/claim-hats.ts (same messages and exit codes).
+ */
+function parseHatIds(input) {
+    const parts = String(input).split(',').map(part => part.trim()).filter(part => part.length > 0);
+    if (parts.length === 0) {
+        throw new errors_1.CliError('No hat IDs given.', exit_codes_1.EXIT.USAGE, 'Pass --hats <id>[,<id>...] (see pop org roles for hat IDs).');
+    }
+    return parts.map(part => {
+        try {
+            return ethers_1.ethers.BigNumber.from(part);
+        }
+        catch {
+            throw new errors_1.CliError(`Invalid hat ID "${part}".`, exit_codes_1.EXIT.USAGE, 'Hat IDs are uint256 integers — pass them as decimal or 0x-hex strings (see pop org roles).');
+        }
+    });
+}
+/**
+ * Port of `pop user register` — src/commands/user/register.ts (also tx 1 of
+ * the 2-tx `pop user join` flow — src/commands/user/join.ts).
+ * UniversalAccountRegistry.registerAccount(string username); reverts
+ * UsernameTaken when the name is held. For the join flow, register on the
+ * SAME registry the org's QuickJoin consults (quickJoin.accountRegistry(),
+ * re-read live in the CLI) — registering anywhere else leaves
+ * quickJoinWithUser reverting NoUsername.
+ */
+function buildRegisterAccount(a) {
+    return {
+        to: a.registryAddress,
+        abi: (0, contracts_1.getAbi)('UniversalAccountRegistry'),
+        method: 'registerAccount',
+        args: [a.username],
+        meta: {
+            domain: 'user',
+            action: 'register',
+            summary: { username: a.username, registry: a.registryAddress },
+        },
+    };
+}
+/**
+ * Port of `pop user update-profile --username` —
+ * src/commands/user/update-profile.ts.
+ * UniversalAccountRegistry.changeUsername(string newUsername) — DESTRUCTIVE:
+ * the old username is released for anyone to claim the moment the tx lands.
+ * Reverts AccountUnknown without an existing registration and UsernameTaken
+ * when the new name is held.
+ */
+function buildChangeUsername(a) {
+    return {
+        to: a.registryAddress,
+        abi: (0, contracts_1.getAbi)('UniversalAccountRegistry'),
+        method: 'changeUsername',
+        args: [a.newUsername],
+        meta: {
+            domain: 'user',
+            action: 'change-username',
+            summary: { username: a.newUsername, registry: a.registryAddress },
+        },
+    };
+}
+/**
+ * Port of the metadata tx of `pop user update-profile` —
+ * src/commands/user/update-profile.ts.
+ * UniversalAccountRegistry.setProfileMetadata(bytes32 metadataHash), where
+ * metadataHash = ipfsCidToBytes32(pinJson(serialized profile document)).
+ */
+function buildSetProfileMetadata(a) {
+    return {
+        to: a.registryAddress,
+        abi: (0, contracts_1.getAbi)('UniversalAccountRegistry'),
+        method: 'setProfileMetadata',
+        args: [a.metadataHash],
+        meta: {
+            domain: 'user',
+            action: 'set-profile-metadata',
+            summary: { metadataHash: a.metadataHash, registry: a.registryAddress },
+        },
+    };
+}
+/**
+ * Port of `pop user join` (the join tx) — src/commands/user/join.ts.
+ * QuickJoinNew.quickJoinWithUser() — NO arguments. The contract reads
+ * accountRegistry.getUsername(msg.sender) and reverts NoUsername when it is
+ * empty, so the sender must already hold a username on the registry this
+ * QuickJoin consults (register first via buildRegisterAccount when needed).
+ */
+function buildQuickJoinWithUser(a) {
+    return {
+        to: a.quickJoinAddress,
+        abi: (0, contracts_1.getAbi)('QuickJoinNew'),
+        method: 'quickJoinWithUser',
+        args: [],
+        meta: {
+            domain: 'user',
+            action: 'join',
+            orgId: a.orgId,
+            summary: {},
+        },
+    };
+}
+/**
+ * Port of `pop user claim-hats` — src/commands/user/claim-hats.ts.
+ * QuickJoinNew.claimHatsWithUser(uint256[] claimHatIds). The caller must
+ * already have a username (reverts NoUsername); since audit H-03 QuickJoin
+ * refuses openly-claimable hats (reverts HatOpenlyClaimable), and the
+ * executor bounds the batch at MAX_HATS_PER_MINT.
+ */
+function buildClaimHatsWithUser(a) {
+    return {
+        to: a.quickJoinAddress,
+        abi: (0, contracts_1.getAbi)('QuickJoinNew'),
+        method: 'claimHatsWithUser',
+        args: [a.hatIds],
+        meta: {
+            domain: 'user',
+            action: 'claim-hats',
+            orgId: a.orgId,
+            summary: { hatIds: a.hatIds.map(id => id.toString()).join(',') },
+        },
+    };
+}
+// ──────────────────────────── Level 2 — resolved ───────────────────────────
+/** Validate a username with the CLI's wrapping (usage error, not a bare throw). */
+function requireUsernameArg(username) {
+    try {
+        return (0, validation_1.requireValidUsername)(username);
+    }
+    catch (err) {
+        throw new errors_1.CliError(err.message, exit_codes_1.EXIT.USAGE);
+    }
+}
+/**
+ * Resolved builder for `pop user register` — src/commands/user/register.ts.
+ * Validates the username, resolves the UniversalAccountRegistry address from
+ * the infrastructure subgraph (universalAccountRegistries[0].id, falling back
+ * to poaManagerContracts[0].globalAccountRegistryProxy), then builds the
+ * registerAccount intent. Defaults to the HOME chain, deliberately ignoring
+ * ctx.chainId — usernames live on the home chain (the CLI ignores
+ * POP_DEFAULT_CHAIN the same way).
+ */
+async function registerAccountIntent(ctx, params) {
+    const username = requireUsernameArg(params.username);
+    const chainId = params.chainId || chains_1.HOME_CHAIN_ID;
+    const infra = await ctx.client.query(infrastructure_1.FETCH_INFRASTRUCTURE_ADDRESSES, {}, chainId);
+    const registryAddr = infra.universalAccountRegistries?.[0]?.id
+        || infra.poaManagerContracts?.[0]?.globalAccountRegistryProxy;
+    if (!registryAddr) {
+        throw new errors_1.CliError('Could not resolve the UniversalAccountRegistry address from the subgraph.', exit_codes_1.EXIT.INFRA, 'The subgraph may be syncing — retry shortly, or pass --chain for a chain with a deployed registry.');
+    }
+    return buildRegisterAccount({ registryAddress: registryAddr, username });
+}
+/**
+ * Resolved builder for the username tx of `pop user update-profile` —
+ * src/commands/user/update-profile.ts. DESTRUCTIVE: the old username is
+ * released on-chain for anyone to claim. Resolves the registry from the same
+ * one-round-trip document the CLI uses. The CLI's AccountUnknown /
+ * UsernameTaken / no-op-rename predictions are preflight and are not ported.
+ */
+async function changeUsernameIntent(ctx, params) {
+    const newUsername = requireUsernameArg(params.newUsername);
+    const chainId = params.chainId ?? chains_1.HOME_CHAIN_ID;
+    const { registryAddress } = await (0, user_2.getRegistryAndAccount)(ctx.client, params.address, chainId);
+    if (!registryAddress) {
+        throw new errors_1.CliError('UniversalAccountRegistry not found on this chain.', exit_codes_1.EXIT.INFRA, 'The subgraph may be syncing — retry shortly.');
+    }
+    return buildChangeUsername({ registryAddress, newUsername });
+}
+/**
+ * Resolved builder for the metadata tx of `pop user update-profile` —
+ * src/commands/user/update-profile.ts. Reads the existing indexed profile
+ * metadata (read-then-merge, so single-field edits preserve the others),
+ * builds the {bio, avatar, github, twitter, website} document with the CLI's
+ * exact conditional key order, pins it to IPFS, converts the CID to bytes32,
+ * and builds the setProfileMetadata intent.
+ */
+async function setProfileMetadataIntent(ctx, params) {
+    const updates = {
+        bio: params.bio,
+        avatar: params.avatar,
+        github: params.github,
+        twitter: params.twitter,
+        website: params.website,
+    };
+    if (!user_1.USER_PROFILE_FIELDS.some(field => updates[field] !== undefined)) {
+        throw new errors_1.CliError('Provide at least one field: --bio, --avatar, --github, --twitter, --website', exit_codes_1.EXIT.USAGE);
+    }
+    const chainId = params.chainId ?? chains_1.HOME_CHAIN_ID;
+    const { registryAddress, account } = await (0, user_2.getRegistryAndAccount)(ctx.client, params.address, chainId);
+    if (!registryAddress) {
+        throw new errors_1.CliError('UniversalAccountRegistry not found on this chain.', exit_codes_1.EXIT.INFRA, 'The subgraph may be syncing — retry shortly.');
+    }
+    // Merge over the indexed metadata exactly as the CLI does
+    // (indexed.account?.metadata || {} — no authority gating on the merge read).
+    const metadata = (0, user_1.buildUserProfileMetadata)(updates, account?.metadata ?? {});
+    const cid = await (0, ipfs_1.pinJson)((0, user_1.serializeUserProfileMetadata)(metadata), ctx.ipfs);
+    const metadataHash = (0, encoding_1.ipfsCidToBytes32)(cid);
+    const intent = buildSetProfileMetadata({ registryAddress, metadataHash });
+    intent.meta.ipfs = { cid, metadata };
+    return intent;
+}
+/**
+ * Resolved builder for `pop user join` (join tx only) —
+ * src/commands/user/join.ts. Resolves the org's QuickJoin via the subgraph
+ * and builds the quickJoinWithUser intent. The 1-tx vs 2-tx decision (does
+ * the sender already hold a username on the registry this QuickJoin
+ * consults?) is host orchestration: read state with
+ * reads/user.getQuickJoinAccount, re-verify the registry pointer LIVE
+ * (quickJoin.accountRegistry() — it is a write target updateAddresses can
+ * re-point), and when registration is needed send buildRegisterAccount
+ * against THAT registry first.
+ */
+async function quickJoinWithUserIntent(ctx, params) {
+    const modules = await (0, resolve_1.resolveOrgModules)(ctx.client, params.org, ctx.chainId);
+    const quickJoinAddress = (0, resolve_1.requireModule)(modules, 'quickJoinAddress');
+    return buildQuickJoinWithUser({ quickJoinAddress, orgId: modules.orgId });
+}
+/**
+ * Resolved builder for `pop user claim-hats` —
+ * src/commands/user/claim-hats.ts. Parses hat IDs with BigNumber (uint256 —
+ * never parseInt), resolves the org's QuickJoin via the subgraph, and builds
+ * the claimHatsWithUser intent. The CLI's Multicall3 preflight (NoUsername /
+ * batch cap / open-hat sentinel probes) stays in the CLI.
+ */
+async function claimHatsWithUserIntent(ctx, params) {
+    const hatIds = typeof params.hats === 'string'
+        ? parseHatIds(params.hats)
+        : params.hats.map(part => {
+            try {
+                return ethers_1.ethers.BigNumber.from(part);
+            }
+            catch {
+                throw new errors_1.CliError(`Invalid hat ID "${part}".`, exit_codes_1.EXIT.USAGE, 'Hat IDs are uint256 integers — pass them as decimal or 0x-hex strings (see pop org roles).');
+            }
+        });
+    if (hatIds.length === 0) {
+        throw new errors_1.CliError('No hat IDs given.', exit_codes_1.EXIT.USAGE, 'Pass --hats <id>[,<id>...] (see pop org roles for hat IDs).');
+    }
+    const modules = await (0, resolve_1.resolveOrgModules)(ctx.client, params.org, ctx.chainId);
+    const quickJoinAddress = (0, resolve_1.requireModule)(modules, 'quickJoinAddress');
+    return buildClaimHatsWithUser({ quickJoinAddress, hatIds, orgId: modules.orgId });
+}