การรวมระบบการชำระเงิน LangGraph.
ไม่จำเป็นต้องมีแพ็คเกจ LangGraph โหนดธรรมดาเรียกใช้ลูกค้า blockchain0x จริง, interrupt() จะระงับจนกว่าการ webhook การชำระเงินจะมาถึง และกราฟจะดำเนินการต่อ - ทนทานต่อการทำงาน
ไม่มีแพ็กเกจเฉพาะของ LangGraph และคุณก็ไม่จำเป็นต้องมี node แบบธรรมดาใน ของคุณเรียกใช้ client ของจริง, จะหยุด graph ไว้จนกว่า payment webhook จะมาถึง และ handler จะกลับมาดำเนินต่อด้วย + ของ LangGraph เอง การชำระเงินจะ settle บน Base
การดำเนินการที่ทนทานทำให้รูปแบบการกลับมาหลังการชำระเงินเป็นธรรมชาติ.
ส่วนที่ยากของการชำระเงินที่ขับเคลื่อนโดยเอเจนต์คือช่องว่างแบบอะซิงโครนัส: คุณขอการชำระเงิน ผู้ซื้อชำระเงินในอีกไม่กี่นาที (หรือไม่เคย) และคุณต้องดำเนินการต่อโดยไม่สูญเสียสถานะที่คุณอยู่ ส่วนใหญ่ของกรอบงานเอเจนต์อิงจากคิวงาน + การจัดเก็บสถานะด้วยมือเพื่อเชื่อมช่องว่างนี้ LangGraph มีพื้นฐานที่สร้างขึ้นแล้ว: interrupt() ระงับกราฟที่โหนดและ checkpointer จะเก็บสถานะไปยังดิสก์ การดำเนินการต่อคือการเรียกหนึ่งครั้ง.
สูตรนี้อาศัยแนวทางนี้โดยไม่ต้องใช้กลไกพิเศษอะไรเพิ่ม node สำหรับจ่ายเงินแบบธรรมดาจะเรียก blockchain0x.payments.create. node await_settlement จะเรียก interrupt() เพื่อหยุดชั่วคราว และ checkpointer จะเก็บสถานะไว้ handler ของ webhook จะตรวจสอบลายเซ็น ตั้งค่า settled บน thread ที่ตรงกันด้วย graph.updateState แล้วเรียก graph.invoke เพื่อทำงานต่อจากจุดที่หยุดไว้ graph จะกลับมาทำงานต่อจากเดิมพอดี รวมถึง context ของ LLM จาก node ก่อนหน้า - ทั้งหมดใช้ API ของ LangGraph เอง
ติดตั้ง LangGraph และ SDK หลัก โดยไม่มีแพ็คเกจเพิ่มเติม
Node 18+ และ @langchain/langgraph 0.2+ บวกกับลูกค้า @blockchain0x/node จริง ไม่มีตัวแปลง LangGraph ที่ต้องเพิ่มในทั้งสองภาษา - ผู้ใช้ Python LangGraph ติดตั้ง langgraph และลูกค้า blockchain0x Python และเขียนสูตรเดียวกัน โดยมี interrupt() และ Command(resume=...) บนด้าน Python
npm install @langchain/langgraph @blockchain0x/node
export BLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet export BLOCKCHAIN0X_WEBHOOK_SECRET=... # for the webhook handler
BLOCKCHAIN0X_API_KEY คือคีย์ sk_test_ สำหรับ testnet หรือ sk_live_ สำหรับ mainnet จากแดชบอร์ดของคุณ โดย client จะอ่านค่าจาก environment ส่วน BLOCKCHAIN0X_WEBHOOK_SECRET (ซึ่งจะแสดงให้เห็นเพียงครั้งเดียวเมื่อคุณสร้างหรือหมุนเวียน webhook) จำเป็นสำหรับ process ที่จัดการ webhooks หาก graph ของคุณรันใน process หนึ่ง และ handler อยู่อีก process หนึ่ง ทั้งสองฝั่งต้องใช้ checkpointer เดียวกัน (เช่น shared Postgres) เพื่อให้ handler หา suspended thread เจอ
กราฟสามโหนด: ชำระเงิน, ระงับ, ส่งมอบ.
ด้านล่างคือ workflow ของ LangGraph แบบครบถ้วน พร้อม typed State, pay node ที่เรียก blockchain0x.payments.create ของจริง, await_settlement node แบบ interrupt-based และ deliver node ที่รันงานที่ขึ้นต่อกันเมื่อ chain ยืนยันว่า payment เคลื่อนย้ายแล้ว
import { StateGraph, START, END, MemorySaver, interrupt, Annotation } from "@langchain/langgraph"; import { createClient } from "@blockchain0x/node"; const blockchain0x = createClient({ apiKey: process.env.BLOCKCHAIN0X_API_KEY! }); const State = Annotation.Root({ agentId: Annotation<string>(), to: Annotation<string>(), amountWei: Annotation<string>(), // USDC base units: "10000" = 0.01 USDC settled: Annotation<boolean>(), }); // A plain node that calls the real SDK. No dedicated package needed. async function pay(state: typeof State.State) { await blockchain0x.payments.create({ agentId: state.agentId, to: state.to, amountWei: state.amountWei, }); return {}; } // Suspend the graph until the payment.sent webhook resumes this thread. function awaitSettlement() { interrupt("awaiting on-chain settlement"); return {}; } async function deliver() { // Funds have moved - do the work that depended on the payment. return {}; } const graph = new StateGraph(State) .addNode("pay", pay) .addNode("await_settlement", awaitSettlement) .addNode("deliver", deliver) .addEdge(START, "pay") .addEdge("pay", "await_settlement") .addConditionalEdges("await_settlement", (s) => (s.settled ? "deliver" : END)) .addEdge("deliver", END) .compile({ checkpointer: new MemorySaver() });
When the graph runs, the pay node submits the USDC transfer through the SDK. The await_settlement node calls interrupt(), which suspends the graph and persists state via the checkpointer. The conditional edge waits to be told settled=true before routing to deliver; if settlement never lands, a timeout sweep routes it to END. amountWei is base units, so 0.01 USDC is "10000".
ตรวจสอบ webhook จากนั้นดำเนินการต่อในเธรด
ตัวจัดการตรวจสอบลายเซ็นด้วย webhooks.verify จาก Node SDK มองหาเธรด LangGraph ที่ถูกระงับจากการแมพของคุณ ตั้งค่าการตั้งถิ่นฐานด้วย graph.updateState และเรียก graph.invoke(null, config) เพื่อดำเนินการต่อจากการหยุดชะงัก ไม่มีผู้ช่วยพิเศษ - นั่นคือ API ของ LangGraph เอง.
import express from "express"; import { webhooks } from "@blockchain0x/node"; import { graph } from "./graph"; const app = express(); // Capture the RAW body. The HMAC is over the exact bytes on the wire. app.use(express.raw({ type: "application/json" })); app.post("/webhooks/payment", async (req, res) => { const result = webhooks.verify({ headers: req.headers, rawBody: req.body, // Buffer, raw bytes secret: process.env.BLOCKCHAIN0X_WEBHOOK_SECRET!, }); if (!result.ok) return res.status(400).json({ code: result.code }); if (result.eventType === "payment.sent") { // You map the event to the suspended graph thread (your own store). const config = { configurable: { thread_id: threadFor(result.eventId) } }; await graph.updateState(config, { settled: true }); await graph.invoke(null, config); // resume from the interrupt } res.status(200).send("ok"); });
webhooks.verify ทำ HMAC-SHA256 ในเวลาเดียวกันกับเนื้อหาดิบและส่งคืนการรวมที่แยกประเภท - แยกตาม result.ok, ไม่มี try/catch. แมพ result.eventId ไปยังเธรดที่คุณระงับ จากนั้น graph.updateState + graph.invoke(null, config) จะกลับมาจากจุดตรวจสอบที่เก็บถาวรและกราฟจะทำการส่ง. เหตุการณ์ที่ส่งคือ payment.received, payment.sent, wallet.deployed, และ webhook.test.
ไคลเอนต์ที่คุณกำลังห่อหุ้มอยู่เปิดอยู่ อ่านมัน.
ไม่มี starter package ของ LangGraph ให้ clone - สูตรด้านบนคือการเชื่อมต่อจริง SDK ของ blockchain0x เป็น open source บน GitHub; สูตรนี้ห่อหุ้ม Python SDK (blockchain0x-python) โดยมี surface ของเมธอดทั้งหมดอยู่ใน docs อ่านไว้เป็นตัวอย่างอ้างอิงสำหรับ body ของ node และการตรวจสอบ webhook
github.com/tosh-labs/blockchain0x-pythonsurface ของเมธอดใน SDK และรูปแบบลายเซ็นของ webhook ถูกอธิบายไว้ที่ the docs. เริ่มด้วยคีย์ sk_test_ บน Base Sepolia ก่อน แล้วค่อยสลับเป็น sk_live_ เมื่อ graph กลับมาทำงานต่อได้ตามที่คุณคาดไว้
ห้าหมายที่เฉพาะเจาะจงเกี่ยวกับ LangGraph ที่ควรหลีกเลี่ยง
โมเดลการดำเนินการที่ทนทานของ LangGraph มีพลังแต่มีข้อควรระวังเกี่ยวกับจุดตรวจ, การหยุดชะงัก, และการอัปเดตสถานะ.
ไม่มีแพ็คเกจ LangGraph - โหนดธรรมดาเรียก SDK
Blockchain0x ส่งอะแดปเตอร์สำหรับ LangChain และ CrewAI พร้อมกับเซิร์ฟเวอร์ MCP; ไม่มีแพ็คเกจ LangGraph ที่เฉพาะเจาะจงใน npm หรือ pip สูตรข้างต้นคือเส้นทาง: โหนดกราฟธรรมดาเรียกใช้ไคลเอนต์ @blockchain0x/node ที่แท้จริง และคุณกลับมาที่ graph.updateState + graph.invoke ของ LangGraph ไม่มีคลาส payment-node พิเศษและไม่มีตัวช่วยในการกลับมาเพื่อให้ import - สิ่งเหล่านั้นไม่เคยมีอยู่.
ขาด checkpointer
interrupt() ของ LangGraph จะทำงานได้ก็ต่อเมื่อกราฟมี checkpointer หากไม่มีมัน สถานะจะหายไปเมื่อกระบวนการของคุณสิ้นสุดลงและตัวจัดการ webhook จะไม่มีเธรดในการดำเนินการต่อ ใช้ MemorySaver สำหรับการพัฒนาและ SqliteSaver หรือ PostgresSaver ในการผลิต หากกราฟและตัวจัดการ webhook ของคุณทำงานในกระบวนการที่แตกต่างกัน พวกเขาต้องแชร์ checkpointer เดียวกัน (เช่น Postgres หนึ่งตัว) เพื่อให้ตัวจัดการสามารถค้นหาเธรดที่ถูกระงับได้
การแมพ webhook ไปยังเธรดที่ถูกต้องเป็นงานของคุณ
Webhook บอกคุณว่าการชำระเงินตั้งถิ่นฐาน; มันไม่รู้จัก thread_id ของ LangGraph ของคุณ เก็บการแมพของคุณเอง - เมื่อคุณเริ่มกราฟ ให้เก็บ thread_id ที่มีคีย์โดยตัวแทน ผู้รับ หรือคีย์ idempotency ที่คุณตั้งค่า จากนั้นมองหามันในตัวจัดการ การเรียก threadFor() ข้างต้นคือการค้นหานั้น ทำผิดและ graph.invoke จะกลับมาที่เธรดที่ผิดหรือไม่มีเลย.
จัดการเส้นทางที่ไม่มีการชำระเงิน, หรือระงับตลอดไป
ขอบเงื่อนไขจาก await_settlement จะส่งมอบเฉพาะเมื่อการตั้งถิ่นฐานเป็นจริง หากการชำระเงินไม่ถึงที่หมาย เธรดจะถูกระงับไม่มีกำหนดเวลา เพิ่มเวลาออก: การทำความสะอาดที่กำหนดเวลาเพื่อเริ่มต้นเธรดที่ล้าสมัยด้วย settled=false ดังนั้นขอบจะส่งไปที่ END หรือการตรวจสอบ payment.sent-versus-deadline เธรดที่ถูกระงับไม่มีค่าใช้จ่าย แต่ก็จะไม่เสร็จสิ้นด้วยตัวเอง.
จำนวนเงินเป็นหน่วยพื้นฐานของ USDC, ในรูปแบบสตริง
payments.create takes amountWei: a string of USDC base units (6 decimals), so 0.01 USDC is "10000" and 5 USDC is "5000000". It also does not retry by default and can answer 503 until the chain adapter is wired for your network. Handle that in the pay node - route to END or a retry node on error rather than letting the graph wedge.