[WIP] Assign Deposit Handling #48

dkuthoore · 2025-10-28T22:15:20Z

Summary

This PR adds support for AssignDeposit intentions, working towards the end-to-end vault seeding flow. The node can now discover on-chain deposits (ERC-20 and ETH, both internal (from contracts) and external(from EOAs), ingest them into a new deposits table, validate and match deposits to AssignDeposit intentions, and credit vault balances at publish time while marking deposits as assigned. The flow is fully auditable and prevents double assignment.

Changes

Database
- Added deposits table and indexes:
  - Columns: id, tx_hash, transfer_uid (UNIQUE), chain_id, depositor (lowercased), token (ERC-20 address or 0x0 for ETH), amount (wei), credited_vault, assigned_at.
- Updated schema verification to include deposits.
Utilities (DB)
- src/utils/deposits.ts:
  - insertDepositIfMissing: Idempotent insert by transfer_uid.
  - findExactUnassignedDeposit: Select an exact, unassigned deposit by depositor, token, amount, chain_id.
  - markDepositAssigned: Atomically flip assigned_at and persist credited_vault.
Proposer: Chain introspection and vault validation
- validateVaultIdOnChain(vaultId): Ensures 1 <= vaultId < nextVaultId() using VaultTracker.nextVaultId().
- Introduced shared block-range helper and a 7-day default lookback (~50,400 blocks) for discovery.
Deposit discovery and ingestion
- ERC-20: discoverAndIngestErc20Deposits({ controller, token, chainId, fromBlockHex?, toBlockHex? }) via Alchemy getAssetTransfers with category: ['erc20'] and contractAddresses: [token].
- ETH: discoverAndIngestEthDeposits({ controller, chainId, fromBlockHex?, toBlockHex? }) via Alchemy getAssetTransfers with category: ['internal', 'external'] (supports deposits from contracts and EOAs).
- Generic helper consolidates block-range and ingestion logic; ERC-20/ETH functions delegate to it.
- Each transfer is stored with a stable transfer_uid (Alchemy uniqueId if present; otherwise a deterministic fallback) to ensure idempotency.
AssignDeposit validation and handler
- validateAssignDepositStructure(intention):
  - Enforces 1:1 inputs[i] ↔ outputs[i] mapping.
  - Enforces per-index equality of asset, amount, chain_id.
  - Requires outputs[i].to (no to_external) and validates the vault on-chain.
  - Enforces zero fees: all totalFee amounts are "0"; proposerTip and protocolFee empty; agentTip absent or empty.
  - Authorization is implied by discovery/selection: depositor must equal the recovered controller.
- handleIntention (AssignDeposit branch):
  - Parses optional fromBlock/toBlock hints from inputs[i].data (hex).
  - Discovers deposits (ERC-20 or ETH) for the controller into VaultTracker.
  - Selects one exact unassigned deposit per input (no splitting/aggregation).
  - Builds proof entries: { token, to, amount, deposit_id, depositor }.
  - Caches execution with from: 0 sentinel (no source vault balance is decremented for assignment).
Publish-time assignment and crediting
- In publishBundle, for AssignDeposit executions:
  - markDepositAssigned(deposit_id, to) to atomically assign the deposit row (guards against double assignment).
  - Credit the destination vault’s balance by amount for token.
- Other intention types continue to use updateBalances(from, to, token, amount).
Tests
- test/integration/deposits.db.test.ts:
  - Verifies idempotent insert via transfer_uid.
  - Verifies exact-match selection and that assigned deposits cannot be re-selected.
  - Verifies assignment persists credited_vault and sets assigned_at.

Notes

AssignDeposit allows assigning to any valid vault ID (not necessarily controlled by the depositor).
Depositor authorization is enforced by checking the on-chain transfer origin (discovery) against the intention controller.
No partial assignment in this version; each input maps to exactly one deposit row of the same amount.
Default lookback uses a constant (~50,400 blocks ≈ 7 days). Can be made configurable later.
Uses Alchemy’s decoded getAssetTransfers for reliability, pagination (pageKey), and structured data across ERC-20 and ETH.

Next Steps

the proposer.ts file is getting really large, especially with the specific functions for handling createVault and AssignDeposit intentions. My plan is to extract the logic for handling specific intentions into a dedicated directory, so the proposer.ts file is cleaner and more easily readable. This aligns with our task of defining our preliminary Intention types, we will have dedicated files for handling each of them.

dkuthoore · 2025-10-29T18:47:35Z

Latest commit changes:

Extract intention-specific logic from proposer into handlers

Extracted the CreateVault and AssignDeposit handling logic from src/proposer.ts into dedicated handler modules.
New files:
- src/utils/intentionHandlers/CreateVault.ts: encapsulates vault creation, event parsing, controller mapping, and seeding trigger.
- src/utils/intentionHandlers/AssignDeposit.ts: encapsulates validation, on-chain deposit discovery (ERC-20 and ETH), exact-match selection, and proof building.
src/proposer.ts now delegates to these handlers, improving readability and separation of concerns while preserving existing behavior (including publish-time assignment and balance updates).

pemulis · 2025-10-29T23:37:07Z

scripts/shared/db-setup.js

+  depositor TEXT NOT NULL,
+  token TEXT NOT NULL,
+  amount NUMERIC(78, 0) NOT NULL,
+  credited_vault TEXT,


Should remove credited_vault from the deposits table or make it into an array of credited_vaults, since there may be more than one. Probably just remove it since it's redundant and we can build the array from deposit_assignment_events.

pemulis · 2025-10-29T23:41:41Z

scripts/shared/db-setup.js

+-- Create indexes for deposits table
+CREATE INDEX IF NOT EXISTS idx_deposits_tx_hash ON deposits(tx_hash);
+CREATE INDEX IF NOT EXISTS idx_deposits_depositor ON deposits(depositor, chain_id);
+CREATE INDEX IF NOT EXISTS idx_deposits_token ON deposits(token);


Might want to include chain_id in this index.

pemulis · 2025-10-29T23:51:32Z

scripts/shared/db-setup.js

 			if (!forceDropConfirm) {
 				console.log(chalk.red('\n⚠️  WARNING: This will DELETE ALL DATA in the following tables:'))
-				console.log(chalk.red('  - bundles, cids, balances, nonces, proposers, vaults'))
+				console.log(chalk.red('  - bundles, cids, balances, nonces, proposers'))


This line should keep vaults, but also add deposit_assignment_events and deposits.

pemulis · 2025-10-29T23:58:00Z

src/proposer.ts

+ */
+export async function validateVaultIdOnChain(vaultId: number): Promise<void> {
+	// Basic sanity
+	if (!Number.isInteger(vaultId) || vaultId < 1) {


We should allow 0 as the vaultId since that's the protocol's vault but disallow any < 0.

pemulis · 2025-10-29T23:59:42Z

src/proposer.ts

+}
+
+/**
+ * Computes block range hex strings for Alchemy getAssetTransfers requests,


Are we getting locked into an Alchemy dependency here or is this something available in generalized libraries for interacting with nodes? Okay if we accept an Alchemy dependency for the moment, just asking.

i can look into it further but all of these methods should be available and pretty similarly structured on any blockchain node/data provider !

pemulis · 2025-10-30T00:21:24Z

src/proposer.ts

+ * and ingests them into the local `deposits` table via idempotent inserts.
+ */
+async function discoverAndIngestEthDeposits(params: {
+	controller: string


See earlier note about leaving controller unspecified and getting all ETH deposits from any address.

pemulis · 2025-10-30T00:28:07Z

src/proposer.ts


-	// Note: Vault-controller mapping is created from on-chain VaultCreated events
+	// Seed the proposer's own vault-to-controller mapping
+	await seedProposerVaultMapping()


Why did this get added back in? We should still handle this through creating a vault onchain, and then finding what vault is associated with the proposer's address as a controller.

pemulis · 2025-10-30T00:28:13Z

src/proposer.ts

 * This is crucial for allowing the proposer to sign and submit seeding intentions.
 */
-// Removed seedProposerVaultMapping(); creation is handled via on-chain events
+async function seedProposerVaultMapping() {


See note above.

pemulis · 2025-10-30T00:40:47Z

src/utils/intentionHandlers/AssignDeposit.ts

+		const input: IntentionInput = intention.inputs[i]
+		const output: IntentionOutput = intention.outputs[i]
+
+		// Optional discovery hints in input.data


Oh, interesting!

pemulis · 2025-10-30T00:44:45Z

src/utils/intentionHandlers/AssignDeposit.ts

+		execution: [
+			{
+				intention,
+				from: 0,


Why from: 0? Should this be from the proposer's address? May be fine as-is since we're working on the proof and execution payloads as a separate task.

Wait, nevermind. from is the vault number, so it should be 0, you're right.

…le log message with all table names

…from alchemy getTransfers call, add lastCheckedBlock variable

dkuthoore · 2025-10-30T02:34:38Z

Changes since feedback

Database
- Removed credited_vault from deposits (redundant; derived from deposit_assignment_events).
- Dropped the deposits(credited_vault) index.
- Updated idx_deposits_token to a composite index on (token, chain_id).
- Adjusted destructive warning list to: bundles, cids, balances, vaults, proposers, deposits, deposit_assignment_events.
Validation
- Moved validateVaultIdOnChain and validateAssignDepositStructure to src/utils/validator.ts.
- Allowed vault ID 0 (protocol vault) and disallowed negative IDs.
- In proposer.ts, added thin wrappers to inject contract dependency into validators.
Deposit Discovery
- Removed controller parameter from:
  - discoverAndIngestDeposits
  - discoverAndIngestErc20Deposits
  - discoverAndIngestEthDeposits
- Removed fromAddress from Alchemy getAssetTransfers requests; now sweep all transfers to VAULT_TRACKER_ADDRESS within the block range.
- Added an in-memory per-chain cursor (lastCheckedBlockByChain) that advances to the last scanned block after each run.
Proposer
- Removed seedProposerVaultMapping and its invocation during initialization; rely on on-chain VaultCreated events for vault-controller mapping.
- Kept proposer clean by delegating validation via wrappers and maintaining discovery logic separation.
AssignDeposit Handler
- Updated context to new discovery signatures (no controller param).
- Continued to enforce authorization by selecting deposits by depositor (the intention’s controller) and asset/chain when assigning.

pemulis · 2025-10-30T02:45:30Z

src/proposer.ts

-	}
-	// Ensure contracts are initialized
+// Wrapper to use validator's on-chain vault ID validation with contract dependency
+const validateVaultIdOnChain = async (vaultId: number): Promise<void> => {


I think we could fully extract these validator functions to utils/validator.js, instead of using base validator functions, but I won't be too fussy!

KagemniKarimu

this is some serious work! Thank you @dkuthoore :)

KagemniKarimu · 2025-10-30T02:56:37Z

test/integration/deposits.db.test.ts

+const TEST_UID = (n: number) => `${TEST_TX}:${n}`
+const CTRL = '0xCcCcCcCcCcCcCcCcCcCcCcCcCcCcCcCcCcCcCcCc'
+const TOKEN = '0x1111111111111111111111111111111111111111'
+const ZERO = '0x0000000000000000000000000000000000000000'


sidenote to maybe move these to the new test fixtures from #51 in a future PR !

dkuthoore added 9 commits October 28, 2025 18:14

create deposits table

9f670dc

create deposit helper functions

a82c54e

create on-chain vault validator

bcb380c

create ERC20 and ETH deposit discovery functions

a460d3c

create AssignDeposit validator function

1a958cf

create AssignDeposit handler in proposer

6569490

add AssignDeposit logic to publishBundle

297b611

create deposits db tests

5df347a

formatting fixes

ad7e965

dkuthoore changed the title ~~Dk/assign deposit~~ Assign Deposit Handling Oct 28, 2025

dkuthoore changed the title ~~Assign Deposit Handling~~ [WIP] Assign Deposit Handling Oct 28, 2025

dkuthoore and others added 2 commits October 29, 2025 14:43

extract intention-specific logic into util files

b5a094d

Merge branch 'main' into dk/assignDeposit

77ed0e1

dkuthoore added 2 commits October 29, 2025 14:53

lint fixes

1cf8c73

function name change

718f8df

dkuthoore marked this pull request as ready for review October 29, 2025 19:00

dkuthoore requested a review from pemulis as a code owner October 29, 2025 19:00

dkuthoore requested review from KagemniKarimu and paulomilitante October 29, 2025 19:00

dkuthoore added 8 commits October 29, 2025 15:15

add new deposit assignment events table

7ead857

add partial assignment functions to deposit utility

94a7e3a

Update AssignDeposit handler to support partial assignment

733b208

update proposer to createAssignmentEvent

fe13013

update deposits db test

3274c18

remove unused deposits functions, update test, update README

a7f34dc

format fixes

15be675

remove alchemy uniqueID for transferUid

13bbb25

pemulis requested changes Oct 30, 2025

View reviewed changes

remove credited_vault column, add chain_id to token index, fixed cono…

30b2c46

…le log message with all table names

dkuthoore added 3 commits October 29, 2025 22:01

extract validator functions from proposer into validator file

ad56d71

remove controller from discovery function inputs, remove fromAddress …

e1bc128

…from alchemy getTransfers call, add lastCheckedBlock variable

remove seedProposerVaultMapping function

49c4d82

pemulis approved these changes Oct 30, 2025

View reviewed changes

KagemniKarimu approved these changes Oct 30, 2025

View reviewed changes

KagemniKarimu reviewed Oct 30, 2025

View reviewed changes

pemulis merged commit 0b1c9e3 into main Oct 30, 2025
2 checks passed

This was referenced Oct 30, 2025

Validation Updates #52

Merged

Extract some testing constants into textFixtures #54

Merged

[WIP] Assign Deposit Handling #48

[WIP] Assign Deposit Handling #48

Uh oh!

Conversation

dkuthoore commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Notes

Next Steps

Uh oh!

dkuthoore commented Oct 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pemulis Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkuthoore commented Oct 30, 2025

Changes since feedback

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KagemniKarimu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dkuthoore commented Oct 28, 2025 •

edited

Loading

pemulis Oct 30, 2025 •

edited

Loading