@coordination-network/network-member-governance 0.0.1

package/dist/index.js

@@ -0,0 +1,555 @@
+import { getAddress, encodeFunctionData, recoverAddress, isAddressEqual, decodeEventLog } from 'viem';
+import { encodeMultiSendData, buildSignatureBytes, calculateSafeTransactionHash, generatePreValidatedSignature, generateTypedData, EthSafeSignature, DEFAULT_SAFE_VERSION } from '@safe-global/protocol-kit';
+import { getMultiSendCallOnlyDeployment, getSafeSingletonDeployment } from '@safe-global/safe-deployments';
+import { OperationType } from '@safe-global/types-kit';
+export { OperationType } from '@safe-global/types-kit';
+
+/** The zero address, the Safe's "unset" value for `gasToken` and `refundReceiver`. */
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+/**
+ * The gas and refund fields of every transaction this package builds, all zeroed.
+ *
+ * A Safe transaction can reimburse whoever submitted it out of the Safe's own
+ * balance. This flow does not: the network member that sends the transaction
+ * pays its own gas, and the Safe never holds or moves funds. Zeroing these
+ * fields is what turns that off, so every transaction this package builds
+ * refunds nobody.
+ */
+const NO_REFUND = {
+    safeTxGas: "0",
+    baseGas: "0",
+    gasPrice: "0",
+    gasToken: ZERO_ADDRESS,
+    refundReceiver: ZERO_ADDRESS
+};
+
+/**
+ * The signatures a Safe of `memberCount` network members must require: a majority, one more than
+ * half. Five members need three, eight need five.
+ *
+ * The authoritative copy of this rule is on chain, in `NetworkMemberGovernance.governanceThreshold`,
+ * which every admission and removal sets the Safe's threshold from. This is the same expression for
+ * off-chain use: checking that a Safe is configured correctly, and reporting what a pending operation
+ * will change the threshold to. No call carries a threshold, so nothing depends on this value being
+ * right.
+ *
+ * @param memberCount How many members the Safe has owners for, after the change.
+ * @returns The required number of approvals.
+ */
+function governanceThreshold(memberCount) {
+    if (!Number.isInteger(memberCount) || memberCount < 1) {
+        throw new Error(`A member count must be a positive integer, got ${memberCount}`);
+    }
+    return Math.floor(memberCount / 2) + 1;
+}
+
+function safeVersionOf(context) {
+    return context.safeVersion ?? DEFAULT_SAFE_VERSION;
+}
+function chainIdOf(context) {
+    return BigInt(context.chainId);
+}
+/**
+ * The MultiSendCallOnly ABI for this context's Safe version.
+ *
+ * Deliberately not chain-scoped. Only the address varies by chain, so resolving the ABI separately is
+ * what lets {SafeContext.multiSend} work on a chain with no canonical deployment, which is the only
+ * situation that override exists for.
+ *
+ * @param context The Safe version the batch is for.
+ * @returns The MultiSendCallOnly ABI.
+ */
+function multiSendAbi(context) {
+    const deployment = getMultiSendCallOnlyDeployment({ version: safeVersionOf(context) });
+    if (!deployment)
+        throw new Error(`No MultiSendCallOnly deployment for Safe ${safeVersionOf(context)}`);
+    return deployment.abi;
+}
+/**
+ * The canonical MultiSendCallOnly address for this context's chain.
+ *
+ * @param context The Safe and chain the batch is for.
+ * @returns The address, or throws when the chain has no canonical deployment.
+ */
+function multiSendAddress(context) {
+    const chainId = chainIdOf(context).toString();
+    const deployment = getMultiSendCallOnlyDeployment({ version: safeVersionOf(context), network: chainId });
+    if (!deployment?.networkAddresses[chainId]) {
+        throw new Error(`No canonical MultiSendCallOnly deployment for chain ${chainId} at Safe ${safeVersionOf(context)}. Pass \`multiSend\` explicitly.`);
+    }
+    return getAddress(deployment.networkAddresses[chainId]);
+}
+/**
+ * The MultiSendCallOnly the Safe delegate-calls to batch several calls.
+ *
+ * Resolved from `@safe-global/safe-deployments` for this chain and Safe version,
+ * which is what keeps a wrong address out of a delegate call. Override it in the
+ * context only for a chain where the canonical deployment is missing.
+ *
+ * @param context The Safe and chain the batch is for.
+ * @returns The MultiSendCallOnly address.
+ */
+function resolveMultiSend(context) {
+    if (context.multiSend)
+        return getAddress(context.multiSend);
+    return multiSendAddress(context);
+}
+/** The Safe singleton ABI for this context's version, from the Safe deployments. */
+function safeAbi(context) {
+    const deployment = getSafeSingletonDeployment({ version: safeVersionOf(context) });
+    if (!deployment)
+        throw new Error(`No Safe singleton deployment for version ${safeVersionOf(context)}`);
+    return deployment.abi;
+}
+/**
+ * Builds the Safe transaction data for one or more calls, with the gas and refund
+ * fields zeroed so whoever submits it pays.
+ *
+ * A single call is executed directly. Several calls are batched through
+ * MultiSendCallOnly as one delegate call, so the Safe applies them together or
+ * not at all.
+ *
+ * @param transactions The calls, in the order the Safe should make them.
+ * @param context The Safe and chain the transaction is for.
+ * @param nonce The Safe's current `nonce()`. Read it from the chain: a
+ * transaction built against a stale nonce is rejected, and executing any Safe
+ * transaction invalidates every approval recorded against that nonce.
+ * @returns The transaction data to hash and sign.
+ */
+function buildSafeTransactionData(transactions, context, nonce) {
+    if (transactions.length === 0)
+        throw new Error("A Safe transaction needs at least one call");
+    if (transactions.length === 1) {
+        const [transaction] = transactions;
+        return {
+            to: getAddress(transaction.to),
+            value: transaction.value,
+            data: transaction.data,
+            operation: transaction.operation ?? OperationType.Call,
+            ...NO_REFUND,
+            nonce
+        };
+    }
+    // `encodeMultiSendData` packs the calls; MultiSendCallOnly still has to be
+    // called through its own `multiSend` entry point.
+    const packedCalls = encodeMultiSendData(transactions.map((transaction) => ({
+        ...transaction,
+        operation: transaction.operation ?? OperationType.Call
+    })));
+    return {
+        to: resolveMultiSend(context),
+        value: "0",
+        data: encodeFunctionData({
+            abi: multiSendAbi(context),
+            functionName: "multiSend",
+            args: [packedCalls]
+        }),
+        operation: OperationType.DelegateCall,
+        ...NO_REFUND,
+        nonce
+    };
+}
+/**
+ * The digest the Safe's owners sign, as the Safe's own `getTransactionHash`
+ * computes it. Bound to the Safe and the chain by the EIP-712 domain, so a
+ * signature cannot be replayed against another Safe or another network.
+ *
+ * @param context The Safe and chain the transaction is for.
+ * @param transaction The transaction data to hash.
+ * @returns The EIP-712 digest.
+ */
+function hashSafeTransaction(context, transaction) {
+    return calculateSafeTransactionHash(getAddress(context.safeAddress), transaction, safeVersionOf(context), chainIdOf(context));
+}
+/**
+ * Signs a Safe transaction as one approver.
+ *
+ * Governance approves on chain with {encodeApproveHash} and never circulates a
+ * signature, so nothing in this package's flow calls this. It stays as a Safe
+ * primitive, and the tests use it to check the packing in
+ * {encodeSafeSignatures}.
+ *
+ * The signer must be an owner of the Safe. A viem account works directly, and so
+ * does any wrapper over a KMS or HSM that signs EIP-712 and knows its address.
+ *
+ * @param signer The approver's signing key.
+ * @param context The Safe and chain the transaction is for.
+ * @param transaction The transaction to approve.
+ * @returns The approver's signature.
+ */
+async function signSafeTransaction(signer, context, transaction) {
+    const typedData = generateTypedData({
+        safeAddress: getAddress(context.safeAddress),
+        safeVersion: safeVersionOf(context),
+        chainId: chainIdOf(context),
+        data: transaction
+    });
+    const signature = await signer.signTypedData(typedData);
+    return new EthSafeSignature(getAddress(signer.address), signature);
+}
+/**
+ * Recovers the owner behind a signature over a Safe transaction, trusting the
+ * signature rather than a claimed sender. Like {signSafeTransaction}, it serves
+ * off-chain signatures, which this package's flow does not produce.
+ *
+ * @param context The Safe and chain the transaction is for.
+ * @param transaction The signed transaction.
+ * @param signature The 65-byte signature.
+ * @returns The recovered signer address.
+ */
+async function recoverSafeSigner(context, transaction, signature) {
+    return recoverAddress({ hash: hashSafeTransaction(context, transaction), signature });
+}
+/**
+ * Calldata for `approveHash`, which records an approval in the Safe's own storage instead of handing a
+ * signature to somebody.
+ *
+ * This is the fully on-chain approval path, and its appeal is that nothing is ever circulated: each
+ * approver derives the transaction from the chain, approves its hash from its own key, and the member
+ * that completes the quorum reads the approvals and executes. There is no channel to secure, and no
+ * approver ever acts on a payload another party assembled, which is what makes blind signing
+ * impossible rather than merely detectable.
+ *
+ * Only an owner may call it, and the hash must be the one from {hashSafeTransaction}: an approval is
+ * bound to one exact transaction, so approving one candidate's admission says nothing about another's.
+ *
+ * @param context The Safe and chain the transaction is for.
+ * @param safeTxHash The digest from {hashSafeTransaction}.
+ * @returns Calldata to send to the Safe address, from the approver's own key.
+ */
+function encodeApproveHash(context, safeTxHash) {
+    return encodeFunctionData({
+        abi: safeAbi(context),
+        functionName: "approveHash",
+        args: [safeTxHash]
+    });
+}
+/**
+ * The signature entry for an owner that approved on chain with {encodeApproveHash}.
+ *
+ * It carries no signature material: the Safe reads `v == 1` and looks the approval up in its own
+ * storage, so the entry only names the approver. Feed these to {encodeSafeSignatures} or
+ * {encodeExecTransaction} exactly like signatures made off chain, and the two kinds may be mixed in one
+ * transaction.
+ *
+ * The member that submits gets its own entry for free: the Safe treats the executor as having approved,
+ * so it can include itself without a prior `approveHash`, turning a 3-of-5 into two approval
+ * transactions plus the execution.
+ *
+ * @param owner The approver, which must still be an owner when the transaction executes.
+ * @returns A signature entry naming that approver.
+ */
+function onChainApproval(owner) {
+    return generatePreValidatedSignature(getAddress(owner));
+}
+/**
+ * Packs signatures into the `signatures` argument of `execTransaction`.
+ *
+ * The Safe reads the packed signatures at fixed 65-byte offsets and requires each recovered signer to be
+ * strictly greater than the previous one, so the SDK sorts them by signer here.
+ * A set that counts the same owner twice would sort fine and then be rejected on
+ * chain, so it is refused up front.
+ *
+ * @param signatures The approvals, in any order. {onChainApproval} produces them for the on-chain
+ * flow.
+ * @returns The entries concatenated into the single `bytes` value `execTransaction` takes, 65 bytes
+ * per owner, ordered by signer.
+ */
+function encodeSafeSignatures(signatures) {
+    if (signatures.length === 0)
+        throw new Error("A Safe transaction needs at least one signature");
+    const seen = new Set();
+    signatures.forEach(({ signer }) => {
+        const owner = getAddress(signer);
+        if (seen.has(owner))
+            throw new Error(`Duplicate signature from ${owner}: the Safe counts each owner once`);
+        seen.add(owner);
+    });
+    return buildSignatureBytes([...signatures]);
+}
+/**
+ * Checks a set of approvers against the Safe's owners and threshold, so a member
+ * knows whether it can submit yet and, if not, how many approvals are missing.
+ * Addresses that are not current owners are ignored rather than counted.
+ *
+ * @param owners The Safe's current owners, from `getOwners()`.
+ * @param threshold The Safe's current `getThreshold()`.
+ * @param signers The addresses that have approved, read from the chain.
+ * @returns Whether the set is enough, and what is still missing.
+ */
+function checkQuorum(owners, threshold, signers) {
+    const isOwner = (candidate) => owners.some((owner) => isAddressEqual(owner, candidate));
+    const distinct = [...new Set(signers.filter(isOwner).map((signer) => getAddress(signer)))].sort((a, b) => BigInt(a) < BigInt(b) ? -1 : 1);
+    return {
+        hasQuorum: distinct.length >= threshold,
+        signers: distinct,
+        missing: Math.max(threshold - distinct.length, 0)
+    };
+}
+/**
+ * Encodes the `execTransaction` call that lands the transaction on chain, against
+ * the Safe ABI for this context's version. The result is plain calldata to the
+ * Safe, so anyone can submit it: the approvals carry the authority, not the
+ * sender.
+ *
+ * @param context The Safe and chain the transaction is for.
+ * @param transaction The approved transaction.
+ * @param signatures The approvals, in any order.
+ * @returns Calldata to send to the Safe address.
+ */
+function encodeExecTransaction(context, transaction, signatures) {
+    return encodeFunctionData({
+        abi: safeAbi(context),
+        functionName: "execTransaction",
+        args: [
+            transaction.to,
+            BigInt(transaction.value),
+            transaction.data,
+            transaction.operation,
+            BigInt(transaction.safeTxGas),
+            BigInt(transaction.baseGas),
+            BigInt(transaction.gasPrice),
+            transaction.gasToken,
+            transaction.refundReceiver,
+            encodeSafeSignatures(signatures)
+        ]
+    });
+}
+
+/**
+ * The `NetworkMemberGovernance` surface: the governance operations, each one call.
+ *
+ * There is no threshold argument anywhere here. The contract computes it from the Safe's live owner
+ * count, and removal reads the member's commitment and signer from the registry, so no caller can
+ * carry a wrong threshold, point at another member's leaf, or take arbitrary calldata.
+ *
+ * `expectedMemberCount` is not a policy input either. It pins the member set a transaction was built
+ * against, so a transaction goes stale the moment that set changes. It has to exist because a
+ * voluntary exit changes the owner count and the threshold without advancing the Safe's nonce, which is
+ * what would otherwise invalidate transactions in flight.
+ */
+const NETWORK_MEMBER_GOVERNANCE_ABI = [
+    {
+        type: "function",
+        name: "admitMember",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "memberNetworkId", type: "bytes32" },
+            { name: "semaphoreCommitment", type: "uint256" },
+            { name: "governanceSigner", type: "address" },
+            { name: "expectedMemberCount", type: "uint256" }
+        ],
+        outputs: []
+    },
+    {
+        type: "function",
+        name: "removeMember",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "memberNetworkId", type: "bytes32" },
+            { name: "merkleProofSiblings", type: "uint256[]" },
+            { name: "expectedMemberCount", type: "uint256" }
+        ],
+        outputs: []
+    },
+    {
+        type: "function",
+        name: "exitNetwork",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "memberNetworkId", type: "bytes32" },
+            { name: "merkleProofSiblings", type: "uint256[]" }
+        ],
+        outputs: []
+    },
+    {
+        type: "function",
+        name: "governanceThreshold",
+        stateMutability: "pure",
+        inputs: [{ name: "memberCount", type: "uint256" }],
+        outputs: [{ name: "", type: "uint256" }]
+    },
+    {
+        type: "function",
+        name: "thresholdAfterAdmission",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "uint256" }]
+    }
+];
+/** The `NetworkMemberRegistry` surface a member server needs directly. */
+const NETWORK_MEMBER_REGISTRY_ABI = [
+    {
+        type: "function",
+        name: "requestToJoin",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "memberNetworkId", type: "bytes32" },
+            { name: "semaphoreCommitment", type: "uint256" },
+            { name: "governanceSigner", type: "address" },
+            { name: "metadataURI", type: "string" }
+        ],
+        outputs: []
+    },
+    {
+        type: "event",
+        name: "NetworkMemberJoinRequested",
+        inputs: [
+            { name: "memberNetworkId", type: "bytes32", indexed: true },
+            { name: "semaphoreCommitment", type: "uint256", indexed: false },
+            { name: "governanceSigner", type: "address", indexed: false },
+            { name: "metadataURI", type: "string", indexed: false }
+        ]
+    }
+];
+/**
+ * Turns a `NetworkMemberJoinRequested` log into the request it announced.
+ *
+ * This is the only honest source of a {NetworkMemberJoinRequest}: an approver reads the candidate's own
+ * event from a node it trusts and decodes it here, so the transaction it approves is a function of what
+ * the chain reported. Building the object by hand from something another party sent gives up that
+ * property, and with it the meaning of the approval.
+ *
+ * It stays free of any RPC dependency: fetching the log is the caller's job, with `getLogs` against its
+ * own node. What this removes is the field mapping, and the chance of a silent mismatch in it.
+ *
+ * @param log The log, as viem returns it from `getLogs`.
+ * @param registry The registry the log must have come from. Checked when the log carries an address.
+ * @returns The request the candidate published.
+ */
+function decodeJoinRequestLog(log, registry) {
+    if (log.address && registry && !isAddressEqual(log.address, getAddress(registry))) {
+        throw new Error(`Log came from ${log.address}, not from the registry at ${getAddress(registry)}`);
+    }
+    const { args } = decodeEventLog({
+        abi: NETWORK_MEMBER_REGISTRY_ABI,
+        eventName: "NetworkMemberJoinRequested",
+        data: log.data,
+        topics: log.topics
+    });
+    return {
+        memberNetworkId: args.memberNetworkId,
+        semaphoreCommitment: args.semaphoreCommitment,
+        governanceSigner: getAddress(args.governanceSigner),
+        metadataURI: args.metadataURI
+    };
+}
+/**
+ * The single call that admits a network member: its record, its group leaf, and its seat at the Safe.
+ *
+ * @param admission The vetted join request being approved.
+ * @param memberCount The Safe's live owner count, from `getOwners().length`. Pinned into the call so the
+ * transaction goes stale if the member set changes before it executes.
+ * @returns Calldata for the orchestrator.
+ */
+function encodeAdmitMember(admission, memberCount) {
+    return encodeFunctionData({
+        abi: NETWORK_MEMBER_GOVERNANCE_ABI,
+        functionName: "admitMember",
+        args: [
+            admission.memberNetworkId,
+            admission.semaphoreCommitment,
+            getAddress(admission.governanceSigner),
+            BigInt(memberCount)
+        ]
+    });
+}
+/**
+ * The single call that removes a network member from all three places.
+ *
+ * @param removal The member to remove, and its membership proof.
+ * @param memberCount The Safe's live owner count, pinned for the reason given on {encodeAdmitMember}.
+ * @returns Calldata for the orchestrator.
+ */
+function encodeRemoveMember(removal, memberCount) {
+    return encodeFunctionData({
+        abi: NETWORK_MEMBER_GOVERNANCE_ABI,
+        functionName: "removeMember",
+        args: [removal.memberNetworkId, removal.merkleProofSiblings, BigInt(memberCount)]
+    });
+}
+/** The one call an admission is, as a Safe meta-transaction. */
+function admissionCall(contracts, admission, memberCount) {
+    return { to: getAddress(contracts.governance), value: "0", data: encodeAdmitMember(admission, memberCount) };
+}
+/** The one call a removal is, as a Safe meta-transaction. */
+function removalCall(contracts, removal, memberCount) {
+    return { to: getAddress(contracts.governance), value: "0", data: encodeRemoveMember(removal, memberCount) };
+}
+/**
+ * Builds the Safe transaction that admits a network member.
+ *
+ * One plain call to the orchestrator, so there is no MultiSend batch to decode and no threshold in the
+ * calldata to check. The result is a pure function of the on-chain request and the nonce, which is what
+ * makes building safe to do in parallel: two approvers who build from the same chain state produce
+ * byte-identical transactions and therefore the same `safeTxHash`, so their approvals accumulate
+ * against one hash instead of competing.
+ *
+ * @param contracts The governance contracts.
+ * @param admission The vetted join request being approved.
+ * @param context The Safe and chain the transaction is for.
+ * @param nonce The Safe's current `nonce()`.
+ * @param memberCount The Safe's live owner count, from `getOwners().length`.
+ * @returns The transaction data to sign.
+ */
+function buildAdmissionTransaction(contracts, admission, context, nonce, memberCount) {
+    return buildSafeTransactionData([admissionCall(contracts, admission, memberCount)], context, nonce);
+}
+/**
+ * Builds the Safe transaction that removes a network member.
+ *
+ * @param contracts The governance contracts.
+ * @param removal The member to remove, and its membership proof.
+ * @param context The Safe and chain the transaction is for.
+ * @param nonce The Safe's current `nonce()`.
+ * @param memberCount The Safe's live owner count, from `getOwners().length`.
+ * @returns The transaction data to sign.
+ */
+function buildRemovalTransaction(contracts, removal, context, nonce, memberCount) {
+    return buildSafeTransactionData([removalCall(contracts, removal, memberCount)], context, nonce);
+}
+/**
+ * Calldata for a member leaving the network of its own accord: its record, its group leaf and its seat
+ * at the Safe, in one call.
+ *
+ * Not a Safe transaction. The member's own governance signer sends this directly to the orchestrator,
+ * because departure does not need the consent of the members being left, so there is no transaction
+ * for anyone else to approve. It is also how a member that is winding down avoids leaving a seat behind
+ * that nobody can sign for, which would still count toward everyone else's threshold.
+ *
+ * Rejoining means a new request and a new place in the group, and every credential the member issued
+ * stops verifying once its record is gone.
+ *
+ * @param memberNetworkId The member leaving. The caller must be its governance signer.
+ * @param merkleProofSiblings The membership proof for its group leaf, computed off chain against the
+ * group state this transaction will execute in.
+ * @returns Calldata to send to the orchestrator.
+ */
+function encodeExitNetwork(memberNetworkId, merkleProofSiblings) {
+    return encodeFunctionData({
+        abi: NETWORK_MEMBER_GOVERNANCE_ABI,
+        functionName: "exitNetwork",
+        args: [memberNetworkId, merkleProofSiblings]
+    });
+}
+/**
+ * Calldata for a candidate's own join request, the one permissionless call in this flow. It must be
+ * sent from the auth address the networkId encodes, and `governanceSigner` must be a different key.
+ *
+ * @param request The request to announce.
+ * @returns Calldata for the registry.
+ */
+function encodeRequestToJoin(request) {
+    return encodeFunctionData({
+        abi: NETWORK_MEMBER_REGISTRY_ABI,
+        functionName: "requestToJoin",
+        args: [
+            request.memberNetworkId,
+            request.semaphoreCommitment,
+            getAddress(request.governanceSigner),
+            request.metadataURI ?? ""
+        ]
+    });
+}
+
+export { NETWORK_MEMBER_GOVERNANCE_ABI, NETWORK_MEMBER_REGISTRY_ABI, NO_REFUND, ZERO_ADDRESS, admissionCall, buildAdmissionTransaction, buildRemovalTransaction, buildSafeTransactionData, checkQuorum, decodeJoinRequestLog, encodeAdmitMember, encodeApproveHash, encodeExecTransaction, encodeExitNetwork, encodeRemoveMember, encodeRequestToJoin, encodeSafeSignatures, governanceThreshold, hashSafeTransaction, onChainApproval, recoverSafeSigner, removalCall, resolveMultiSend, signSafeTransaction };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@coordination-network/network-member-governance",
+  "version": "0.0.1",
+  "description": "Governance Safe transactions for the network member registry: build the admission or removal transaction, sign it as an approved network member, and aggregate the signatures the Safe accepts on chain.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zk-kit/coordination-network.git",
+    "directory": "packages/network-member-governance"
+  },
+  "homepage": "https://github.com/zk-kit/coordination-network/tree/main/packages/network-member-governance",
+  "bugs": "https://github.com/zk-kit/coordination-network/issues",
+  "sideEffects": false,
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "types/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist types && rollup -c rollup.config.mjs"
+  },
+  "dependencies": {
+    "@safe-global/protocol-kit": "^8.0.6",
+    "@safe-global/safe-deployments": "^1.37.62",
+    "@safe-global/types-kit": "^4.0.1",
+    "viem": "^2.40.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/jest": "^30.0.0",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.62.2",
+    "rollup-plugin-cleanup": "^3.2.1",
+    "rollup-plugin-dts": "^6.4.1",
+    "tslib": "^2.8.0",
+    "typescript": "^6.0.3"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,19 @@
+/** The zero address, the Safe's "unset" value for `gasToken` and `refundReceiver`. */
+export const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000" as const
+
+/**
+ * The gas and refund fields of every transaction this package builds, all zeroed.
+ *
+ * A Safe transaction can reimburse whoever submitted it out of the Safe's own
+ * balance. This flow does not: the network member that sends the transaction
+ * pays its own gas, and the Safe never holds or moves funds. Zeroing these
+ * fields is what turns that off, so every transaction this package builds
+ * refunds nobody.
+ */
+export const NO_REFUND = {
+    safeTxGas: "0",
+    baseGas: "0",
+    gasPrice: "0",
+    gasToken: ZERO_ADDRESS,
+    refundReceiver: ZERO_ADDRESS
+} as const

package/src/governance-rule.ts

@@ -0,0 +1,20 @@
+/**
+ * The signatures a Safe of `memberCount` network members must require: a majority, one more than
+ * half. Five members need three, eight need five.
+ *
+ * The authoritative copy of this rule is on chain, in `NetworkMemberGovernance.governanceThreshold`,
+ * which every admission and removal sets the Safe's threshold from. This is the same expression for
+ * off-chain use: checking that a Safe is configured correctly, and reporting what a pending operation
+ * will change the threshold to. No call carries a threshold, so nothing depends on this value being
+ * right.
+ *
+ * @param memberCount How many members the Safe has owners for, after the change.
+ * @returns The required number of approvals.
+ */
+export function governanceThreshold(memberCount: number): number {
+    if (!Number.isInteger(memberCount) || memberCount < 1) {
+        throw new Error(`A member count must be a positive integer, got ${memberCount}`)
+    }
+
+    return Math.floor(memberCount / 2) + 1
+}