feat: add crypto-payroll blueprint

[ayushsingh82]

Summary

This PR adds crypto-payroll — a new solution blueprint that demonstrates policy-gated bulk USDC payroll using Dfns wallets and the Dfns Policy Engine.

It fills a documented but unimplemented gap: docs.dfns.co/solutions/automate-payments describes this use case but no runnable code existed in the repo.

---

What it does

A finance team runs a payroll CSV through a Dfns-secured treasury wallet. Every transfer is intercepted by a Wallets:Sign policy before it hits the chain:

• Transfers at or below the configured limit (AUTO_APPROVE_LIMIT_USDC, default 1000 USDC) are auto-approved by a Dfns Service Account acting as a programmatic checker
• Transfers above the limit stay Pending and require a human approver to accept or reject them — a classic maker/checker workflow

Finance team                  Dfns Policy Engine           Service Account (checker)
     |                               |                              |
     |-- npm run payroll:run ------->|                              |
     |   (CSV: employees · USDC)    |                              |
     |                              |-- approval Pending --------->|
     |                              |   (for each transfer)        | amount <= 1000 USDC?
     |                              |<-- createApprovalDecision ---|
     |                              |    Approved / left Pending   |
     |<-- transfer broadcasts ------|                              |
     |                              |                              |
Human approver                      |                              |
     |-- npm run approvals:approve ->|                             |
     |   (large amounts only)       |                              |
     |<-- transfer broadcasts ------|                              |

---

Dfns features showcased

Feature	How it's used
wallets.transferAsset	Sends ERC-20 USDC to each employee with kind: 'Erc20'
Wallets:Sign policy	Intercepts every transfer before it reaches the chain
AlwaysTrigger rule	Policy fires on every transfer from the tagged wallet
walletTags filter	Policy only targets wallets tagged payroll — does not interfere with other wallets
RequestApproval action	Routes transfers to a 1-of-2 approval group
serviceAccountsCanApprove	Allows the checker service account to auto-approve small transfers
policies.listApprovals	Checker fetches all pending decisions
policies.createApprovalDecision	Checker posts Approved or Denied with a reason string
externalId on transfers	Each transfer carries a deterministic ID derived from run date + employee address — prevents double-payment if payroll is re-run
Audit trail	Every approval decision (who, when, why) is recorded in Dfns and queryable via API

---

Why this is different from programmable-policy

The existing programmable-policy blueprint intercepts broadcastTransaction calls and decodes ABI-encoded smart contract call data. This blueprint operates at the transfer level (wallets.transferAsset) and enforces business rules based on amount and token contract — a different policy layer targeting a different real-world workflow.

---

Files added

crypto-payroll/
├── scripts/
│   ├── DfnsCommon.ts     # shared Dfns client and env config
│   ├── Setup.ts          # create the Wallets:Sign approval policy
│   ├── RunPayroll.ts     # read CSV and initiate USDC transfers
│   ├── AutoReview.ts     # service-account checker: auto-approve or flag
│   ├── ListPending.ts    # list transfers pending human review
│   ├── Approve.ts        # manually approve a transfer
│   ├── Reject.ts         # manually reject a transfer
│   ├── Status.ts         # show recent transfer statuses
│   └── ListUsers.ts      # list users to find POLICY_USER_ID
└── data/
    └── employees.csv     # payroll input: name, address, amount_usdc

---

How to run

cd crypto-payroll
npm install
cp .env.example .env   # fill in Dfns credentials + treasury wallet ID

npm run users:list              # find POLICY_USER_ID
npm run policy:create           # create the Wallets:Sign policy in Dfns
# tag your treasury wallet with "payroll" in the Dfns dashboard
npm run payroll:run             # send this month's payroll
npm run approvals:auto          # auto-approve transfers within the limit
npm run approvals:list          # see what needs human sign-off
npm run approvals:approve <id>  # approve a large transfer manually
npm run status                  # check on-chain transfer statuses

Runs on Ethereum Sepolia with testnet USDC from the Circle faucet. No paid external services required.

---

Test plan

• npm run policy:create creates an active Wallets:Sign policy in Dfns
• npm run payroll:run initiates one transfer per CSV row, each landing in Pending
• npm run approvals:auto approves rows at or below AUTO_APPROVE_LIMIT_USDC and leaves larger ones untouched
• npm run approvals:approve <id> moves a large transfer from Pending to Approved and it broadcasts
• npm run approvals:reject <id> denies a transfer and it does not broadcast
• Re-running payroll with the same CSV and run date does not create duplicate transfers (idempotency via externalId)
• npm run status shows Confirmed for approved and broadcast transfers

