Skip to content

Add fleet package for acting on shared kernels - #20

Merged
elffjs merged 7 commits into
mainfrom
deploy_admin_module
May 12, 2026
Merged

elffjs merged 7 commits into
mainfrom
deploy_admin_module

Conversation

@elffjs

@elffjs elffjs commented May 11, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds a small fleet subpackage that lets a fleet EOA submit regular-mode UserOps against a Kernel V3.1 shared account that DIMO accounts (accounts#62) already provisioned + installed. No existing production caller of the parent package is affected.

What the package does

Client.SendCall Plain regular-mode UserOp — encoded with the default-mode + secondary nonce key for the weighted-ECDSA validator, signed by the fleet PK via EIP-191 personal-sign, sponsored + submitted through ZeroDev. The one method callers (e.g. kaufmann) routinely exercise.
Client.IsFleetInstalled Defensive eth_getCode + isAllowedSelector probe. Returns true only when the kernel exists AND the weighted-ECDSA validator is installed with permission for executeUserOp. Useful sanity check before sending the first UserOp against a kernel the admin claimed to provision.

Pure helpers also exported so a caller that wants to build/sign UserOps out-of-band (HSM, KMS, signing oracle) can do so without taking the full Client:

  • NonceKey / NonceKeyDefaultModeForWeightedEcdsa / NonceKeyAsUint192 / FullNonce
  • PersonalSignUserOpHash

Parent-package changes — just two

After successive trims to the minimum, the parent package only gets:

  • Entrypoint.GetNonceWithKey(account, key *big.Int) — the existing GetNonce uses a sudo-friendly key encoding that won't route to a secondary validator. Adding a custom-key form lets the fleet client compose the right 256-bit nonce.
  • GetUserOperationReceiptResponse.Nonce typed as *hexutil.Big — real bug fix unrelated to scope: bundlers return the uint256 nonce with leading zeros stripped, which produces odd-length hex that *hexutil.Bytes rejects (json: cannot unmarshal hex string of odd length). We hit this on the first real run.

Nothing else in the parent package changed. UserOperation, PackUserOperation, and PaymasterClient.SponsorUserOperation are identical to main. Existing kaufmann / go-transactions usages are bit-identical at runtime.

EIP-191 footgun (the one subtle thing)

The weighted-ECDSA validator does NOT verify a raw secp256k1 sig over the userOpHash. It verifies personalSign(userOpHash) — i.e. ecdsa_sign(keccak256("\x19Ethereum Signed Message:\n32" || userOpHash)). The existing account.SmartAccountPrivateKeySigner.SignUserOperationHash does a raw sign, correct for the ECDSA sudo path but wrong for weighted-ECDSA. fleet.PersonalSignUserOpHash is a separate helper for that reason.

Tests

Three byte-level tests against fixtures dumped from the ZeroDev TS SDK (zdexplore/08-go-vectors.ts) with deterministic test keys:

  • TestNonceKeyDefaultMode — the 24-byte nonce key encoding for a regular-mode UserOp targeting the weighted-ECDSA validator.
  • TestPersonalSignDigestMatchesSdk — EIP-191 digest matches what viem produces.
  • TestValidationIdForWeightedEcdsa — 21-byte vId (0x01 || weightedEcdsaAddr) used by IsFleetInstalled.

examples/fleet-demo

Wires accounts → kernel → fleet end-to-end:

  1. POST {email, providedSignerAddress} to accounts. Returns { walletAddress } after accounts did all on-chain work itself.
  2. IsFleetInstalled(kernel) — expected true on first probe.
  3. One SendCall(noop) to demonstrate fleet authority on the kernel.

No EnableArtifact, no SendInstallAndCall, no factory bits. The whole binary is ~95 lines of substance.

Test plan

  • go test ./... passes
  • go vet ./... clean
  • go build ./... clean
  • End-to-end run against accounts.dimo.org (with accounts#62 merged) — should print kernelAddress, installed=true, then userOpHash + txHash

🤖 Generated with Claude Code

elffjs and others added 5 commits May 11, 2026 15:03
Lets a holder of a "fleet" EOA install itself as a weighted-ECDSA secondary
validator on a Kernel V3.1 account that was provisioned by an admin service
(e.g. DIMO accounts) using an enable-mode UserOp, then act on the account
with plain regular-mode UserOps thereafter.

The fleet package ships its own UserOp builder, nonce encoder, signature
envelope, and signer because the existing Client is opinionated around "I
am the AA wallet owner" and the secondary-validator path has different
nonce-key encoding, an enable-mode signature wrapper, and EIP-191
personal-sign (not raw sign) over the userOpHash.

Public surface:

  fleet.Client.SendInstallAndCall  enable-mode UserOp; installs the
                                   weighted-ECDSA validator with selector
                                   permission for executeUserOp and runs
                                   the call atomically. Attaches factory
                                   bits when eth_getCode(kernel) is empty.
  fleet.Client.SendCall            plain regular-mode UserOp for any time
                                   after install has landed.
  fleet.Client.IsFleetInstalled    eth_call(isAllowedSelector) probe so the
                                   caller can pick between the two.
  fleet.EnableTypedData            EIP-712 typed-data shape the admin
                                   signs; same value used to verify the
                                   enable signature on the fleet side.

Pure encoders (FactoryData, NonceKey, SelectorData, EnableEnvelope,
WeightedEcdsaConfig.EncodeInstallData, PersonalSignUserOpHash) are
exported so a caller that wants to build/sign UserOps out-of-band can do
so without taking the full Client.

Parent-package changes are additive:

  - UserOperation: Factory + FactoryData fields (with JSON marshal/
    unmarshal). PackUserOperation hashes initCode from factory ||
    factoryData when factory is set; identical to the previous behavior
    when not, so existing callers see no hash change.
  - Entrypoint.GetNonceWithKey(account, key *big.Int) — custom-key form
    needed when routing UserOps to a non-default validator.
  - PaymasterClient.SponsorUserOperationWithStub(op) — variant that does
    not overwrite op.Signature, for callers that need to ship their own
    stub (the enable-mode envelope's stub differs from the default
    65-byte dummy).

Tests exercise every encoder against byte-level fixtures dumped from the
ZeroDev TypeScript SDK with deterministic keys: weighted-ECDSA install
data, selector data, nonce keys in both modes, enable-typed-data EIP-712
hash, artifact signature recovery, EIP-191 personal-message digest,
factory data layout, envelope round-trip.

examples/fleet-demo wires the whole flow end-to-end against
accounts.dimo.org and a ZeroDev bundler.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
fixSelectorData and fixValidatorInstallData were drafted as top-of-file
fixtures but ended up inlined in their respective tests after I caught
hand-alignment errors in the originals. Leaving the misaligned constants
in the file makes the compiler complain about unused declarations and
muddies what the tests actually check against.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pairs with DIMO-Network/accounts#61: the accounts service now returns the
Turnkey EOA as sudoSignerAddress and no longer deploys the kernel
sudo-only. The demo plumbs that field into EnableArtifact.UserSignerAddress
so SendInstallAndCall can build factoryData and the EntryPoint deploys
the kernel as the first step of the install-carrying UserOp.

Decoder treats sudoSignerAddress as optional so the binary still parses
responses from an accounts service that hasn't shipped the change yet —
if it's missing and the kernel is already deployed (older accounts
versions), the factory branch is skipped and the demo works as before;
if missing and the kernel is undeployed, run() warns explicitly that
SendInstallAndCall will fail with a sender-address mismatch.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The bundler returns the UserOp's uint256 nonce with leading zeros stripped,
which produces an odd-length hex string whenever the top nibble is zero
(common, since the nonce key encodes a validator-mode byte at position 0
that is 0x00 for the default-mode case). hexutil.Bytes rejects odd-length
strings, blowing up the entire receipt decode with

    json: cannot unmarshal hex string of odd length into Go struct field
    GetUserOperationReceiptResponse.nonce of type hexutil.Bytes

Switch the field to *hexutil.Big to match its semantic (uint256 integer)
and the convention the rest of the receipt's numeric fields already use.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ernel

DIMO-Network/accounts#62 cut accounts over to doing the entire deploy +
install server-side, so the fleet package no longer needs the enable-mode
path. The only thing a caller (kaufmann) does with a freshly registered
account is submit regular-mode UserOps signed by the fleet's EOA. Strip
everything else.

Deleted:

  fleet/selectordata.go    Enable typed-data selector blob (admin-only).
  fleet/typeddata.go       Enable EIP-712 typed-data shape (admin-only).
  fleet/envelope.go        Enable signature envelope wrapper (admin-only).
  fleet/factory.go         FactoryData encoder (admin-only).
  fleet/validator.go       WeightedEcdsaConfig.EncodeInstallData was only
                           used for the install path; the runtime sign
                           path bypasses it. ValidationIdForWeightedEcdsa
                           moved into install_check.go.
  fleet/bigint.go          Helper for the now-removed install data
                           encoding.

  Client.SendInstallAndCall and EnableArtifact removed from client.go.
  NonceKeyEnableModeForWeightedEcdsa removed from nonce.go.
  ValidatorModeEnable / CallTypeDelegateCall constants removed.

Kept:

  Client.SendCall            plain regular-mode UserOp, the only flow
                             callers exercise now.
  Client.IsFleetInstalled    defensive probe of eth_getCode +
                             isAllowedSelector; useful sanity check.
  NonceKeyDefaultModeForWeightedEcdsa + helpers.
  PersonalSignUserOpHash.
  Tests for the surviving encoders.

examples/fleet-demo updated to match the new accounts API shape (response
is just { walletAddress }) and to skip the install dance entirely — it
just registers, probes IsFleetInstalled, and submits two noop UserOps to
prove fleet authority on the kernel.

Net: -776 lines, +174 lines, no test loss for surviving code.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@elffjs elffjs changed the title Add fleet package for secondary-validator UserOps Add fleet package for acting on shared kernels May 11, 2026
elffjs and others added 2 commits May 11, 2026 16:35
It was load-bearing back when the first UserOp carried the install (the
second one was the proof that regular-mode worked after install). Now
both noops are plain regular-mode and the second one is just running the
same code path with a different customNonceKey — no additional signal.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
After accounts#62 moved all on-chain provisioning + install work
server-side, the fleet flow no longer needs:

  - UserOperation.Factory / FactoryData fields
  - PackUserOperation initCode hashing of factory||factoryData
  - PaymasterClient.SponsorUserOperationWithStub

These were only useful for the enable-mode install flow the fleet package
no longer implements. Reverting them keeps the parent package surface
identical to main for everything except the two changes that genuinely
support the trimmed flow:

  - Entrypoint.GetNonceWithKey (custom-key form for routing UserOps to a
    non-default validator)
  - GetUserOperationReceiptResponse.Nonce typed as *hexutil.Big (real bug
    fix — bundlers strip leading zeros, *hexutil.Bytes rejects odd-length
    hex)

fleet/client.go: SendCall now uses PaymasterClient.SponsorUserOperation
directly. The 65-byte dummy stub that method writes is exactly what the
weighted-ECDSA getStubSignature path expects for a single-signer
regular-mode UserOp, so no custom stub needed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@elffjs
elffjs marked this pull request as ready for review May 12, 2026 17:27
@elffjs
elffjs merged commit 99f41b2 into main May 12, 2026
2 checks passed
@elffjs
elffjs deleted the deploy_admin_module branch May 12, 2026 17:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant