@aztec/ethereum 0.0.0-test.0 → 0.0.1-commit.21caa21

package/src/eth-signer/eth-signer.ts

@@ -0,0 +1,25 @@
+/**
+ * Common interface for all signer implementations
+ */
+import type { Buffer32 } from '@aztec/foundation/buffer';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Signature } from '@aztec/foundation/eth-signature';
+
+import type { TransactionSerializable, TypedDataDefinition } from 'viem';
+
+/**
+ * Abstraction for signing operations used by the node keystore.
+ */
+export interface EthSigner {
+  /** The Ethereum address for this signer */
+  readonly address: EthAddress;
+
+  /** Sign a message using eth_sign (with Ethereum message prefix) */
+  signMessage(message: Buffer32): Promise<Signature>;
+
+  /** Sign typed data using EIP-712 */
+  signTypedData(typedData: TypedDataDefinition): Promise<Signature>;
+
+  /** Sign a transaction */
+  signTransaction(transaction: TransactionSerializable): Promise<Signature>;
+}

package/src/eth-signer/index.ts

@@ -0,0 +1 @@
+export * from './eth-signer.js';

package/src/index.ts

@@ -1,8 +1,7 @@
 export * from './constants.js';
 export * from './deploy_l1_contracts.js';
 export * from './chain.js';
-export * from './eth_cheat_codes.js';
-export * from './l1_tx_utils.js';
+export * from './l1_tx_utils/index.js';
 export * from './l1_contract_addresses.js';
 export * from './l1_reader.js';
 export * from './utils.js';
@@ -11,3 +10,8 @@ export * from './types.js';
 export * from './contracts/index.js';
 export * from './queries.js';
 export * from './client.js';
+export * from './account.js';
+export * from './l1_types.js';
+export * from './l1_artifacts.js';
+export * from './publisher_manager.js';
+export * from './eth-signer/index.js';

package/src/l1_artifacts.ts

@@ -0,0 +1,254 @@
+import {
+  CoinIssuerAbi,
+  CoinIssuerBytecode,
+  DateGatedRelayerAbi,
+  DateGatedRelayerBytecode,
+  EmpireSlasherDeploymentExtLibAbi,
+  EmpireSlasherDeploymentExtLibBytecode,
+  EmpireSlashingProposerAbi,
+  EmpireSlashingProposerBytecode,
+  FeeAssetHandlerAbi,
+  FeeAssetHandlerBytecode,
+  FeeJuicePortalAbi,
+  FeeJuicePortalBytecode,
+  GSEAbi,
+  GSEBytecode,
+  GovernanceAbi,
+  GovernanceBytecode,
+  GovernanceProposerAbi,
+  GovernanceProposerBytecode,
+  HonkVerifierAbi,
+  HonkVerifierBytecode,
+  InboxAbi,
+  InboxBytecode,
+  MockVerifierAbi,
+  MockVerifierBytecode,
+  MockZKPassportVerifierAbi,
+  MockZKPassportVerifierBytecode,
+  MultiAdderAbi,
+  MultiAdderBytecode,
+  OutboxAbi,
+  OutboxBytecode,
+  RegisterNewRollupVersionPayloadAbi,
+  RegisterNewRollupVersionPayloadBytecode,
+  RegistryAbi,
+  RegistryBytecode,
+  RewardDistributorAbi,
+  RewardDistributorBytecode,
+  RewardExtLibAbi,
+  RewardExtLibBytecode,
+  RollupAbi,
+  RollupBytecode,
+  RollupLinkReferences,
+  RollupOperationsExtLibAbi,
+  RollupOperationsExtLibBytecode,
+  SlashFactoryAbi,
+  SlashFactoryBytecode,
+  SlasherAbi,
+  SlasherBytecode,
+  StakingAssetHandlerAbi,
+  StakingAssetHandlerBytecode,
+  TallySlasherDeploymentExtLibAbi,
+  TallySlasherDeploymentExtLibBytecode,
+  TallySlashingProposerAbi,
+  TallySlashingProposerBytecode,
+  TestERC20Abi,
+  TestERC20Bytecode,
+  ValidatorOperationsExtLibAbi,
+  ValidatorOperationsExtLibBytecode,
+  ValidatorSelectionLibAbi,
+  ValidatorSelectionLibBytecode,
+} from '@aztec/l1-artifacts';
+
+import type { Hex } from 'viem';
+
+export const RegistryArtifact = {
+  name: 'Registry',
+  contractAbi: RegistryAbi,
+  contractBytecode: RegistryBytecode as Hex,
+};
+
+export const InboxArtifact = {
+  name: 'Inbox',
+  contractAbi: InboxAbi,
+  contractBytecode: InboxBytecode as Hex,
+};
+
+export const OutboxArtifact = {
+  name: 'Outbox',
+  contractAbi: OutboxAbi,
+  contractBytecode: OutboxBytecode as Hex,
+};
+
+export const RollupArtifact = {
+  name: 'Rollup',
+  contractAbi: RollupAbi,
+  contractBytecode: RollupBytecode as Hex,
+  libraries: {
+    linkReferences: RollupLinkReferences,
+    libraryCode: {
+      ValidatorSelectionLib: {
+        name: 'ValidatorSelectionLib',
+        contractAbi: ValidatorSelectionLibAbi,
+        contractBytecode: ValidatorSelectionLibBytecode as Hex,
+      },
+      RollupOperationsExtLib: {
+        name: 'RollupOperationsExtLib',
+        contractAbi: RollupOperationsExtLibAbi,
+        contractBytecode: RollupOperationsExtLibBytecode as Hex,
+      },
+      ValidatorOperationsExtLib: {
+        name: 'ValidatorOperationsExtLib',
+        contractAbi: ValidatorOperationsExtLibAbi,
+        contractBytecode: ValidatorOperationsExtLibBytecode as Hex,
+      },
+      RewardExtLib: {
+        name: 'RewardExtLib',
+        contractAbi: RewardExtLibAbi,
+        contractBytecode: RewardExtLibBytecode as Hex,
+      },
+      TallySlasherDeploymentExtLib: {
+        name: 'TallySlasherDeploymentExtLib',
+        contractAbi: TallySlasherDeploymentExtLibAbi,
+        contractBytecode: TallySlasherDeploymentExtLibBytecode as Hex,
+      },
+      EmpireSlasherDeploymentExtLib: {
+        name: 'EmpireSlasherDeploymentExtLib',
+        contractAbi: EmpireSlasherDeploymentExtLibAbi,
+        contractBytecode: EmpireSlasherDeploymentExtLibBytecode as Hex,
+      },
+    },
+  },
+};
+
+export const StakingAssetArtifact = {
+  name: 'StakingAsset',
+  contractAbi: TestERC20Abi,
+  contractBytecode: TestERC20Bytecode as Hex,
+};
+
+export const FeeAssetArtifact = {
+  name: 'FeeAsset',
+  contractAbi: TestERC20Abi,
+  contractBytecode: TestERC20Bytecode as Hex,
+};
+
+export const FeeJuicePortalArtifact = {
+  name: 'FeeJuicePortal',
+  contractAbi: FeeJuicePortalAbi,
+  contractBytecode: FeeJuicePortalBytecode as Hex,
+};
+
+export const RewardDistributorArtifact = {
+  name: 'RewardDistributor',
+  contractAbi: RewardDistributorAbi,
+  contractBytecode: RewardDistributorBytecode as Hex,
+};
+
+export const CoinIssuerArtifact = {
+  name: 'CoinIssuer',
+  contractAbi: CoinIssuerAbi,
+  contractBytecode: CoinIssuerBytecode as Hex,
+};
+
+export const DateGatedRelayerArtifact = {
+  name: 'DateGatedRelayer',
+  contractAbi: DateGatedRelayerAbi,
+  contractBytecode: DateGatedRelayerBytecode as Hex,
+};
+
+export const GovernanceProposerArtifact = {
+  name: 'GovernanceProposer',
+  contractAbi: GovernanceProposerAbi,
+  contractBytecode: GovernanceProposerBytecode as Hex,
+};
+
+export const GovernanceArtifact = {
+  name: 'Governance',
+  contractAbi: GovernanceAbi,
+  contractBytecode: GovernanceBytecode as Hex,
+};
+
+export const SlasherArtifact = {
+  name: 'Slasher',
+  contractAbi: SlasherAbi,
+  contractBytecode: SlasherBytecode as Hex,
+};
+
+export const EmpireSlashingProposerArtifact = {
+  name: 'EmpireSlashingProposer',
+  contractAbi: EmpireSlashingProposerAbi,
+  contractBytecode: EmpireSlashingProposerBytecode as Hex,
+};
+
+export const TallySlashingProposerArtifact = {
+  name: 'TallySlashingProposer',
+  contractAbi: TallySlashingProposerAbi,
+  contractBytecode: TallySlashingProposerBytecode as Hex,
+};
+
+export const SlashFactoryArtifact = {
+  name: 'SlashFactory',
+  contractAbi: SlashFactoryAbi,
+  contractBytecode: SlashFactoryBytecode as Hex,
+};
+
+export const RegisterNewRollupVersionPayloadArtifact = {
+  name: 'RegisterNewRollupVersionPayload',
+  contractAbi: RegisterNewRollupVersionPayloadAbi,
+  contractBytecode: RegisterNewRollupVersionPayloadBytecode as Hex,
+};
+
+export const FeeAssetHandlerArtifact = {
+  name: 'FeeAssetHandler',
+  contractAbi: FeeAssetHandlerAbi,
+  contractBytecode: FeeAssetHandlerBytecode as Hex,
+};
+
+export const StakingAssetHandlerArtifact = {
+  name: 'StakingAssetHandler',
+  contractAbi: StakingAssetHandlerAbi,
+  contractBytecode: StakingAssetHandlerBytecode as Hex,
+};
+
+export const MultiAdderArtifact = {
+  name: 'MultiAdder',
+  contractAbi: MultiAdderAbi,
+  contractBytecode: MultiAdderBytecode as Hex,
+};
+
+export const GSEArtifact = {
+  name: 'GSE',
+  contractAbi: GSEAbi,
+  contractBytecode: GSEBytecode as Hex,
+};
+
+// Verifier artifacts
+export const HonkVerifierArtifact = {
+  name: 'HonkVerifier',
+  contractAbi: HonkVerifierAbi,
+  contractBytecode: HonkVerifierBytecode as Hex,
+};
+
+export const MockVerifierArtifact = {
+  name: 'MockVerifier',
+  contractAbi: MockVerifierAbi,
+  contractBytecode: MockVerifierBytecode as Hex,
+};
+
+export const MockZkPassportVerifierArtifact = {
+  name: 'MockZkPassportVerifier',
+  contractAbi: MockZKPassportVerifierAbi,
+  contractBytecode: MockZKPassportVerifierBytecode as Hex,
+};
+
+// Re-export the verifier artifacts for backwards compatibility
+export const l1ArtifactsVerifiers = {
+  honkVerifier: HonkVerifierArtifact,
+};
+
+// Re-export the mock verifiers for backwards compatibility
+export const mockVerifiers = {
+  mockVerifier: MockVerifierArtifact,
+  mockZkPassportVerifier: MockZkPassportVerifierArtifact,
+};

