@poa-box/core 0.1.0

package/dist/tx/org.js

@@ -0,0 +1,544 @@
+"use strict";
+/**
+ * Org write builders.
+ *
+ * Ports:
+ *   - `pop org deploy`             — src/commands/org/deploy.ts
+ *   - `pop org update-metadata`    — src/commands/org/update-metadata.ts
+ *   - `pop org set-metadata-admin` — src/commands/org/set-metadata-admin.ts
+ *
+ * Level-1 builders are pure (sync, zero I/O) and own ALL argument encoding.
+ * Level-2 `<action>Intent(ctx, params)` builders resolve addresses via the
+ * subgraph, pin metadata to IPFS, and delegate to Level 1.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEPLOY_FULL_ORG_GAS_LIMIT = exports.REGISTER_ACCOUNT_TYPES = void 0;
+exports.indicesToBitmap = indicesToBitmap;
+exports.assertRoleIndices = assertRoleIndices;
+exports.deriveOrgId = deriveOrgId;
+exports.registerAccountDomain = registerAccountDomain;
+exports.signRegisterAccount = signRegisterAccount;
+exports.buildDeploymentParams = buildDeploymentParams;
+exports.buildDeployFullOrg = buildDeployFullOrg;
+exports.deployFullOrgIntent = deployFullOrgIntent;
+exports.buildUpdateOrgMetaAsAdmin = buildUpdateOrgMetaAsAdmin;
+exports.updateOrgMetaIntent = updateOrgMetaIntent;
+exports.setMetadataAdminTitle = setMetadataAdminTitle;
+exports.buildSetMetadataAdminProposal = buildSetMetadataAdminProposal;
+exports.setMetadataAdminIntent = setMetadataAdminIntent;
+const ethers_1 = require("ethers");
+const contracts_1 = require("../contracts");
+const encoding_1 = require("../encoding");
+const ipfs_1 = require("../ipfs");
+const errors_1 = require("../errors");
+const exit_codes_1 = require("../exit-codes");
+const resolve_1 = require("../reads/resolve");
+const infrastructure_1 = require("../graph/documents/infrastructure");
+const org_1 = require("../graph/documents/org");
+const org_2 = require("../metadata/org");
+const proposal_1 = require("../metadata/proposal");
+const governance_1 = require("./governance");
+// ---------------------------------------------------------------------------
+// Shared infra resolution
+// ---------------------------------------------------------------------------
+/**
+ * OrgRegistry proxy address — global infrastructure, not an org module.
+ * Same lookup + error as `pop org update-metadata` / `pop org set-metadata-admin`.
+ */
+async function resolveOrgRegistryAddress(ctx) {
+    const infra = await ctx.client.query(infrastructure_1.FETCH_INFRASTRUCTURE_ADDRESSES, {}, ctx.chainId);
+    const orgRegistryAddr = infra.poaManagerContracts?.[0]?.orgRegistryProxy;
+    if (!orgRegistryAddr) {
+        throw new errors_1.CliError('Could not resolve OrgRegistry address from subgraph', exit_codes_1.EXIT.INFRA);
+    }
+    return orgRegistryAddr;
+}
+/** Port of indicesToBitmap in src/commands/org/deploy.ts. */
+function indicesToBitmap(indices) {
+    let bitmap = ethers_1.ethers.BigNumber.from(0);
+    for (const i of indices) {
+        bitmap = bitmap.or(ethers_1.ethers.BigNumber.from(1).shl(i));
+    }
+    return bitmap;
+}
+/**
+ * Reject role indices that do not name a role in the config.
+ *
+ * RoleResolver reverts UnregisteredRole(roleIdx) when a bitmap bit has no registered hat
+ * (audit M-09) — previously hat 0 was silently stored as an "authorized" hat and the deploy
+ * succeeded with a broken allowlist. Either way the config is wrong, and we know roles.length
+ * here, so name the offending field instead of surfacing a bare index from gas estimation
+ * (older deployers) or an aborted deploy (upgraded ones).
+ */
+function assertRoleIndices(field, indices, roleCount) {
+    for (const i of indices ?? []) {
+        if (!Number.isInteger(i) || i < 0 || i >= roleCount) {
+            throw new errors_1.CliError(`${field} references role index ${i}, but the config defines ${roleCount} role(s) (valid: 0-${roleCount - 1}).`, exit_codes_1.EXIT.USAGE, 'Role indices are positions in the config\'s `roles` array — renumber them after adding '
+                + 'or removing a role.');
+        }
+    }
+}
+/**
+ * Derive the deterministic orgId + normalized name the deployer uses:
+ * orgId = keccak256(orgName.toLowerCase().replace(/\s+/g, '-')).
+ * The normalized name is also the default deployer username.
+ */
+function deriveOrgId(orgName) {
+    const normalizedName = orgName.toLowerCase().replace(/\s+/g, '-');
+    return {
+        orgId: ethers_1.ethers.utils.keccak256(ethers_1.ethers.utils.toUtf8Bytes(normalizedName)),
+        normalizedName,
+    };
+}
+/** EIP-712 type set for UniversalAccountRegistry registration. */
+exports.REGISTER_ACCOUNT_TYPES = {
+    RegisterAccount: [
+        { name: 'user', type: 'address' },
+        { name: 'username', type: 'string' },
+        { name: 'nonce', type: 'uint256' },
+        { name: 'deadline', type: 'uint256' },
+    ],
+};
+/** EIP-712 domain for UniversalAccountRegistry registration. */
+function registerAccountDomain(chainId, registryAddress) {
+    return {
+        name: 'UniversalAccountRegistry',
+        version: '1',
+        chainId,
+        verifyingContract: registryAddress,
+    };
+}
+/**
+ * Port of the EIP-712 RegisterAccount signature step in `pop org deploy`
+ * (src/commands/org/deploy.ts): registration happens INSIDE deployFullOrg via
+ * this signature — it is not a separate tx. Kept as a separate function taking
+ * a Signer so hosts control key custody; everything else here is pure data.
+ */
+async function signRegisterAccount(signer, params) {
+    const domain = registerAccountDomain(params.chainId, params.registryAddress);
+    const message = {
+        user: params.user,
+        username: params.username,
+        nonce: ethers_1.ethers.BigNumber.from(params.nonce).toString(),
+        deadline: params.deadline,
+    };
+    return signer._signTypedData(domain, exports.REGISTER_ACCOUNT_TYPES, message);
+}
+/** Recommended gasLimit for deployFullOrg — the CLI always sends 15,000,000. */
+exports.DEPLOY_FULL_ORG_GAS_LIMIT = 15000000;
+/**
+ * Pure assembly of the DeploymentParams struct — port of the param build in
+ * `pop org deploy` (src/commands/org/deploy.ts:257-403), byte-for-byte the
+ * same encoding. Validates taskManagerPerms lengths and every roleAssignments
+ * index exactly like the CLI (both gate the broadcast).
+ *
+ * ABI field order (verified against src/abi/OrgDeployerNew.json +
+ * contracts origin/main src/OrgDeployer.sol DeploymentParams):
+ *   orgId, orgName, metadataHash, registryAddr, deployerAddress,
+ *   deployerUsername, regDeadline, regNonce, regSignature, autoUpgrade,
+ *   hybridThresholdPct, ddThresholdPct, hybridClasses, ddInitialTargets,
+ *   roles, roleAssignments, metadataAdminRoleIndex, passkeyEnabled,
+ *   educationHubConfig, bootstrap, paymasterConfig, taskManagerPerms
+ */
+function buildDeploymentParams(config, resolved) {
+    // Build hybrid voting classes
+    // ABI: strategy(uint8), slicePct(uint8), quadratic(bool), minBalance(uint256), asset(address), hatIds(uint256[])
+    const hybridClasses = config.hybridVoting.classes.map((c) => [
+        c.strategy === 'DIRECT' ? 0 : 1, // uint8
+        c.slicePct, // uint8 (0-100)
+        c.quadratic || false, // bool
+        c.minBalance ? ethers_1.ethers.utils.parseUnits(c.minBalance, 18) : 0, // uint256
+        c.asset || ethers_1.ethers.constants.AddressZero, // address
+        c.hatIds || [], // uint256[]
+    ]);
+    // Build role configs
+    // ABI: name(string), image(string), metadataCID(bytes32), canVote(bool),
+    //      vouching(tuple), defaults(tuple), hierarchy(tuple), distribution(tuple), hatConfig(tuple)
+    const MAX_UINT32 = 4294967295; // 2^32 - 1
+    const roles = config.roles.map((r) => [
+        r.name, // string
+        r.image || '', // string
+        ethers_1.ethers.constants.HashZero, // bytes32 metadataCID
+        r.canVote, // bool
+        [
+            r.vouching?.enabled || false,
+            r.vouching?.quorum || 0,
+            r.vouching?.voucherRoleIndex ?? ethers_1.ethers.constants.MaxUint256,
+            r.vouching?.combineWithHierarchy || false,
+        ],
+        [
+            r.defaults?.eligible ?? true,
+            r.defaults?.standing ?? true,
+        ],
+        [
+            r.hierarchy?.adminRoleIndex ?? ethers_1.ethers.constants.MaxUint256,
+        ],
+        [
+            r.distribution?.mintToDeployer ?? true,
+            r.distribution?.additionalWearers || [],
+        ],
+        [
+            r.hatConfig?.maxSupply ?? MAX_UINT32, // uint32, NOT uint256
+            r.hatConfig?.mutableHat ?? true,
+        ],
+    ]);
+    // Build role assignment bitmaps
+    const ra = config.roleAssignments;
+    // Every index must name a real role BEFORE anything is broadcast — a stale index is
+    // trivially produced by editing `roles` without renumbering `roleAssignments`.
+    const roleCount = config.roles.length;
+    assertRoleIndices('roleAssignments.quickJoinRoles', ra.quickJoinRoles, roleCount);
+    assertRoleIndices('roleAssignments.tokenMemberRoles', ra.tokenMemberRoles, roleCount);
+    assertRoleIndices('roleAssignments.tokenApproverRoles', ra.tokenApproverRoles, roleCount);
+    assertRoleIndices('roleAssignments.taskCreatorRoles', ra.taskCreatorRoles, roleCount);
+    assertRoleIndices('roleAssignments.educationCreatorRoles', ra.educationCreatorRoles, roleCount);
+    assertRoleIndices('roleAssignments.educationMemberRoles', ra.educationMemberRoles, roleCount);
+    assertRoleIndices('roleAssignments.hybridProposalCreatorRoles', ra.hybridProposalCreatorRoles, roleCount);
+    assertRoleIndices('roleAssignments.ddVotingRoles', ra.ddVotingRoles, roleCount);
+    assertRoleIndices('roleAssignments.ddCreatorRoles', ra.ddCreatorRoles, roleCount);
+    const roleAssignments = [
+        indicesToBitmap(ra.quickJoinRoles),
+        indicesToBitmap(ra.tokenMemberRoles),
+        indicesToBitmap(ra.tokenApproverRoles),
+        indicesToBitmap(ra.taskCreatorRoles),
+        indicesToBitmap(ra.educationCreatorRoles || []),
+        indicesToBitmap(ra.educationMemberRoles || []),
+        indicesToBitmap(ra.hybridProposalCreatorRoles),
+        indicesToBitmap(ra.ddVotingRoles),
+        indicesToBitmap(ra.ddCreatorRoles),
+    ];
+    // Build paymaster config
+    // ABI: operatorRoleIndex(uint256), autoWhitelistContracts(bool),
+    //      maxFeePerGas(uint256), maxPriorityFeePerGas(uint256),
+    //      maxCallGas(uint32), maxVerificationGas(uint32), maxPreVerificationGas(uint32),
+    //      defaultBudgetCapPerEpoch(uint128), defaultBudgetEpochLen(uint32)
+    const pm = config.paymaster;
+    const paymasterConfig = pm ? [
+        pm.operatorRoleIndex, // uint256
+        true, // bool
+        ethers_1.ethers.utils.parseUnits(pm.maxFeePerGas, 'gwei'), // uint256
+        ethers_1.ethers.utils.parseUnits(pm.maxPriorityFeePerGas, 'gwei'), // uint256
+        500000, // uint32 maxCallGas
+        500000, // uint32 maxVerificationGas
+        100000, // uint32 maxPreVerificationGas
+        ethers_1.ethers.utils.parseEther(pm.defaultBudgetCapPerEpoch), // uint128
+        pm.defaultBudgetEpochLen, // uint32
+    ] : [
+        ethers_1.ethers.constants.MaxUint256, // operatorRoleIndex = MaxUint256 disables paymaster
+        false, // autoWhitelistContracts
+        0, // maxFeePerGas
+        0, // maxPriorityFeePerGas
+        0, // maxCallGas
+        0, // maxVerificationGas
+        0, // maxPreVerificationGas
+        0, // defaultBudgetCapPerEpoch
+        0, // defaultBudgetEpochLen
+    ];
+    // Optional org-wide TaskManager ROLE_PERM grants
+    // (OrgDeployer.TaskManagerPermConfig: roleIndices[] + masks[] — empty
+    // arrays skip the bootstrapGlobalPerms step entirely; verified against
+    // contracts origin/main src/OrgDeployer.sol).
+    const tmPerms = config.taskManagerPerms;
+    if (tmPerms && (tmPerms.roleIndices?.length || 0) !== (tmPerms.masks?.length || 0)) {
+        throw new errors_1.CliError('Config invalid: taskManagerPerms.roleIndices and taskManagerPerms.masks must be the same length.', exit_codes_1.EXIT.USAGE);
+    }
+    const taskManagerPerms = [
+        tmPerms?.roleIndices || [], // uint256[] roleIndices
+        tmPerms?.masks || [], // uint8[] masks
+    ];
+    return [
+        resolved.orgId, // bytes32
+        config.orgName, // string
+        resolved.metadataHash, // bytes32
+        resolved.registryAddr, // address
+        resolved.deployerAddress, // address deployerAddress
+        resolved.deployerUsername, // string deployerUsername
+        resolved.regDeadline, // uint256
+        resolved.regNonce, // uint256
+        resolved.regSignature, // bytes
+        config.autoUpgrade ?? true, // bool
+        config.hybridVoting.thresholdPct, // uint8
+        config.directDemocracy?.thresholdPct || 51, // uint8
+        hybridClasses, // ClassConfig[]
+        [], // address[] ddInitialTargets
+        roles, // RoleConfig[]
+        roleAssignments, // RoleAssignments struct
+        config.metadataAdminRoleIndex ?? ethers_1.ethers.constants.MaxUint256, // uint256
+        true, // bool passkeyEnabled
+        [config.educationHub?.enabled ?? true], // EducationHubConfig struct
+        [[], []], // BootstrapConfig struct (projects, tasks)
+        paymasterConfig, // PaymasterConfig struct
+        taskManagerPerms, // TaskManagerPermConfig struct (roleIndices, masks)
+    ];
+}
+/**
+ * Port of `pop org deploy` — src/commands/org/deploy.ts.
+ * OrgDeployer.deployFullOrg([DeploymentParams]) — the single on-chain write,
+ * which internally deploys every org module (registration happens inside it
+ * via the EIP-712 signature carried in the params).
+ *
+ * NOTE: the CLI always sends this with gasLimit 15,000,000
+ * (DEPLOY_FULL_ORG_GAS_LIMIT) — pass it in the executor's options; TxIntent
+ * carries no gas policy.
+ */
+function buildDeployFullOrg(a) {
+    return {
+        to: a.orgDeployerAddress,
+        abi: (0, contracts_1.getAbi)('OrgDeployerNew'),
+        method: 'deployFullOrg',
+        args: [a.deployParams],
+        value: a.value,
+        meta: {
+            domain: 'org',
+            action: 'deploy',
+            orgId: a.orgId,
+            summary: {
+                orgId: a.orgId,
+                orgName: a.orgName,
+                gasLimit: exports.DEPLOY_FULL_ORG_GAS_LIMIT,
+            },
+        },
+    };
+}
+/**
+ * Resolved builder for `pop org deploy` — src/commands/org/deploy.ts.
+ *
+ * Performs the CLI's pre-steps in the same order: config validation,
+ * infrastructure address resolution (orgDeployerProxy +
+ * globalAccountRegistryProxy), org metadata pin, on-chain
+ * UniversalAccountRegistry.nonces() read (requires ctx.provider), and the
+ * EIP-712 RegisterAccount signature — then delegates to buildDeployFullOrg.
+ */
+async function deployFullOrgIntent(ctx, params) {
+    const config = params.config;
+    // ── Fail fast on config problems before any network work ───────────
+    if (!config.orgName)
+        throw new errors_1.CliError('Config missing: orgName', exit_codes_1.EXIT.USAGE);
+    if (!config.roles?.length)
+        throw new errors_1.CliError('Config missing: roles', exit_codes_1.EXIT.USAGE);
+    if (!config.hybridVoting)
+        throw new errors_1.CliError('Config missing: hybridVoting', exit_codes_1.EXIT.USAGE);
+    if (!ctx.provider) {
+        throw new errors_1.CliError('deployFullOrgIntent requires ctx.provider (UniversalAccountRegistry.nonces read)', exit_codes_1.EXIT.USAGE);
+    }
+    if (ctx.chainId === undefined) {
+        throw new errors_1.CliError('deployFullOrgIntent requires ctx.chainId (EIP-712 domain)', exit_codes_1.EXIT.USAGE);
+    }
+    // Resolve infrastructure addresses
+    const infra = await ctx.client.query(infrastructure_1.FETCH_INFRASTRUCTURE_ADDRESSES, {}, ctx.chainId);
+    const orgDeployerAddr = infra.poaManagerContracts?.[0]?.orgDeployerProxy;
+    const registryAddr = infra.poaManagerContracts?.[0]?.globalAccountRegistryProxy;
+    if (!orgDeployerAddr)
+        throw new errors_1.CliError('Could not resolve OrgDeployer address', exit_codes_1.EXIT.INFRA);
+    if (!registryAddr)
+        throw new errors_1.CliError('Could not resolve UniversalAccountRegistry address', exit_codes_1.EXIT.INFRA);
+    // Generate orgId: keccak256(orgName.toLowerCase().replace(/\s+/g, '-'))
+    const { orgId, normalizedName } = deriveOrgId(config.orgName);
+    const deployerUsername = config.deployerUsername || normalizedName;
+    // Upload org metadata to IPFS
+    const metadata = (0, org_2.buildOrgDeployMetadata)({
+        description: config.description,
+        links: config.links,
+    });
+    const metaCid = await (0, ipfs_1.pinJson)((0, org_2.serializeOrgMetadata)(metadata), ctx.ipfs);
+    const metadataHash = (0, encoding_1.ipfsCidToBytes32)(metaCid);
+    // Get registration nonce for deployer
+    const registryContract = (0, contracts_1.createReadContract)(registryAddr, 'UniversalAccountRegistry', ctx.provider);
+    const regNonce = await registryContract.nonces(params.deployerAddress);
+    // 15 min validity by default — see DeployFullOrgParams.regDeadline.
+    const regDeadline = params.regDeadline ?? Math.floor(Date.now() / 1000) + 900;
+    // Sign EIP-712 registration message
+    const regSignature = await signRegisterAccount(params.signer, {
+        registryAddress: registryAddr,
+        chainId: ctx.chainId,
+        user: params.deployerAddress,
+        username: deployerUsername,
+        nonce: regNonce,
+        deadline: regDeadline,
+    });
+    const deployParams = buildDeploymentParams(config, {
+        orgId,
+        metadataHash,
+        registryAddr,
+        deployerAddress: params.deployerAddress,
+        deployerUsername,
+        regDeadline,
+        regNonce,
+        regSignature,
+    });
+    const txValue = config.paymaster?.funding
+        ? ethers_1.ethers.utils.parseEther(config.paymaster.funding)
+        : undefined;
+    const intent = buildDeployFullOrg({
+        orgDeployerAddress: orgDeployerAddr,
+        deployParams,
+        value: txValue,
+        orgId,
+        orgName: config.orgName,
+    });
+    intent.meta.ipfs = { cid: metaCid, metadata };
+    return intent;
+}
+/**
+ * Port of `pop org update-metadata` — src/commands/org/update-metadata.ts.
+ * OrgRegistry.updateOrgMetaAsAdmin(orgId, stringToBytes(name), metadataHash).
+ * Caller must wear the org's metadata-admin hat (topHat fallback) — revert
+ * NotOrgMetadataAdmin otherwise. FULL OVERWRITE of name + metadata hash.
+ */
+function buildUpdateOrgMetaAsAdmin(a) {
+    return {
+        to: a.orgRegistryAddress,
+        abi: (0, contracts_1.getAbi)('OrgRegistry'),
+        method: 'updateOrgMetaAsAdmin',
+        args: [a.orgId, (0, encoding_1.stringToBytes)(a.name), a.metadataHash],
+        meta: {
+            domain: 'org',
+            action: 'update-metadata',
+            orgId: a.orgId,
+            summary: { name: a.name, metadataHash: a.metadataHash },
+        },
+    };
+}
+/**
+ * Resolved builder for `pop org update-metadata` — src/commands/org/update-metadata.ts.
+ *
+ * Merge base is the RAW IPFS doc (fetchJson of the current metadataHash),
+ * spread FIRST so unknown keys (e.g. zkEmailAllowlist) and frontend key order
+ * survive; refuses (INFRA) when IPFS is unreachable but the subgraph shows
+ * metadata exists — proceeding would drop any key the CLI does not model.
+ */
+async function updateOrgMetaIntent(ctx, params) {
+    if (!params.name && !params.description && !params.logo && !params.logoCid && !params.links
+        && params.backgroundColor === undefined && params.hideTreasury === undefined) {
+        throw new errors_1.CliError('At least one metadata field must be provided.', exit_codes_1.EXIT.USAGE, 'Available: --name, --description, --logo, --links, --background-color, --hide-treasury');
+    }
+    const orgId = await (0, resolve_1.resolveOrgId)(ctx.client, params.org, ctx.chainId);
+    // Resolve OrgRegistry address (global infrastructure, not an org module)
+    const orgRegistryAddr = await resolveOrgRegistryAddress(ctx);
+    // Fetch existing metadata to preserve fields not being updated.
+    const existing = await ctx.client.query(org_1.FETCH_ORG_FULL_DATA, { orgId }, ctx.chainId);
+    if (!existing.organization) {
+        throw new errors_1.CliError(`Organization ${orgId} is not indexed on this chain.`, exit_codes_1.EXIT.INFRA, 'This write overwrites the org name and metadata wholesale; refusing to send it against '
+            + 'an unknown org would otherwise blank both. Check --chain, or retry once indexed.');
+    }
+    const subgraphMeta = existing.organization.metadata || {};
+    const currentName = existing.organization.name || '';
+    const currentMetadataHash = existing.organization.metadataHash;
+    // The RAW IPFS doc — not the subgraph's typed projection — is the merge base
+    // (see mergeOrgMetadata for why).
+    let rawMeta = null;
+    if (currentMetadataHash && currentMetadataHash !== ethers_1.ethers.constants.HashZero) {
+        try {
+            rawMeta = await (0, ipfs_1.fetchJson)(currentMetadataHash, ctx.ipfs);
+        }
+        catch { /* handled below */ }
+    }
+    if (!rawMeta && Object.keys(subgraphMeta).length > 0) {
+        throw new errors_1.CliError('Could not fetch the org\'s current metadata from IPFS, so unknown fields cannot be preserved.', exit_codes_1.EXIT.INFRA, 'This write is a full overwrite — proceeding would drop any metadata key the CLI does not '
+            + 'model. Retry once IPFS responds.');
+    }
+    const currentMeta = rawMeta ?? subgraphMeta;
+    // Upload logo to IPFS if provided
+    let logoCid = params.logoCid ?? null;
+    if (params.logo) {
+        logoCid = await (0, ipfs_1.pinFile)(params.logo, ctx.ipfs);
+    }
+    const metadata = (0, org_2.mergeOrgMetadata)(currentMeta, {
+        description: params.description,
+        links: params.links,
+        logoCid,
+        backgroundColor: params.backgroundColor,
+        hideTreasury: params.hideTreasury,
+    });
+    // If name not provided, keep the current name (full-overwrite write).
+    const nameToSend = params.name || currentName;
+    const metaCid = await (0, ipfs_1.pinJson)((0, org_2.serializeOrgMetadata)(metadata), ctx.ipfs);
+    const metadataHash = (0, encoding_1.ipfsCidToBytes32)(metaCid);
+    const intent = buildUpdateOrgMetaAsAdmin({
+        orgRegistryAddress: orgRegistryAddr,
+        orgId,
+        name: nameToSend,
+        metadataHash,
+    });
+    intent.meta.ipfs = { cid: metaCid, metadata };
+    if (logoCid)
+        intent.meta.summary.logoCid = logoCid;
+    return intent;
+}
+/** The exact proposal title `pop org set-metadata-admin` uses. */
+function setMetadataAdminTitle(hatId) {
+    return `Set org metadata-admin hat to ${ethers_1.ethers.BigNumber.from(hatId).toString()}`;
+}
+/**
+ * Port of `pop org set-metadata-admin` — src/commands/org/set-metadata-admin.ts.
+ *
+ * setOrgMetadataAdminHat(bytes32 orgId, uint256 hatId) is executor-only after
+ * bootstrap (revert NotOrgExecutor), so it ships as a HybridVoting proposal
+ * whose option-0 execution batch calls the OrgRegistry via the executor.
+ * Option 1 is "keep current" (empty batch). hatId 0 is meaningful: it clears
+ * the override so updateOrgMetaAsAdmin falls back to the org topHat.
+ */
+function buildSetMetadataAdminProposal(a) {
+    const hatId = ethers_1.ethers.BigNumber.from(a.hatId);
+    // Same inline fragment the CLI encodes with — identical selector + calldata
+    // to the full OrgRegistry ABI.
+    const registryIface = new ethers_1.ethers.utils.Interface([
+        'function setOrgMetadataAdminHat(bytes32 orgId, uint256 hatId)',
+    ]);
+    const setHatCall = registryIface.encodeFunctionData('setOrgMetadataAdminHat', [a.orgId, hatId]);
+    return (0, governance_1.buildGovernanceProposal)({
+        votingAddress: a.hybridVotingAddress,
+        votingAbiName: 'HybridVotingNew',
+        title: a.title ?? setMetadataAdminTitle(hatId),
+        descriptionHash: a.descriptionHash,
+        durationMinutes: a.durationMinutes,
+        numOptions: 2,
+        batches: [
+            [{ target: a.orgRegistryAddress, value: ethers_1.ethers.BigNumber.from(0), calldata: setHatCall }], // option 0: apply
+            [], // option 1: keep current
+        ],
+        hatIds: [],
+        orgId: a.orgId,
+        domain: 'org',
+        action: 'set-metadata-admin',
+        summary: { hatId: hatId.toString(), orgRegistry: a.orgRegistryAddress },
+    });
+}
+/**
+ * Resolved builder for `pop org set-metadata-admin` — src/commands/org/set-metadata-admin.ts.
+ * Resolves the org's HybridVoting module + the global OrgRegistry, pins the
+ * proposal metadata ({description, optionNames, createdAt} — key order is
+ * load-bearing), and delegates to buildSetMetadataAdminProposal.
+ */
+async function setMetadataAdminIntent(ctx, params) {
+    const hatId = ethers_1.ethers.BigNumber.from(params.hatId);
+    const durationMinutes = params.durationMinutes ?? 60;
+    const modules = await (0, resolve_1.resolveOrgModules)(ctx.client, params.org, ctx.chainId);
+    const hybridVotingAddress = modules.hybridVotingAddress;
+    if (!hybridVotingAddress) {
+        throw new errors_1.CliError('HybridVoting not deployed for this org — cannot create a governance proposal.', exit_codes_1.EXIT.PRECONDITION);
+    }
+    // OrgRegistry is global infrastructure (not an org module).
+    const orgRegistryAddr = await resolveOrgRegistryAddress(ctx);
+    const hatLabel = hatId.isZero() ? '0 (clear — topHat fallback)' : hatId.toString();
+    const title = setMetadataAdminTitle(hatId);
+    // Proposal metadata — key order (description, optionNames, createdAt) is a
+    // protocol contract (metadata/proposal.ts); text matches the CLI exactly.
+    const metadata = (0, proposal_1.buildProposalMetadata)({
+        description: `Set the org's metadata-admin hat to ${hatLabel} via OrgRegistry.setOrgMetadataAdminHat. Wearers of this hat can update the org name/metadata directly (pop org update-metadata) without a vote.${hatId.isZero() ? ' A value of 0 clears the override so the org topHat is required instead.' : ''}`,
+        optionNames: [title, 'Keep current metadata admin'],
+    });
+    const cid = await (0, ipfs_1.pinJson)((0, proposal_1.serializeProposalMetadata)(metadata), ctx.ipfs);
+    const descriptionHash = (0, encoding_1.ipfsCidToBytes32)(cid);
+    const intent = buildSetMetadataAdminProposal({
+        hybridVotingAddress,
+        orgRegistryAddress: orgRegistryAddr,
+        orgId: modules.orgId,
+        hatId,
+        durationMinutes,
+        title,
+        descriptionHash,
+    });
+    intent.meta.ipfs = { cid, metadata };
+    return intent;
+}