🤖 Generated with Claude Code

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​tsx@​4.22.4
	npm/​viem@​2.53.1

View full report

[socket-security]

Caution

Review the following alerts detected in dependencies.

According to your organization's Security Policy, you must resolve all "Block" alerts before proceeding. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Block		Potential code anomaly (AI signal): npm esbuild is 90.0% likely to have a medium risk anomaly Notes: The esbuild package uses a postinstall install.js script to download platform-specific binaries from registry sources and verify them via hashes. While hash verification reduces risk, the elevated postinstall action creates a potential code-execution surface if the script is tampered with. Audit install.js and its endpoints, ensure artifacts are strictly verified against known hashes, and test in controlled environments before deployment. Confidence: 0.90 Severity: 0.60 From: ? → npm/tsx@4.22.4 → npm/esbuild@0.28.1 ℹ Read more on: This package | This alert | What is an AI-detected potential code anomaly? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: An AI system found a low-risk anomaly in this package. It may still be fine to use, but you should check that it is safe before proceeding. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/esbuild@0.28.1. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Block		Potential code anomaly (AI signal): npm ox is 62.0% likely to have a medium risk anomaly Notes: This fragment is primarily a CPU-intensive proof-of-work/salt-mining implementation using worker-thread parallelism plus an async fallback. It includes input validation, structured error propagation, and abort handling, and it does not show classic malware behaviors (no network/file/process/persistence or dynamic execution in the snippet). The dominant security concern is potential resource-exhaustion/DoS if untrusted callers can control workerCount/count/chunkSize, and secondary concern is leakage of progress/rate metrics into application callbacks/logging. Overall: likely intended PoW functionality but potentially abuse-prone in the wrong threat model. Confidence: 0.62 Severity: 0.50 From: ? → npm/viem@2.53.1 → npm/ox@0.14.29 ℹ Read more on: This package | This alert | What is an AI-detected potential code anomaly? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: An AI system found a low-risk anomaly in this package. It may still be fine to use, but you should check that it is safe before proceeding. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/ox@0.14.29. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Block		Potential code anomaly (AI signal): npm ox is 60.0% likely to have a medium risk anomaly Notes: This module implements parallel WebAssembly computation using Node worker_threads and browser Web Workers, including dynamic worker script execution (Node eval:true and browser Blob URL). It communicates only via postMessage and does not show network exfiltration, credential theft, or persistence within this snippet. The main risks are supply-chain/execution boundary concerns from dynamic worker code and potential CPU/DoS impact if the mining parameters are attacker-influenced. Overall: likely intended for compute work, but should be reviewed and guarded with strict input controls and hardened worker creation. Confidence: 0.60 Severity: 0.60 From: ? → npm/viem@2.53.1 → npm/ox@0.14.29 ℹ Read more on: This package | This alert | What is an AI-detected potential code anomaly? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: An AI system found a low-risk anomaly in this package. It may still be fine to use, but you should check that it is safe before proceeding. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/ox@0.14.29. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Block		Potential code anomaly (AI signal): npm ox is 70.0% likely to have a medium risk anomaly Notes: This dependency is a cross-platform worker harness that executes embedded WebAssembly to perform a “salt mining” computation and returns progress/results to the caller via message passing. In this file, there is no clear evidence of classic malware behaviors such as network exfiltration, credential theft, or filesystem/system sabotage. The most notable supply-chain/security concerns are dynamic code execution patterns (Node Worker with eval:true and browser Blob URL worker scripts) and the potential for CPU-intensive abuse (computational mining-like workload) if invoked in an unauthorized context or with adversarial parameters. Overall: moderate security risk driven by execution surface and availability impact rather than direct data-stealing. Confidence: 0.70 Severity: 0.60 From: ? → npm/viem@2.53.1 → npm/ox@0.14.29 ℹ Read more on: This package | This alert | What is an AI-detected potential code anomaly? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: An AI system found a low-risk anomaly in this package. It may still be fine to use, but you should check that it is safe before proceeding. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/ox@0.14.29. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Block		Potential code anomaly (AI signal): npm ox is 66.0% likely to have a medium risk anomaly Notes: This dependency is a worker-based “salt mining”/proof-of-work compute engine that loads an embedded WebAssembly payload and runs a CPU-intensive loop in Node worker_threads or browser Web Workers, communicating progress and results via postMessage. There is no direct evidence in this fragment of network exfiltration, credential access, persistence, or system modification. The main security concerns are (1) dynamic worker code execution (Node worker eval:true and browser Blob URL execution) and (2) cryptomining-like resource consumption that can be abused for CPU exhaustion. The embedded WASM module itself should be reviewed to confirm it contains only the expected computation and no hidden side effects. Confidence: 0.66 Severity: 0.55 From: ? → npm/viem@2.53.1 → npm/ox@0.14.29 ℹ Read more on: This package | This alert | What is an AI-detected potential code anomaly? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: An AI system found a low-risk anomaly in this package. It may still be fine to use, but you should check that it is safe before proceeding. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/ox@0.14.29. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Block		Potential code anomaly (AI signal): npm tsx is 62.0% likely to have a medium risk anomaly Notes: No direct malware/backdoor behavior is evident in the provided fragment. The primary security concern is design-risk: it dynamically reads local files, transforms them, and executes the result by patching Node’s module resolution and calling Node’s internal compilation hook. If an attacker can influence module resolution inputs (or tsconfig/package.json contents), the impact of that compromise is high. Without additional context (package provenance, transformer implementation, and how inputs can be controlled), confidence is moderate and the security risk is mainly tied to the loader’s powerful execution path rather than clear malicious intent. Confidence: 0.62 Severity: 0.52 From: crypto-payroll/package.json → npm/tsx@4.22.4 ℹ Read more on: This package | This alert | What is an AI-detected potential code anomaly? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: An AI system found a low-risk anomaly in this package. It may still be fine to use, but you should check that it is safe before proceeding. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/tsx@4.22.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Block		Potential code anomaly (AI signal): npm viem is 75.0% likely to have a medium risk anomaly Notes: The code implements a cross-chain deposit flow with proper validations, artifact reads, and on-chain interactions. There is no evidence of hidden backdoors, data exfiltration, or malware. The main security considerations relate to token approval logic and correct configuration of flags to avoid granting excessive allowances. Overall, the module appears legitimate for a bridge deposit flow, with moderate risk primarily around configuration of approvals and correct handling of gas/fees. Confidence: 0.75 Severity: 0.60 From: crypto-payroll/package.json → npm/viem@2.53.1 ℹ Read more on: This package | This alert | What is an AI-detected potential code anomaly? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: An AI system found a low-risk anomaly in this package. It may still be fine to use, but you should check that it is safe before proceeding. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/viem@2.53.1. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Block		Potential code anomaly (AI signal): npm ws is 68.0% likely to have a medium risk anomaly Notes: The analyzed code segment represents a robust, standards-aligned WebSocket receiver. It correctly handles frame parsing, masking, fragmentation, and optional compression via PerMessageDeflate, with appropriate validation and error signaling. There is no evidence of malicious intent or backdoors within this module; the security posture is solid for a protocol parser, with typical risks mitigated by payload size checks and UTF-8 validation. Overall, the code is appropriate for integration in a WebSocket client/server library, with moderate security risk primarily tied to how downstream consumers handle emitted data and potential resource usage under edge cases. Confidence: 0.68 Severity: 0.60 From: ? → npm/viem@2.53.1 → npm/ws@8.20.1 ℹ Read more on: This package | This alert | What is an AI-detected potential code anomaly? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: An AI system found a low-risk anomaly in this package. It may still be fine to use, but you should check that it is safe before proceeding. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/ws@8.20.1. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Block		Potential code anomaly (AI signal): npm ws is 75.0% likely to have a medium risk anomaly Notes: The code implements a standard EventTarget-like mixin for wrapping event listeners and dispatching events to user callbacks. There are no suspicious patterns such as dynamic code execution, hardcoded secrets, or network activity. The risk is contingent on what the consumer does inside their handlers; the snippet itself does not introduce malware or data leakage mechanisms beyond normal event dispatch. Overall security risk is low in isolation. Confidence: 0.75 Severity: 0.50 From: ? → npm/viem@2.53.1 → npm/ws@8.20.1 ℹ Read more on: This package | This alert | What is an AI-detected potential code anomaly? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: An AI system found a low-risk anomaly in this package. It may still be fine to use, but you should check that it is safe before proceeding. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/ws@8.20.1. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[ayushsingh82]

Hey @jonas-dfns 👋

I noticed docs.dfns.co/solutions/automate-payments describes a payroll/bulk disbursement use case but there was no corresponding blueprint in the repo — so I built one.

The crypto-payroll blueprint shows how to run policy-gated USDC payroll using a Dfns treasury wallet and the Policy Engine:

• Small transfers (≤ configurable limit) are auto-approved by a service account checker
• Large transfers stay Pending for a human approver — classic maker/checker workflow
• Uses wallets.transferAsset with externalId for idempotency (prevents double-payment on re-runs)
• Policy filters by walletTags so it only targets the payroll wallet, nothing else

Happy to make any changes to better fit the repo's conventions. Would love your feedback!