@coordination-network/network-member-governance 0.0.1

package/types/index.d.ts

@@ -0,0 +1,472 @@
+import * as _safe_global_types_kit from '@safe-global/types-kit';
+import { MetaTransactionData, SafeTransactionData, SafeSignature } from '@safe-global/types-kit';
+export { MetaTransactionData, OperationType, SafeSignature, SafeTransactionData, SafeVersion } from '@safe-global/types-kit';
+import { Address, Hex, TypedDataDefinition } from 'viem';
+
+/** The zero address, the Safe's "unset" value for `gasToken` and `refundReceiver`. */
+declare 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.
+ */
+declare const NO_REFUND: {
+    readonly safeTxGas: "0";
+    readonly baseGas: "0";
+    readonly gasPrice: "0";
+    readonly gasToken: "0x0000000000000000000000000000000000000000";
+    readonly refundReceiver: "0x0000000000000000000000000000000000000000";
+};
+
+/**
+ * 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.
+ */
+declare function governanceThreshold(memberCount: number): number;
+
+/**
+ * Which Safe, on which chain, a transaction is bound to.
+ *
+ * `safeVersion` selects the encoding: Safe changed both the EIP-712 domain and
+ * the `SafeTx` struct across versions, so a digest computed for the wrong version
+ * is silently wrong. It defaults to the SDK's default version; read the Safe's
+ * own `VERSION()` and pass it when governing an older deployment.
+ */
+interface SafeContext {
+    /** The governance Safe's address. */
+    safeAddress: Address;
+    /** The chain the Safe is deployed on. */
+    chainId: number | bigint;
+    /** The Safe's contract version. Defaults to the SDK's default. */
+    safeVersion?: _safe_global_types_kit.SafeVersion;
+    /**
+     * MultiSendCallOnly to batch through. Defaults to the canonical deployment
+     * for this chain and Safe version, from `@safe-global/safe-deployments`. Pass
+     * one only for a chain where that deployment is missing.
+     */
+    multiSend?: Address;
+}
+/** The result of checking a signature set against a Safe's owners. */
+interface QuorumCheck {
+    /** Whether the set is enough for the Safe to execute. */
+    hasQuorum: boolean;
+    /** The distinct owners that signed, sorted ascending. */
+    signers: Address[];
+    /** How many more owner signatures are needed. Zero once quorum is met. */
+    missing: number;
+}
+
+/**
+ * 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.
+ */
+declare const NETWORK_MEMBER_GOVERNANCE_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "admitMember";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "memberNetworkId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "semaphoreCommitment";
+        readonly type: "uint256";
+    }, {
+        readonly name: "governanceSigner";
+        readonly type: "address";
+    }, {
+        readonly name: "expectedMemberCount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "removeMember";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "memberNetworkId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "merkleProofSiblings";
+        readonly type: "uint256[]";
+    }, {
+        readonly name: "expectedMemberCount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "exitNetwork";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "memberNetworkId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "merkleProofSiblings";
+        readonly type: "uint256[]";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "governanceThreshold";
+    readonly stateMutability: "pure";
+    readonly inputs: readonly [{
+        readonly name: "memberCount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "thresholdAfterAdmission";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}];
+/** The `NetworkMemberRegistry` surface a member server needs directly. */
+declare const NETWORK_MEMBER_REGISTRY_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "requestToJoin";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "memberNetworkId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "semaphoreCommitment";
+        readonly type: "uint256";
+    }, {
+        readonly name: "governanceSigner";
+        readonly type: "address";
+    }, {
+        readonly name: "metadataURI";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "event";
+    readonly name: "NetworkMemberJoinRequested";
+    readonly inputs: readonly [{
+        readonly name: "memberNetworkId";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }, {
+        readonly name: "semaphoreCommitment";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "governanceSigner";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "metadataURI";
+        readonly type: "string";
+        readonly indexed: false;
+    }];
+}];
+/** Where the governance operations live. */
+interface GovernanceContracts {
+    /** The `NetworkMemberGovernance` orchestrator, enabled as a module on the Safe. */
+    governance: Address;
+    /** The `NetworkMemberRegistry`, for reading records and for a candidate's own join request. */
+    registry: Address;
+}
+/**
+ * What a candidate published in its `NetworkMemberJoinRequested` event, which is every argument its
+ * admission will carry.
+ *
+ * Approvers build this from the event rather than from anything another party sends them, so an
+ * admission is a function of the candidate's own announcement.
+ */
+interface NetworkMemberJoinRequest {
+    /** The candidate's networkId. */
+    memberNetworkId: Hex;
+    /** The Semaphore identity commitment it wants in the approved-member group. */
+    semaphoreCommitment: bigint;
+    /** The address it wants added to the governance Safe, so it can vote on later candidates. */
+    governanceSigner: Address;
+    /** Where the vetting material lives, or an empty string. */
+    metadataURI?: string;
+}
+/** What removing a member needs. */
+interface NetworkMemberRemoval {
+    /** The member's networkId. Its commitment and signer are read on chain. */
+    memberNetworkId: Hex;
+    /**
+     * The membership proof for its group leaf, computed off chain against the group state this
+     * transaction will execute in. If another group write lands first, recompute it and approve the
+     * rebuilt transaction.
+     */
+    merkleProofSiblings: bigint[];
+}
+/** The shape of a log this package can read: enough of viem's `Log` to decode it. */
+interface JoinRequestLog {
+    /** The contract that emitted it. Checked against the registry when both are given. */
+    address?: Address;
+    /** The log's topics, the first being the event signature. */
+    topics: readonly Hex[];
+    /** The log's non-indexed data. */
+    data: Hex;
+}
+/**
+ * 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.
+ */
+declare function decodeJoinRequestLog(log: JoinRequestLog, registry?: Address): NetworkMemberJoinRequest;
+/**
+ * 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.
+ */
+declare function encodeAdmitMember(admission: NetworkMemberJoinRequest, memberCount: number): Hex;
+/**
+ * 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.
+ */
+declare function encodeRemoveMember(removal: NetworkMemberRemoval, memberCount: number): Hex;
+/** The one call an admission is, as a Safe meta-transaction. */
+declare function admissionCall(contracts: GovernanceContracts, admission: NetworkMemberJoinRequest, memberCount: number): MetaTransactionData;
+/** The one call a removal is, as a Safe meta-transaction. */
+declare function removalCall(contracts: GovernanceContracts, removal: NetworkMemberRemoval, memberCount: number): MetaTransactionData;
+/**
+ * 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.
+ */
+declare function buildAdmissionTransaction(contracts: GovernanceContracts, admission: NetworkMemberJoinRequest, context: SafeContext, nonce: number, memberCount: number): SafeTransactionData;
+/**
+ * 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.
+ */
+declare function buildRemovalTransaction(contracts: GovernanceContracts, removal: NetworkMemberRemoval, context: SafeContext, nonce: number, memberCount: number): SafeTransactionData;
+/**
+ * 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.
+ */
+declare function encodeExitNetwork(memberNetworkId: Hex, merkleProofSiblings: bigint[]): Hex;
+/**
+ * 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.
+ */
+declare function encodeRequestToJoin(request: NetworkMemberJoinRequest): Hex;
+
+/**
+ * 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.
+ */
+declare function resolveMultiSend(context: SafeContext): Address;
+/**
+ * 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.
+ */
+declare function buildSafeTransactionData(transactions: MetaTransactionData[], context: SafeContext, nonce: number): SafeTransactionData;
+/**
+ * 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.
+ */
+declare function hashSafeTransaction(context: SafeContext, transaction: SafeTransactionData): Hex;
+/** What a member server needs from its governance key: EIP-712 signing. */
+interface TypedDataSigner {
+    /** The owner address this key signs for. */
+    address: Address;
+    /** Signs EIP-712 typed data, returning a 65-byte signature. */
+    signTypedData(typedData: TypedDataDefinition): Promise<Hex>;
+}
+/**
+ * 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.
+ */
+declare function signSafeTransaction(signer: TypedDataSigner, context: SafeContext, transaction: SafeTransactionData): Promise<SafeSignature>;
+/**
+ * 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.
+ */
+declare function recoverSafeSigner(context: SafeContext, transaction: SafeTransactionData, signature: Hex): Promise<Address>;
+/**
+ * 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.
+ */
+declare function encodeApproveHash(context: SafeContext, safeTxHash: Hex): Hex;
+/**
+ * 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.
+ */
+declare function onChainApproval(owner: Address): SafeSignature;
+/**
+ * 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.
+ */
+declare function encodeSafeSignatures(signatures: SafeSignature[]): Hex;
+/**
+ * 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.
+ */
+declare function checkQuorum(owners: Address[], threshold: number, signers: Address[]): QuorumCheck;
+/**
+ * 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.
+ */
+declare function encodeExecTransaction(context: SafeContext, transaction: SafeTransactionData, signatures: SafeSignature[]): Hex;
+
+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 };
+export type { GovernanceContracts, JoinRequestLog, NetworkMemberJoinRequest, NetworkMemberRemoval, QuorumCheck, SafeContext, TypedDataSigner };