package/dist/tx/paymaster.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Paymaster transaction builders — ports of `pop paymaster *` write paths
+ * (src/commands/paymaster/).
+ *
+ *   buildDepositForOrg / depositForOrgIntent — pop paymaster deposit
+ *     (PaymasterHub.depositForOrg(bytes32) payable — permissionless)
+ *   buildRegisterCalldata / buildAdminCallRegister / registerOrgIntent —
+ *     pop paymaster register (PoaManager.adminCall wrapping the
+ *     registrar-gated registerOrg / registerAndConfigureOrg)
+ *
+ * Registration gate — VERIFIED against contracts origin/main
+ * src/PaymasterHub.sol: registerOrg / registerAndConfigureOrg are
+ * registrar-gated (_onlyRegistrar: msg.sender must be the PoaManager CONTRACT
+ * or the orgRegistrar, i.e. the OrgDeployer). No EOA can ever call them
+ * directly — the after-the-fact path is the PoaManager OWNER routing the call
+ * through PoaManager.adminCall(target, data). adminCall is NOT payable, so an
+ * initial deposit is always its own, separate depositForOrg transaction.
+ */
+import { ethers } from 'ethers';
+import type { TxIntent } from './intent';
+import type { PopContext } from '../context';
+/** DeployConfig struct shape — verified against PaymasterHub.sol origin/main. */
+export declare const DEPLOY_CONFIG_TUPLE: string;
+/**
+ * Optional --config JSON for registerAndConfigureOrg. Fee caps are GWEI and
+ * budget caps are ETHER units, matching the `pop org deploy` paymaster block
+ * conventions.
+ */
+export interface PaymasterRegisterConfig {
+    operatorHatId?: string | number;
+    maxFeePerGas?: string | number;
+    maxPriorityFeePerGas?: string | number;
+    maxCallGas?: number;
+    maxVerificationGas?: number;
+    maxPreVerificationGas?: number;
+    rules?: Array<{
+        target: string;
+        selector: string;
+        allowed: boolean;
+        maxCallGasHint?: number;
+    }>;
+    budgets?: Array<{
+        subjectKey?: string;
+        hatId?: string | number;
+        capPerEpoch: string | number;
+        epochLen: number;
+    }>;
+}
+/** Parse a hat ID flag — BigNumber, never parseInt (Hats IDs exceed 2^53). */
+export declare function parsePaymasterHatId(input: string | number, flag: string): ethers.BigNumber;
+/** Parse an amount in ether units of the native gas token — port of parseDepositAmount in src/commands/paymaster/deposit.ts. */
+export declare function parseDepositAmount(input: string | number): ethers.BigNumber;
+/**
+ * Build the registerOrg / registerAndConfigureOrg calldata from the hat IDs +
+ * the optional config (gwei fee caps + ether budget caps). Pure port of
+ * buildRegisterCalldata in src/commands/paymaster/register.ts — byte-for-byte
+ * identical encoding.
+ */
+export declare function buildRegisterCalldata(orgId: string, adminHatId: ethers.BigNumber, operatorHatId: ethers.BigNumber, config?: PaymasterRegisterConfig): {
+    method: string;
+    data: string;
+};
+export interface DepositForOrgArgs {
+    paymasterHubAddress: string;
+    /** bytes32 org id. */
+    orgId: string;
+    /** Native value in wei (the function is payable; reverts ZeroAmount on 0). */
+    amountWei: ethers.BigNumberish;
+}
+/**
+ * Port of `pop paymaster deposit` — src/commands/paymaster/deposit.ts:
+ * PaymasterHub.depositForOrg(bytes32 orgId) payable. PERMISSIONLESS ("anyone
+ * can deposit to any org"); reverts ZeroAmount on msg.value == 0 and
+ * OrgNotRegistered when the org has no paymaster config (adminHatId == 0).
+ * ONE-WAY on the deployed hub: no withdraw exists (PR #185 / audit M-04 not
+ * shipped) — funds draw down only as sponsored UserOperations consume them.
+ */
+export declare function buildDepositForOrg(a: DepositForOrgArgs): TxIntent;
+export interface AdminCallRegisterArgs {
+    poaManagerAddress: string;
+    paymasterHubAddress: string;
+    /** bytes32 org id. */
+    orgId: string;
+    adminHatId: ethers.BigNumber;
+    /** 0 = none. */
+    operatorHatId: ethers.BigNumber;
+    /** Present → registerAndConfigureOrg; absent → registerOrg. */
+    config?: PaymasterRegisterConfig;
+}
+/**
+ * Port of the owner path of `pop paymaster register` —
+ * src/commands/paymaster/register.ts: PoaManager.adminCall(paymasterHub,
+ * registerCalldata). Only the PoaManager OWNER can send this (adminCall is
+ * onlyOwner); any other signer's transaction must revert — the CLI prints the
+ * calldata for the owner instead of broadcasting, which hosts can reproduce
+ * with buildRegisterCalldata + encodeIntent.
+ */
+export declare function buildAdminCallRegister(a: AdminCallRegisterArgs): TxIntent;
+export interface DepositForOrgParams {
+    org: string;
+    /** Ether units of the native gas token (e.g. 0.05 = 0.05 xDAI on Gnosis). */
+    amount: string | number;
+}
+/**
+ * Resolved port of `pop paymaster deposit` — src/commands/paymaster/deposit.ts.
+ * Resolves the org id and the chain's singleton PaymasterHub proxy from the
+ * infrastructure subgraph (the hub is NOT in the org's module list). When
+ * ctx.provider is present, replicates the CLI's authoritative
+ * OrgNotRegistered gate (an eth_call on purpose — subgraph lag in a
+ * revert-predicting read means knowingly broadcasting a doomed tx).
+ */
+export declare function depositForOrgIntent(ctx: PopContext, params: DepositForOrgParams): Promise<TxIntent>;
+export interface RegisterOrgParams {
+    org: string;
+    /** Hat ID that will administer the org's paymaster config (usually the org top hat). */
+    adminHat: string | number;
+    /** Optional hat ID allowed to manage budgets/rules (0 = none). */
+    operatorHat?: string | number;
+    /** Initial fee caps (gwei), rules, and budgets (ether caps) — uses registerAndConfigureOrg. */
+    config?: PaymasterRegisterConfig;
+}
+/**
+ * Resolved port of `pop paymaster register` —
+ * src/commands/paymaster/register.ts (the adminCall route). Resolves the org
+ * id + PaymasterHub + PoaManager from the infrastructure subgraph and returns
+ * the PoaManager.adminCall intent.
+ *
+ * Registration check is asymmetric like the CLI: a POSITIVE indexed
+ * "registered" answer is trusted; a negative is re-confirmed on chain when
+ * ctx.provider is available. An already-registered org throws
+ * PreconditionError (the CLI reports it as a no-op success — builder callers
+ * need the hard stop, since the intent would be a doomed re-registration).
+ *
+ * NOTE the on-chain gate the builder cannot check for you: adminCall is
+ * onlyOwner on the PoaManager, and PoaManager.owner() has no subgraph field
+ * in either live deployment — the CLI reads it via eth_call and prints the
+ * calldata instead of broadcasting when the signer is not the owner. Hosts
+ * should do the same before executing this intent.
+ */
+export declare function registerOrgIntent(ctx: PopContext, params: RegisterOrgParams): Promise<TxIntent>;