@dexterai/浮点数

Dexter-vault Anchor程序的脱链镜. 字节精密指令构建器,消息编码器,账户解码器,以及密码根基库的签名抽象.

制作应用程序? 到达 @dexterai/x402 换句话说:它给您的代理人规定了几行支出限额,包括买卖双方,并取决于该包的转接。 来 @dexterai/vault 当您组装自己的金库交易时:一个促进器,一个自定义的和解路径,或者第二个打开标签标准执行。 这是引擎 不是前门.

此软件包为何存在

手卷同一协议的三个位置: dexter-api/src/vault/, (中文(简体) ), dexter-facilitator/src/vault/,以及 dexter-vault/tests/其中一个已登记的角色3(ProgramExec 页:1 settle_tab_voucher两个没有。 端到端的制表盘烟雾一直以 Role not found for ID: 3它在2026-06-02上吃了数小时的调试 才发现漂流.

这个包是结构固定. 克能4-作用斯威克提供器,每个指令构建器,每个字节精密的信息编码器,金库账户解码器,预编辅助器各活在一个准确的文件中. 每个消费者(dexter-api, (中文(简体) ), dexter-facilitator, (中文(简体) ), dexter-vault 测试, @dexterai/x402/tab从这里进口。 漂出虫类已去.

如果您要手动滚动一个金库指令构建器,一个预编译信息,一个斯维克角色列表,或者一个金库账户解码器, 从这里导入.

安装

npm install @dexterai/vault

目标 dexter-vault V7程序:70个生成的IDL指令,每个对接方的会话账户PDA,以及一个单调的每个高地 PasskeyAuthorization 重弹后卫. V7前金库在使用V7密码加盖的构建器之前必须完成程序的迁移路径;V5后金库先通过V6迁移.

字节合同

每个字节的链上程序检查都住在这里,每个字节完全一个文件:指令歧视者,188字节的V2会话注册信息,252字节的V3撤销信息,44字节的凭证有效载荷,Canonical 200字节的密码授权信封,以及Vault +会话账户+PasskeyAuthorization账户布局. 这个 dexter-vault 程序是真理的来源;这个包是与之交谈的TypeScript,由快照测试锁定的字节平等(见下文). 一个程序斯威克角色使得非拘禁支出路径成为可能,整个花费路径都通过金库程序,没有主钥匙,没有代管,也没有信任.

提供金库(服务器侧注册)

import {
  buildSetSwigAtomicFromIdentity,
  SWIG_BIRTH_MODE_OWNER_ONLY,
} from '@dexterai/vault/instructions';
import { Transaction } from '@solana/web3.js';

// `clientDataJSON` and `authenticatorData` come from the owner passkey ceremony
// over buildSetSwigOperationMessage(expectedSwigAddress).
const atomicBirth = buildSetSwigAtomicFromIdentity({
  vaultPda,
  feePayer: feePayerKeypair.publicKey,
  dexterMasterPubkey: sessionMaster.publicKey,
  identitySeed: userHandleBytes,           // per-user, stable, ≤32 bytes
  hmacKey: serverSecret.subarray(0, 32),   // 32-byte HMAC key
  clientDataJSON,
  authenticatorData,
  spendLimitAtomic: 0n,
  sessionTtlSeconds: 0n,
  spendMode: SWIG_BIRTH_MODE_OWNER_ONLY,
});

const tx = new Transaction().add(p256VerifyInstruction, atomicBirth);

新鲜的入学是一个 Vault 指令,所以 Swig 创建,程序定义 权威脊椎,角色-0中子和反之 SwigVaultBinding 实施或 滚回一起。 遗产 buildSwigCreationBundle 多指令 API 仅保留为已失效的相容性符号,并总是丢出.

解析分页凭单( 方便端)

import { buildSettleTabVoucherInstruction } from '@dexterai/vault/instructions';
import { buildEd25519VerifyInstruction } from '@dexterai/vault/precompile';
import { buildVoucherMessage } from '@dexterai/vault/messages';
import { readVaultFull } from '@dexterai/vault/reader';

const vaultState = await readVaultFull(connection, vaultPda);
const voucherMessage = buildVoucherMessage(channelId, cumulativeAmount, sequenceNumber);

const tx = new Transaction().add(
  // Ed25519 precompile verifies the session key signed the voucher bytes.
  buildEd25519VerifyInstruction(sessionPubkey, sessionSignature, voucherMessage),
  // settle_tab_voucher consumes the verified voucher; Swig role 3 drives the SPL transfer.
  // allowedCounterparty names the per-counterparty session PDA being settled against.
  buildSettleTabVoucherInstruction({
    vaultPda,
    swigAddress: new PublicKey(vaultState.swigAddress!),
    dexterAuthority: sessionMaster.publicKey,
    allowedCounterparty,
    channelId,
    cumulativeAmount,
    sequenceNumber,
  }),
);

读取金库状态

import { readVaultOnchain, readVaultFull } from '@dexterai/vault/reader';
import { fetchSessionAccount, isSessionLive } from '@dexterai/vault/session';

// Slim shape: { exists, pendingVoucherCount, pendingWithdrawal }.
const slim = await readVaultOnchain(connection, vaultPda);

// Full shape adds: { version, swigAddress, dexterAuthority, liveSessionCount }.
const full = await readVaultFull(connection, vaultPda);

// V7: per-counterparty session state remains in its own PDA, not in the vault.
const s = await fetchSessionAccount(connection, vaultPda, allowedCounterparty);
if (s && isSessionLive(s)) {
  console.log(`tab open: ${s.session.spent} / ${s.session.maxAmount}`);
}

读取结晶索赔(保留级)

券可以是 结晶 改为 a LockedClaim: 不可逆的、买方-不可撤销的对所付金额的保留。 保险库追踪运行中的数量 outstanding_locked_amount,表面显示 readVaultFull 作为 outstandingLockedAmount。这是锁模式标签背面的预留,即运出的标准标签保护,手术时只保留应计金额,而不是冻结整个钱包.

import { readVaultFull, fetchVaultLockedClaims, decodeLockedClaim } from '@dexterai/vault/reader';

// Vault-level total: the sum the withdrawal gate reserves out of the balance.
const { outstandingLockedAmount } = await readVaultFull(connection, vaultPda);

// Per-claim detail. Each claim is a terminal state machine: Pending → Settled
// or Pending → Abandoned. Filter to the live (unsettled) reservations.
const pending = await fetchVaultLockedClaims(connection, vaultPda, { status: 'Pending' });
// reconciliation invariant: sum(pending.amount) === outstandingLockedAmount
for (const c of pending) {
  console.log(`${c.voucherHash}: ${c.amount} held by ${c.currentHolder} (${c.status})`);
}

// decodeLockedClaim(address, accountData) decodes a single account you already
// hold — the same moving-cursor decoder fetchVaultLockedClaims uses internally.

设定反事实 Swig 地址

import { deriveCounterfactualAddresses } from '@dexterai/vault/counterfactual';

// Returns both the state PDA (program-owned) and the wallet-address PDA
// (system-owned, the asset holder). Useful for showing a deposit address
// before the Swig is on chain.
const { swigStateAddress, swigWalletAddress } = await deriveCounterfactualAddresses({
  identitySeed: userHandleBytes,
  hmacKey: serverSecret.subarray(0, 32),
});

会话: 每对交易方一个标签

每届会议都以会议账户PDA为单位, [b"session", vault, allowed_counterparty]:每(倒数,对数)一个分页,每个金库有许多对数. 对已经开庭的对手进行登记 替换到原地 (同样的种子)和 重置仪表 (单位:千美元)spent, (中文(简体) ), currentOutstanding);任何在上方建有UX的建筑,在被替换前都应该警告.

注册需要兄弟会的合同:程序检查交易名称是金库中每个其它版本的QQ0会话,这样它就可以扫去已过期的会话并证明新封顶不会过度承诺金库的余额.

import { buildRegisterSessionKeyInstruction, buildRevokeSessionKeyInstruction } from '@dexterai/vault/instructions';
import { fetchVaultSessionAccounts, sessionPdasOf, waitForSession, resolveVaultUsdcAta } from '@dexterai/vault/session';

// fetch siblings FRESH immediately before building (the gate sweeps expired
// siblings; a stale list fails the on-chain completeness check)
const siblings = sessionPdasOf(await fetchVaultSessionAccounts(connection, vaultPda));
// resolve the vault's USDC ATA — returns its address if it exists, or `null`
// for a credit-only vault that never received a deposit (see note below)
const vaultUsdcAta = await resolveVaultUsdcAta(connection, swigAddress);
const ix = buildRegisterSessionKeyInstruction({ ...args, payer, vaultUsdcAta, siblingSessionPdas: siblings });
// ... send [secp256r1Precompile, ix] ...
await waitForSession(connection, vaultPda, allowedCounterparty, { expectedSessionPubkey });

构建者处理兄弟会列表中 fidd 部分(不包括目标,去除,按生字节严格地递增,标记全部可写);您唯一的工作就是取出新鲜的. waitForSession 是认识到内容的确认-可见性:它等待 新设 session_pubkey,因为旧的注册 也通过存在 和版本检查 在读取你的写后滞后.

vaultUsdcAta 是可选的. 注册门计算后置为 own_USDC + available_standby_credit自筹资金的金库通过USDC ATA,所以其余额计算在内; a 只有信用的保险库从未收到保证金,所以没有ATA - 通过 vaultUsdcAta: null 而自定义的USDC则被计算为0(仅备份为备用行). resolveVaultUsdcAta 为您做出这个决定( 贬损和检验): 使用它 PublicKey | null 直接结果。 选择一个只存在的ATA 小写 支持,所以它是安全的; 一个自筹资金的金库,想要它的余额计数,必须通过它.

信用原始人

金库程序支持花费的标签 过去 使用者的平衡,在金融家备用资本的支持下,结构上使买方无法纠缠金融家,而金融家无法扣押超过约定的束缚。 这条道路的建造者住在这里:

import {
  drawCredit,
  originateLineCredit,
  repayCredit,
  seizeCollateral,
} from '@dexterai/vault/tab';

信用不是单独的产品。 它是一个可以度过平衡的标签, 所以它构成相同的原始: open_standby 举起后盾, draw_credit 编号 : repay_credit 移动所借余额, seize_collateral 运行默认路径,并且锁定要求结晶分层(@dexterai/vault/instructions加上保理/即时付款(@dexterai/vault/factoring)上起而为上. 演示索拉纳主网:提款,还款,违约并扣. 这是包件中最新的表面;按此处理.

originateLineCredit 那是一条有证据的地道。 它会产生 版本证据和术语承诺,然后返回(但不发送) 1 原子 record_line_origination -> draw_credit -> Swig SignV2 信封上写着 这个 (一) 现行主要节点设施每笔提取收据是不可改变的证据; 它不是可转让债权,也不是第二个余额分类账。 读出来 readLineOrigination 或解码紧凑事件和调用 fetchLineOriginationForEvent 要求的全额收据.

新的先取图应该执行 LineTermsV2V2约束了商定的到期日, 要求的回收窗口、费率、本金、资产和政策/证据散列, 但故意不包含 defaultAt 或者说 curePeriodSeconds: 这些 数值从实际起落时间最后确定。 现有V1出口仍然存在 不变.

import { originateLineCredit } from '@dexterai/vault/tab';
import { LINE_TERMS_V2_SCHEDULE_POLICY } from '@dexterai/vault/credit';

const result = await originateLineCredit({
  ...draw,
  terms: {
    schedulePolicy: LINE_TERMS_V2_SCHEDULE_POLICY,
    assetDecimals: 6,
    dueAt,
    legalAgreementHash,
    underwritingHash,
    policyHash,
    pricingHash,
  },
});
// originateLineCredit binds the exact live mint, principal, node rate, and
// requested recovery window before hashing the V2 envelope.

支出赠款@dexterai/vault/grant(中文(简体) )

一项应用提议了一个有界限的开销;用户的密码认可了准确的188字节注册范围. 两分之一:

// App side: produce a self-contained request blob (no keys, signs nothing):
import { requestSpendGrant, encodeSpendGrantRequest } from '@dexterai/vault/grant';

const blob = requestSpendGrant({
  app: { name: 'Acme Research', domain: 'acme.example' },
  counterparty: SELLER_ADDRESS,        // the on-chain binding (session PDA seed)
  capAtomic: '5000000',                // $5; the user may only SHORTEN
  expiresAtUnix: Math.floor(Date.now() / 1000) + 7 * 86400,
  sessionPubkey: AGENT_SESSION_PUBKEY, // optional; see custody note
});
const consentUrl = `https://dexter.cash/grant?req=${encodeSpendGrantRequest(blob)}`;

// Consent side: parse untrusted input, apply shorten-only edits, run the
// passkey ceremony over the exact bytes, end at the SIGNED GRANT:
import { parseSpendGrantRequest, approveSpendGrant } from '@dexterai/vault/grant';

const request = parseSpendGrantRequest(rawBlob);
const approved = await approveSpendGrant({
  request,
  vaultPda,                            // the USER's vault, never from the blob
  edits: { capAtomic: '2000000' },     // shorten-only; raises throw
  sign: (message) => myWebAuthnPipeline(message),
});

可选 seller 字段载 { calledUrl, offer?: { format: 'jws', signature }, expectedHost? }。 。 。 . calledUrl 必须是没有证书或明确端口的HTTPS,最多2048个字符. 紧凑的JWS有3个基质64url片段,最多有4096个字符; expectedHost 是一个小写 ASCII 主机名,最多253个字符. 两种请求的切入点都拒绝销售者输入错误的输入 bad_seller 并放下未知的密钥. 请求blob没有签名。 里面的引文带有商店的签名; 打电话者核实该签名和卖方分别具有约束力.

如果小块携带 sessionPubkey,请求的应用的代理 持有会话秘密 并可以驱动花费到同意的上限 自己的节奏。 放弃它 approveSpendGrant 生成 keypair 调用方, 因此请求者永远不会看到这个秘密 。 无论是哪种方式,接触都以上限×对应方×过期为界限,在结算时强制实施.

批准和拒绝证据@dexterai/vault/mandate(中文(简体) )

verifyMandateApproval 返回时 ceremonyNonce 小写十六进制 完成200字节批准 核实。 它回来了 null 一个32字节的遗产 质疑或无效或无授权.

verifyCaseFailedTransaction 接受三个 CaseRefusalAttempt 变体: settle_voucher, (中文(简体) ), settle_tab_voucher 财务报告和审定财务报表 settle_locked_voucher。现有的 变量保留其对应方字段。 锁定付款用途 :

const attempt = {
  instruction: 'settle_locked_voucher' as const,
  vault, claim, destinationOwner,
  amount: 1_000_000n, // Expected amount from the claim evidence.
  holder,           // Optional expected holder signer.
  authority,        // Optional expected Dexter authority signer.
};
verifyCaseFailedTransaction(transaction, signature, {
  program: DEXTER_VAULT_PROGRAM_ID.toBase58(), code: 6070, attempt,
});

锁定的支付支票解码了下面的 Swig SignV2 传输检查和 要求罐头来源 USDC ATA,USDC 薄荷,预期目的地 ATA, 索赔额和6个小数。 绑定账户必须签有静态密钥. 打电话者提供预期索赔额并证明索赔情况 和金库的Swig身份 从单独的证据。 交易签名覆盖 ; RPC 节点报告失败代码和日志.

字节均等担保

tests/byte-parity.test.ts, (中文(简体) ), tests/precompile.test.ts, (中文(简体) ), tests/swigBundle.test.ts, (中文(简体) ), tests/counterfactual.test.ts,以及 tests/reader.test.ts 一起快照 :

• 每一个手执的指令 歧视者在 DISCRIMINATORS,来源于 sha256("global:<name>") 并核对生成的IDL.
• 核心会话/指针消息布局,字节逐字节:188-字节V2会话登记,252-字节V3精确状态撤销,44-字节凭证有效载荷,外加操作专用授权信息套件.
• 两者 预编译构建器,secp256r1(SIMD-0075)和Ed25519,包括14字节相冲平表.
• 这个 金库账户解码器 用于 V7 版式 162字节会话解码器,而每伏特重放后卫解码器.
• 这个 原子生子合同: 确定身份, 犬形反向绑定, 仅所有者模式编码, 准确的211字节同意, 语义程序Exec 标记目录, 和失败关闭的遗产注册 .
• 这个 反事实衍生 为有名的种子.

如果未来的改变以一个字节漂移其中任何一个,快照测试失败. 链上 dexter-vault 程序是终极裁判;这些测试在它出船前捕捉到漂移.

npm test

审计前,我们这样说. 这个 dexter-vault 此软件包镜像尚未接受外部审计; 资金正在流出。 报告及调查结果公布于 程序重传负责任的披露: 分支@ dexter. cash。 。 。 .

建筑

                ┌─────────────────────────────────┐
                │  dexter-vault (Anchor program)  │  ← source of truth
                │  V7: 70 IDL instructions + guard│
                └────────────────┬────────────────┘
                                 │ defines bytes
                                 ▼
                ┌─────────────────────────────────┐
                │  @dexterai/vault (this package) │  ← off-chain mirror
                │  byte-parity locked by tests    │
                └────────┬────┬──────────┬────────┘
                         │    │          │
       ┌─────────────────┘    │          └──────────────────┐
       ▼                      ▼                             ▼
┌──────────────┐     ┌──────────────────┐         ┌───────────────────┐
│ dexter-api   │     │ dexter-facilitator│         │ dexter-vault tests│
│ (DB + glue)  │     │ (tab settle path) │         │ (anchor smokes)   │
└──────────────┘     └──────────────────┘         └───────────────────┘

        ▲                                                     ▲
        │                                                     │
        └────────── @dexterai/x402/tab imports message ───────┘
                    helpers from @dexterai/vault; keeps
                    the HTTP wrapping

子路径导出

每个子路径都是树能震动的出入口. 随便你.

遗产直接 @dexterai/vault/connect 仪式随V7号机退役 授权协议。 它不能满足 Canonial 重放守护信封 从第三方WebAuthn源。 网站集成必须使用 @dexterai/connect,其托管的 Dexter 同意窗口将签名源 而不限制离开开放网站.

现有的 V7 保险库必须运行无权限的, 等效的 buildInitializePasskeyAuthorizationInstruction 在他们第一次守卫之前 操作。 仅凭金库-版本迁移并不能创建这个再玩守护 PDA.

一次性直播会话旋转(未公布的0.42.1修复)

V7 拒绝直接覆盖未过期会话账户 。 以前的保险箱 旋转形状需要在一次交易中有两个带警戒的WebAuthn断言: revoke_session_key(N) 接下来是 register_session_key(N+1)与犬科动物 200字节的授权质疑, 准确交易是 1, 621字节 即使每个符合资格的账户通过压缩后,零兄弟会 地址查询表; 索拉纳的包盖为 1,232 字节.

replace_session_key_v1 用一种说法修复运输死路一条 内容 固定的348字节操作 绑定了现在的护卫... ...非.., 所有10个已退休的登记地/米,以及所有6个替换地. 该指令保留了仪表,要求更换限制以覆盖 ,并且只更改经密码支持的会话范围。 没有退休的田地 在指令数据中重复:程序从活的目标重建它们, 因此,任何后 仪式仪表漂移 使操作的散乱.

composeRevokeThenRegister 现在发出 [secp(replace), replace_session_key_v1] 用于活靶并保留 [secp(register), register_session_key] 对于缺席、清理或过期的目标。 之前的每一个 替换尝试 它重新配置目标, 重放后卫, 和完整的兄弟 设置; 重试前未关闭目标公尺或守卫外漂移。 堕落者 revokeCeremony 输入被忽略,从不输入交易.

现实的浏览器有效载荷需要完整的地址查询表. 绑起 0/1/4个兄弟会的电线尺寸分别为991/993/999字节 与完全的低价竞标。 同样的遗产形状是1234/1267/1366字节和v0 没有ALT是1236/1269/1368字节,所以没有压缩的形态都不是保险箱 掉回索拉纳的1 232字节盖下 这些是PREP文物测量; 它们不是软件包出版或程序部署的证据.

签名抽象

interface Ed25519Signer {
  readonly publicKey: Uint8Array;                              // 32 bytes
  sign(message: Uint8Array): Promise<Uint8Array>;              // 64-byte signature
}

interface PasskeySigner {
  readonly credentialId: Uint8Array;
  sign(challenge: Uint8Array): Promise<{
    signature: Uint8Array;
    clientDataJSON: Uint8Array;
    authenticatorData: Uint8Array;
  }>;
}

NodeEd25519Signer 船舶在 @dexterai/vault/signers/node。浏览器的密码是 WebAuthnAssertion 时间 @dexterai/vault/signers/browser纯浏览器P-256仪式 navigator.credentials.get() 并返回三个已准备好的缓冲器(64字节紧凑的低S签名,原始) clientDataJSON粗线 authenticatorData),无 fetch 打电话 执行 PasskeySigner;消费者用自己的服务器政策适配器来作曲.

版本

当前 SDK 瞄准 dexter-vault V7程序(70个生成的IDL指令;每对面会话账户 PDA;每个故障的单调 PasskeyAuthorization 重放后卫; 角色 3 ProgramExec 页:1 settle_tab_voucher 每个新斯威克。 V7前金库在使用V7密码加盖的构建器之前必须完成程序的迁移路径;V5后金库先通过V6迁移. 结晶-要求读取器(outstandingLockedAmount, (中文(简体) ), fetchVaultLockedClaims, (中文(简体) ), decodeLockedClaim)和 settle_locked_voucher 斯维克标记于0.10. 未来的程序版本会撞出SDK主干线或者在ChangGELOG中记录三角洲. 字节对等测试是结构锁:任何布局变化都需要明确快照更新.

出版

前当地人 release* npm 脚本已被删除 。 使用已验证的 存档和维护者批准程序如下供出版.

释放使用情况 发布默认 SDK。该建筑 任务运行 npm run verify:release:package测试所承诺的来源, 包装,并检查新的无害环境管理、通用JS和TypeScript消费者。 它的焦油弹 财务报告和审定财务报表 release-proof.json 保存为 GitHub 动作器件。 第二个工作 上传同样的焦油球到 npm 组装,供维护者用 2FA 批准 .

配置 vault-npm-production 有部署规则的 GitHub 环境 允许释放标记。 在 npm 设置中 @dexterai/vault,添加一个 GitHub Actions 信任的出版社,其中包含这些精确的值:

这些设置需要在 GitHub 和 npm 中配置 。 将工作流程添加到 该寄存器不配置任一服务。 工作流程使用节点 24和npm 11.19.1, 满足 npm 信任的出版。 。 。 . Vault 的源寄存器是私有的, 因此发布的任务禁用出处 根据 npm 当前对私人寄存器的支持需要生成.

要发布稳定的版本, 请将版本和锁文件更改合并到 main, (中文(简体) ), 然后推动标签匹配 package.json,例如 v0.43.4。工作流程检查 标记为属于 main。拉动请求运行软件包验证 无需申请出版许可.

中转任务检查所保存的散列并使用 OIDC. (英语). 它的运行摘要显示阶段 ID 和一个 npm stage approve 命令; 页:1 vault-stage 文物中包含npm响应和包检查和. 审查这个包,然后在npm与2FA批准. 在批准之前 尚未释放,不能释放 从公共登记处安装。 批准发生在npm,因为 这个私人寄存器的 GitHub 计划不支持所需的审查者.

批准后, 重新运行工作流程的运行任务, 以验证 npm 的软件包 联合国 latest 标签。 已出版的版本 仅在其字节与被测试的软件包相匹配时才被接受。 如果进行未遂 中断, 在重运行前检查 npm 的 Staged 软件包标签: 待定 级已经保留了软件包版本.

对于手动运行,请在 GitHub 动作中选择发布标记或使用 :

gh workflow run publish-vault.yml --repo Dexter-DAO/dexter-vault-sdk --ref v0.43.4

许可证

麻省理工学院 2026 Dexter.

部分 Dexter-DAO 数据交换系统 开源家族.

在没有 GitHub 跑道时进行本地中转

使用节点22.14或更新和npm 11.19.1. 登录方式 npm login --auth-type=web, (中文(简体) ), 然后运行 npm run verify:release:package 从一个干净的,坚定的检查. 选定的承诺必须合并为 main 发表前.

将精确的归档记录在验证器上 release-proof.json数字 :

npm stage publish /path/from/release-proof/packed/dexterai-vault-VERSION.tgz \
  --ignore-scripts --access public --tag latest --provenance=false --json
npm stage view STAGE_ID --json

将所上演的完整和shasum与包的证明相提并论. 等会儿 npm stage view 报告 staged 运行前 npm stage approve STAGE_ID· ; 在 npm 的自动审查仍在运行时, 避免请求批准 . 完成浏览器认证, 然后验证 npm 的版本, 完整性 财务报告和审定财务报表 latest 标记匹配已测试的归档 。 保留证明和舞台收据.