package/src/l1_contract_addresses.ts

@@ -26,7 +26,14 @@ export const L1ContractsNames = [
 /** Provides the directory of current L1 contract addresses */
 export type L1ContractAddresses = {
   [K in (typeof L1ContractsNames)[number]]: EthAddress;
-} & { slashFactoryAddress?: EthAddress | undefined };
+} & {
+  slashFactoryAddress?: EthAddress | undefined;
+  feeAssetHandlerAddress?: EthAddress | undefined;
+  stakingAssetHandlerAddress?: EthAddress | undefined;
+  zkPassportVerifierAddress?: EthAddress | undefined;
+  gseAddress?: EthAddress | undefined;
+  dateGatedRelayerAddress?: EthAddress | undefined;
+};
 
 export const L1ContractAddressesSchema = z.object({
   rollupAddress: schemas.EthAddress,
@@ -41,69 +48,75 @@ export const L1ContractAddressesSchema = z.object({
   governanceProposerAddress: schemas.EthAddress,
   governanceAddress: schemas.EthAddress,
   slashFactoryAddress: schemas.EthAddress.optional(),
+  feeAssetHandlerAddress: schemas.EthAddress.optional(),
+  stakingAssetHandlerAddress: schemas.EthAddress.optional(),
+  zkPassportVerifierAddress: schemas.EthAddress.optional(),
+  gseAddress: schemas.EthAddress.optional(),
+  dateGatedRelayerAddress: schemas.EthAddress.optional(),
 }) satisfies ZodFor<L1ContractAddresses>;
 
 const parseEnv = (val: string) => EthAddress.fromString(val);
 
-export const l1ContractAddressesMapping: ConfigMappingsType<L1ContractAddresses> = {
-  rollupAddress: {
-    env: 'ROLLUP_CONTRACT_ADDRESS',
-    description: 'The deployed L1 rollup contract address.',
-    parseEnv,
-  },
+export const l1ContractAddressesMapping: ConfigMappingsType<
+  Omit<L1ContractAddresses, 'gseAddress' | 'zkPassportVerifierAddress' | 'dateGatedRelayerAddress'>
+> = {
   registryAddress: {
     env: 'REGISTRY_CONTRACT_ADDRESS',
     description: 'The deployed L1 registry contract address.',
     parseEnv,
   },
+  slashFactoryAddress: {
+    env: 'SLASH_FACTORY_CONTRACT_ADDRESS',
+    description: 'The deployed L1 slashFactory contract address',
+    parseEnv,
+  },
+  feeAssetHandlerAddress: {
+    env: 'FEE_ASSET_HANDLER_CONTRACT_ADDRESS',
+    description: 'The deployed L1 feeAssetHandler contract address',
+    parseEnv,
+  },
+  rollupAddress: {
+    description: 'The deployed L1 rollup contract address.',
+    parseEnv,
+  },
   inboxAddress: {
-    env: 'INBOX_CONTRACT_ADDRESS',
     description: 'The deployed L1 inbox contract address.',
     parseEnv,
   },
   outboxAddress: {
-    env: 'OUTBOX_CONTRACT_ADDRESS',
     description: 'The deployed L1 outbox contract address.',
     parseEnv,
   },
   feeJuiceAddress: {
-    env: 'FEE_JUICE_CONTRACT_ADDRESS',
     description: 'The deployed L1 Fee Juice contract address.',
     parseEnv,
   },
   stakingAssetAddress: {
-    env: 'STAKING_ASSET_CONTRACT_ADDRESS',
     description: 'The deployed L1 staking asset contract address.',
     parseEnv,
   },
   feeJuicePortalAddress: {
-    env: 'FEE_JUICE_PORTAL_CONTRACT_ADDRESS',
     description: 'The deployed L1 Fee Juice portal contract address.',
     parseEnv,
   },
   coinIssuerAddress: {
-    env: 'COIN_ISSUER_CONTRACT_ADDRESS',
     description: 'The deployed L1 coinIssuer contract address',
     parseEnv,
   },
   rewardDistributorAddress: {
-    env: 'REWARD_DISTRIBUTOR_CONTRACT_ADDRESS',
     description: 'The deployed L1 rewardDistributor contract address',
     parseEnv,
   },
   governanceProposerAddress: {
-    env: 'GOVERNANCE_PROPOSER_CONTRACT_ADDRESS',
     description: 'The deployed L1 governanceProposer contract address',
     parseEnv,
   },
   governanceAddress: {
-    env: 'GOVERNANCE_CONTRACT_ADDRESS',
     description: 'The deployed L1 governance contract address',
     parseEnv,
   },
-  slashFactoryAddress: {
-    env: 'SLASH_FACTORY_CONTRACT_ADDRESS',
-    description: 'The deployed L1 slashFactory contract address',
+  stakingAssetHandlerAddress: {
+    description: 'The deployed L1 stakingAssetHandler contract address',
     parseEnv,
   },
 };

package/src/l1_reader.ts

@@ -4,7 +4,7 @@ import { type L1ContractAddresses, l1ContractAddressesMapping } from './l1_contr
 
 /** Configuration of the L1GlobalReader. */
 export interface L1ReaderConfig {
-  /** The RPC Url of the ethereum host. */
+  /** List of URLs of Ethereum RPC nodes that services will connect to (comma separated). */
   l1RpcUrls: string[];
   /** The chain ID of the ethereum host. */
   l1ChainId: number;
@@ -15,20 +15,20 @@ export interface L1ReaderConfig {
 }
 
 export const l1ReaderConfigMappings: ConfigMappingsType<L1ReaderConfig> = {
-  l1RpcUrls: {
-    env: 'ETHEREUM_HOSTS',
-    description: 'The RPC Url of the ethereum host.',
-    parseEnv: (val: string) => val.split(',').map(url => url.trim()),
+  l1Contracts: {
+    description: 'The deployed L1 contract addresses',
+    nested: l1ContractAddressesMapping,
   },
   l1ChainId: {
     env: 'L1_CHAIN_ID',
     parseEnv: (val: string) => +val,
-    defaultValue: 31337,
     description: 'The chain ID of the ethereum host.',
   },
-  l1Contracts: {
-    description: 'The deployed L1 contract addresses',
-    nested: l1ContractAddressesMapping,
+  l1RpcUrls: {
+    env: 'ETHEREUM_HOSTS',
+    description: 'List of URLs of Ethereum RPC nodes that services will connect to (comma separated).',
+    parseEnv: (val: string) => val.split(',').map(url => url.trim()),
+    defaultValue: [],
   },
   viemPollingIntervalMS: {
     env: 'L1_READER_VIEM_POLLING_INTERVAL_MS',

package/src/l1_tx_utils/README.md

@@ -0,0 +1,177 @@
+# L1 Transaction Utils
+
+This module handles sending L1 txs, including simulating txs, choosing gas prices, estimating gas limits, monitoring sent txs, speeding them up, and cancelling them. Each instance of `L1TxUtils` is stateful, corresponds to a given **publisher** EOA, and tracks its in-flight txs.
+
+## Usage context
+
+Aside from bootstrapping (such as deploying L1 contracts), the Aztec node sends txs to L1 for the following purposes:
+
+### Sequencing
+
+As a sequencer (ie block proposer), the node sends blob txs proposing new L2 blocks. These txs may be part of a multicall where the proposer also votes for a proposal, slashes other validators, or invalidates a block. If block building fails, the sequencer may send a multicall without a block (and hence without blobs). These actions have a specific set of L1 blocks in which they may land (ie an L2 slot, which lasts 2-6 L1 slots), after which they "expire" and revert if mined. On each L2 slot, at most one L1 tx is in-flight.
+
+A given block proposer is chosen at random. While chances are low, it could be the case that the same proposer is chosen for two L2 slots in a row.
+
+There is an edge case in which block building fails at the beginning of the slot (for instance, if there are not enough L2 txs to build the block), which means only a vote or a slash is sent to L1, but then the block does get built, and is submitted in a separate L1 tx.
+
+### Proving
+
+As a prover, the node sends a tx with a validity proof for an epoch. These txs also have an expiration window, after which they revert if they'd land. No blobs are used. The cost is 1M-4M gas, and these txs are sent at most once per epoch, which is about 96-384 L1 slots.
+
+Provers typically try proving all epochs. Today the proof submission window is set to one epoch, meaning that each epoch must be proven during the next, so there is no overlap. If this window were to be extended, then we could have multiple L1 proving txs in flight, which must land in order.
+
+## Properties
+
+From the usage context above, we know that:
+
+- Each publisher EOA has typically only one in-flight tx at a time.
+- Every tx has an expiration time after which they'd revert if mined.
+
+## State transitions
+
+We keep all our **publishers** split by scope, where the scope may be _proving_ or _sequencing_. If sequencing, publishers are also scoped by validator address, so a node that runs multiple validators may use different publisher accounts for each validator, to avoid publicly linking them. Note that a publisher may belong to more than one scope.
+
+Each publisher account is in one of the following states, which is reflected from the state of the tx with the highest nonce it has sent:
+
+- `idle`: Ready to send a tx
+- `sent`: A tx has been sent and we are awaiting for it to be mined
+- `speed-up`: The tx has been replaced with the same tx but higher gas price
+- `cancelled`: The tx has expired so it has been replaced with a noop tx
+- `not-mined`: The tx has expired or was dropped and we are no longer monitoring it
+- `mined`: The tx or one of its replacements (ie a tx with the same nonce) has been mined
+
+With the following state transitions:
+
+| From | To | Condition | Effect |
+|-|-|-|-|
+| `idle` | `sent` | `send_tx` | A new tx is sent and nonce is consumed |
+| `sent` | `speed-up`| `time_since_last_sent > stall_time && retry_attempts < max_retries` | The requested tx is replaced with an equivalent but higher gas price |
+| `sent`, `speed-up` | `not-mined` | `current_time > tx_timeout && !cancel_on_timeout` | The tx times out, nonce manager is reset |
+| `sent`, `speed-up` | `cancelled` | `current_time > tx_timeout && cancel_on_timeout` | The tx times out and we replace it with a noop |
+| `sent`, `speed-up`, `cancelled` | `mined` | `get_nonce(latest) > tx_nonce` | The tx or a replacement is mined |
+| `cancelled` | `not-mined` | `current_time > cancel_tx_timeout` | Cancellation times out, nonce manager is reset |
+| `cancelled` | `not-mined` | `nonce no longer in mempool && time_passed > unseen_considered_dropped` | Cancel tx dropped from mempool, nonce manager is reset |
+
+Note that we do not transition back to `idle`.
+
+## Nonce Management
+
+The `L1TxUtils` class uses a `NonceManager` from viem to track and manage nonces for the publisher account:
+
+- **Nonce consumption**: When sending a new transaction, the nonce is consumed from the nonce manager, which increments the internal counter.
+- **Nonce reset**: The nonce manager is reset in the following scenarios:
+  - When a regular tx times out without being cancelled (`NOT_MINED` state)
+  - When a cancellation tx is dropped from the mempool
+  - When a cancellation tx itself times out
+  - When we decide not to send a cancellation due to interruption or the original tx being dropped
+
+The reset allows the next transaction to reuse the nonce if the current tx is no longer in the mempool by the time this next transaction is sent.
+
+## Time checks
+
+All time checks for speed ups and time outs are based on L1 time, not local time. When se send a tx, we assign the `sent_at` time to the time of the most recent L1 block. Using L1 time means that speed ups and time outs can be expressed in terms of L1 slots. It also means that we will wait for a new L1 block to be mined and check if our tx is present in that block before computing time outs or speed ups. 
+
+An edge case here is that, if an L1 slot is missed (ie there is no L1 block for that slot), we won't update time outs during that 12s period. Given how infrequent these are, we are fine with this tradeoff.
+
+## Pseudocode
+
+```python
+def send_and_monitor_tx(tx_request):
+  # Always consume a fresh nonce from the nonce manager
+  nonce = nonce_manager.consume()
+
+  # Build and send the transaction
+  tx = make_tx(tx_request, nonce)
+  state = create_state(tx, status='sent')
+  txs.push(state)
+  l1.send_tx(tx)
+
+  # State transitions differ based on whether this is a cancel tx
+  is_cancel_tx = state.cancelTxHashes.length > 0
+
+  # Monitor loop
+  loop:
+    # Check if interrupted
+    if interrupted:
+      break
+
+    # Check if the tx was mined
+    current_nonce = l1.get_nonce(latest)
+    if current_nonce > nonce:
+      # Try to find the receipt from all tx attempts
+      for tx in state.txHashes + state.cancelTxHashes:
+        if receipt = l1.get_tx_receipt(tx):
+          state.status = 'mined'
+          return receipt
+      # Unknown tx was mined with our nonce
+      state.status = 'mined'
+      raise unknown_mined_tx_error
+
+    # Check if cancel tx dropped from mempool (only for cancellations)
+    pending_nonce = l1.get_nonce(pending)
+    if is_cancel_tx and pending_nonce < nonce and time_passed > unseen_considered_dropped:
+      state.status = 'idle'
+      nonce_manager.reset()
+      raise dropped_transaction_error
+
+    # Check if tx has timed out
+    if is_timed_out(state, l1_timestamp):
+      if is_cancel_tx or !cancel_on_timeout:
+        # Either already a cancel tx or configured not to cancel
+        state.status = 'not-mined'
+        nonce_manager.reset()
+        raise timeout_error
+      else:
+        # Send cancellation in background
+        run_in_background attempt_tx_cancellation(state)
+        raise timeout_error
+
+    # Speed up if stalled and have retries left
+    if time_since_last_sent > stall_time and attempts < max_attempts:
+      replacement_tx = make_tx(tx_request, nonce, bump_gas_price(state.gasPrice))
+      state.status = is_cancel_tx ? 'cancelled' : 'speed-up'
+      state.tx_hashes.push(send_tx(replacement_tx))
+      state.last_sent_at = now
+      continue
+
+    sleep(check_interval)
+
+def attempt_tx_cancellation(state):
+  # Check if original tx still in mempool
+  if l1.get_nonce(pending) < state.nonce:
+    state.status = 'not-mined'
+    nonce_manager.reset()
+    return
+
+  # Send noop tx with same nonce but higher gas
+  cancel_tx = make_noop_tx(state.nonce, bump_gas_price(state.gasPrice))
+  state.cancelTxHashes.push(send_tx(cancel_tx))
+  state.status = 'cancelled'
+
+  # Monitor the cancellation in background
+  run_in_background monitor_transaction(state)
+```
+
+## Publisher selection
+
+When sending a tx for a given scope, we choose from all publishers for the scope in the following order:
+
+- `idle`: The publisher is ready to be used and has not sent any txs recently.
+- `mined`: The publisher has mined a tx and is ready for a new one.
+- `speed-up`, `sent`: There is a tx in-flight, new one will be enqueued after (not eligible unless `publisherAllowInvalidStates` is set).
+- `cancelled`: There is a tx in-flight caused by a time-out mining the previous one, new tx will be enqueued after (not eligible unless `publisherAllowInvalidStates` is set).
+- `not-mined`: The previous tx timed out or was dropped, new tx will reuse the same nonce if previous one is no longer in the mempool, or pick the next otherwise (not eligible unless `publisherAllowInvalidStates` is enabled).
+
+If there is more than one publisher in the same state to choose from, we prefer choosing based on:
+1. Highest balance first
+2. Least recently used (based on `lastMinedAtBlockNumber`)
+
+Available publishers should be filtered by balance, ensuring that the given EOA has enough funds to send the tx, and possibly replace it with a larger gas price. If we detect a publisher account has not enough gas, we should warn (bonus points if we warn before running out).
+
+Note that selection is not handled by the `L1TxUtils` class but by the `PublisherManager`.
+
+## API
+
+- `sendTransaction`: Sends an L1 tx and returns the tx hash. Returns when the tx has been sent. Consumes a nonce from the nonce manager.
+- `monitorTransaction`: Monitors a sent tx and speeds up or cancels it. Returns when mined or timed out. May reset the nonce manager on timeout.
+- `sendAndMonitorTransaction`: Combines sending and monitoring in a single call.