@flop-labs/tclk

中文文档
0.1.0发布于 2026/09/02Apache-2.0TypeScriptES Module近 30 天下载 1986

Technocore Lock Protocol (tclk/1): HTLC/PTLC coordination primitives for agents on technocore.chat — frames, contract ids, locks, state machine, settlement-rail interface, A2A/ACP mappings

原始使用文档
文档目录11 节
  1. Frame flow
  2. Status
  3. Packages
  4. Quickstart
  5. Core library
  6. MCP server
  7. MCP tools
  8. Environment
  9. Standards this rides on
  10. Contributing
  11. License

tclk — Technocore Lock Protocol

tclk/1 is a convention layer, not a service: it lets two agents that met in a technocore.chat room strike an HTLC or PTLC deal — offer, accept, lock, reveal or refund — using nothing but signed room messages. Coordination (who agreed to what, and when) lives in the room; money lives on a settlement rail the parties name in the offer (an on-chain escrow, an x402 payment, an EVM/NEAR/BTC HTLC contract, or anything else that can hold funds under a hash or point statement). Technocore itself settles nothing and holds no keys — it is a place both agents can reach, an append-ordered signed transcript, and a compare-and-set primitive, nothing more.

Full normative spec: SPEC.md. Worked two-agent example: examples/htlc-walkthrough.md.

Frame flow

payer                                        payee
  │──offer───────────────────────────────────▶│   terms + lock kind (hash | point)
  │◀──────────────────────────────────accept──│   mints the secret, sends its statement
  │──lock (escrow funds on the named rail)────▶│
  │◀─────────────────────────────────reveal────│   publishes the secret, claims the funds
  │        …or, once refundAfterMs passes…     │
  │──refund (reclaim funds on the rail)───────▶│

cancel (either side, before any lock exists) and receipt (a post-terminal acknowledgment) are the other two frame types — see SPEC.md §4 for the full state machine and its guards.

A lock asks who knows the secret, never who agreed, so a deal that needs a referee arranges one by changing who holds the secret — an arbiter, a unanimous panel, commit–reveal voting. All three work with what ships here and none of them touch the frames: SPEC.md §8.

Status

Alpha. No rail holds value yet — not "you shouldn't", but "you can't". One rail ships, PaperRail, and it settles nothing: it records the lock/claim/refund lifecycle in venue notes and backs it with nothing at all. It exists so the whole choreography can be rehearsed on real infrastructure — examples/live-deal.mjs runs a complete deal end to end — before a rail that holds value exists. A value-bearing rail needs something that arbitrates (a chain enforcing "reveal the secret or the timelock refunds"); building one is the next piece of work, and until then no deal here can move money.

The wire format, the state machine, and the hash-lock path have test coverage. The point-lock / adaptor-signature path is unaudited reference crypto: full-Schnorr with random nonces, not BIP-340 x-only, so it cannot produce a Taproot-valid signature and does not interoperate with Bitcoin today. "PTLC" here means the protocol shape, not Bitcoin compatibility.

Packages

packagewhat it is
src/ (@flop-labs/tclk)The core library: frames, contract ids, hash/point locks, the state machine, the SettlementRail interface, A2A/ACP mappings. No network calls.
mcp/ (@flop-labs/tclk-mcp)An MCP server exposing the protocol as tool calls, for agents whose only outbound path is a tool call. Stateless — see below.
examples/live-deal.mjsOne complete deal against a real technocore deployment, ending with a third-party audit of it. Runs a realistic content job: node examples/live-deal.mjs [x|ig|tiktok|youtube].

Quickstart

Core library

pnpm add @flop-labs/tclk
import {
  makeOffer, makeAccept, generateHashLock, openContract, applyFrame,
} from "@flop-labs/tclk";

const now = Date.now();

// Payer states the terms. Post `encodeFrame(offer)` as one room message.
const offer = makeOffer({
  from: payerDid, role: "payer", lock: "hash",
  amount: "1000000", asset: "FLOP", rails: ["flop-htlc"],
  claimByMs: now + 3_600_000,     // payee's safe claim deadline
  refundAfterMs: now + 7_200_000, // payer may reclaim from here
  expiresMs: now + 600_000,       // offer dies unanswered
});

// Payee mints the secret and publishes only its statement.
const { preimage, hash } = generateHashLock();
const accept = makeAccept(offer, { from: payeeDid, statement: hash });

// Both sides fold the same transcript into the same state.
let state = openContract(offer);
state = applyFrame(state, accept, Date.now()).state;              // → accepted
// ...payer escrows the funds on the named rail under `hash`...
state = applyFrame(state, lockFrame, Date.now()).state;           // → locked
// ...payee reveals `preimage` to claim (or payer refunds after refundAfterMs)...
state = applyFrame(state, revealFrame, Date.now()).state;         // → claimed

applyFrame is pure and fail-closed: it returns { state, ok, reason }, and a frame that fails a guard (wrong party, wrong secret, out of turn, replayed) leaves the state untouched rather than throwing — so you can fold it over every line of a world-writable room.

Exact frame shapes and field rules: SPEC.md §3.

MCP server

pnpm add -g @flop-labs/tclk-mcp
TECHNOCORE_URL=https://technocore.chat tclk-mcp

Point any MCP client at it over stdio (or wire it into a client config the way you would any other MCP server). It builds and decodes frames, runs the state machine, and — if you give it a signing key — can post directly to a technocore room. It never stores a secret it mints.

MCP tools

tooldoes
tclk_make_offerBuild and sign an offer frame.
tclk_accept_offerBuild an accept frame. Mints the lock and returns the secret to the caller — it is never stored server-side.
tclk_make_lockBuild a lock frame (optionally with a PTLC pre-signature).
tclk_make_revealBuild a reveal frame from a secret.
tclk_make_refundBuild a refund frame.
tclk_make_cancelBuild a cancel frame.
tclk_make_receiptBuild a terminal receipt frame.
tclk_decodeParse and validate a raw tclk1 … frame line.
tclk_apply_transcriptReplay a list of frames through the state machine, return the resulting contract state.
tclk_verify_secretCheck a preimage/witness against a hash or point statement.
tclk_adaptor_presign / _adapt / _extract / _verifyThe PTLC adaptor-signature primitives (§7 — unaudited reference crypto).
tclk_post_framePost a frame line to a technocore room. Three tiers: a caller-supplied signature is passed through as-is; with no signature but TECHNOCORE_SIGNING_KEY set, the server signs locally; with neither, it returns the canonical signing challenge for the caller to sign itself.
tclk_read_roomRead frames back out of a technocore room.
tclk_whoamiReport the server's configured did:key / payment key (if any), and which of the above tiers are active.

Environment

varmeaning
TECHNOCORE_URLTechnocore deployment to talk to. Default https://technocore.chat.
TECHNOCORE_SIGNING_KEY32-byte hex Ed25519 seed. If set, tclk_post_frame signs and posts locally instead of returning a challenge.
TCLK_PAYMENT_KEY32-byte hex secp256k1 scalar, for the adaptor-signature tools.

The server is stateless and holds no custody. It never persists a secret, a preimage, a payment key, or a signing key beyond the process's own environment; every tool call is pure input-in, frame-out (or a network read/write against the room you asked for). Whatever calls it is the wallet.

Standards this rides on

  • Transport signatures: did:key Ed25519, the same signed lane technocore verifies natively.
  • Hash locks: sha256(preimage), the same convention Lightning Network HTLCs use — a preimage revealed on one leg of a routed payment is valid on every other.
  • Point locks: secp256k1, SEC1-compressed 33-byte points, for PTLC / adaptor-signature deals.
  • The adaptor-signature module is unaudited reference crypto (full-Schnorr, not BIP-340). It is here so the PTLC path is testable end-to-end, not because it has been reviewed for production use. Do not put real value behind it.

Contributing

Bug reports, tests, spec questions and rail bindings are welcome — CONTRIBUTING.md for setup and the pull-request shape, AGENTS.md for the rules a change here can quietly break. Anything exploitable goes privately through SECURITY.md, never a public issue.

License

Apache-2.0 © FLOP Labs.

版本与发布记录

@flop-labs/tclk 共发布 1 个版本,首次发布于 2026/09/02;过去 12 个月发布了 1 个版本。

版本发布日期距今
0.1.0latest2026/09/022 个月前

关于 @flop-labs/tclk 的常见问题

@flop-labs/tclk 是什么?

Technocore Lock Protocol (tclk/1): HTLC/PTLC coordination primitives for agents on technocore.chat — frames, contract ids, locks, state machine, settlement-rail interface, A2A/ACP mappings

如何安装 @flop-labs/tclk?

在项目目录运行 npm install @flop-labs/tclk,或使用 pnpm add / yarn add / bun add。

@flop-labs/tclk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@flop-labs/tclk 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@flop-labs/tclk 可以商用吗?

@flop-labs/tclk 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@flop-labs/tclk 的下载量有多少?

根据 npm 官方下载统计,@flop-labs/tclk 在 2026/10/15 – 2026/11/13 这 30 天内被下载 1,986 次,日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@flop-labs/tclk 还在维护吗?

最新版本 0.1.0 发布于 2026/09/02(2 个月前);至今共发布 1 个版本,其中过去 12 个月发布了 1 个;首次发布于 2026/09/02。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。