Skip to content
BranchesTags

Repository files navigation

Vert

Vert is a payment-readiness and execution-planning SDK for Fiber wallets and apps.

Its purpose is not only to answer whether a payment can succeed, but to determine how it should succeed.

Vert compiles an execution plan that determines whether a payment is:

  • individually routable across a single path
  • or collectively routable across multiple paths

and then selects the most efficient split strategy when aggregate liquidity is sufficient.

Core idea

Most payment-channel integrations stop too early.

They ask:

  • Can I send this payment?

Vert asks a stronger question:

  • Can the network, as a whole, get this payment through?
  • If no single route can carry it, can several routes carry it together?
  • If yes, what is the best execution strategy?
  • If not, why not, and what should happen next?

That makes Vert a planning layer, not just a checker.

What Vert does

Vert turns channel and routing complexity into reusable infrastructure for wallets and apps.

It provides:

  • a deterministic evaluation engine
  • an execution-planning layer
  • a failure explanation model
  • a React UI layer for readiness, routes, and payment lifecycle feedback
  • an adapter layer for live Fiber-backed or fallback-mock integration paths

The problem Vert solves

In payment-channel networks, a failed payment does not always mean:

  • the recipient is unreachable
  • the total requested amount is impossible

Sometimes it only means:

  • no single route has enough liquidity
  • route fees are too high on one path
  • one hop is weak but another path exists
  • the network needs a better execution plan than “try one route and fail”

That means a payment may be:

  • impossible on one path
  • but fully payable across multiple paths together

Vert is designed to detect and explain that distinction.

Execution planning model

Vert should ultimately answer questions like:

  • Is there a best single route?
  • Is there a usable fallback route?
  • Is the payment fully payable only when split across multiple routes?
  • What is the most efficient route allocation by capacity, fee, and path quality?
  • What should the app try first?
  • What should happen if that route fails?

This means Vert is moving toward a richer model where execution plans are based on:

  • route capacity
  • aggregate liquidity
  • fallback availability
  • split allocations
  • next-step sequencing

In simple terms:

Vert determines whether a payment is individually routable or collectively routable, then chooses the best execution strategy.

SDK usage

Vert currently exposes a higher-level SDK facade through @vert/adapters.

Create a Vert instance

import { Vert } from '@vert/adapters'

const vert = new Vert()

You can also configure sender-node authorities up front:

import { Vert } from '@vert/adapters'

const vert = new Vert([
  { pubkey: '02abc...', key: 'my-authority-key' },
])

Or add them later:

vert.addKey({ pubkey: '02abc...', key: 'my-authority-key' })
vert.addKeys([
  { pubkey: '03def...', key: 'backup-authority-key' },
])

In the current SDK, key is stored as authority metadata. Sender selection uses pubkey; local private-key signing is not implemented yet. For vert.vertify(), senderPubkey is optional when the Vert instance already has configured authorities — if omitted, Vert uses the pubkey from index 0 of the configured authority array.

Run Vertify and get JSON analysis

Basic invoice flow:

const result = await vert.vertify({
  request: {
    amount: '25',
    asset: 'CKB',
    maxFee: '2',
    paymentIntentId: 'demo-payment',
    metadata: { invoice: 'fibt...' },
  },
  senderPubkey: '02sender...',
  invoice: 'fibt...',
})

If you already configured new Vert([{ pubkey, key }]), you can omit senderPubkey and Vert will use the first configured authority:

const vert = new Vert([{ pubkey: '02sender...', key: 'my-authority-key' }])

const result = await vert.vertify({
  request: {
    amount: '25',
    asset: 'CKB',
    maxFee: '2',
    paymentIntentId: 'demo-payment',
    metadata: { invoice: 'fibt...' },
  },
  invoice: 'fibt...',
})

Advanced direct receiver flow:

const result = await vert.vertify({
  request: {
    destination: '03receiver...',
    amount: '25',
    asset: 'CKB',
    maxFee: '2',
    paymentIntentId: 'demo-payment',
  },
  senderPubkey: '02sender...',
  receiverPubkey: '03receiver...',
})

The returned object includes the original evaluation payload plus SDK-friendly helpers such as:

  • evaluation
  • executionPlan
  • primaryAction
  • canExecute
  • efficiency
  • passPossibility
  • selectedSenderPubkey
  • selectedRoute
  • routeDetails

Open the SDK modal in React/browser apps

For browser-hosted modal mounting, use the React bridge package:

import { Vert } from '@vert/adapters'
import { createVertModalPresenter } from '@vert/react'

const vert = new Vert({
  baseUrl: 'http://127.0.0.1:8787',
  modalPresenter: createVertModalPresenter(),
})

await vert.vertifyOnModal({
  request: {
    destination: '03receiver...',
    amount: '25',
    asset: 'CKB',
    maxFee: '2',
  },
  senderPubkey: '02sender...',
  receiverPubkey: '03receiver...',
})

The React presenter mounts VertifyPreviewModal, shows the Vertify analysis, and lets the user click Commence to trigger payment execution and status polling.

Execute a payment

Run payment continuation using the latest input:

const payment = await vert.execute({
  request: {
    destination: '03receiver...',
    amount: '25',
    asset: 'CKB',
    maxFee: '2',
  },
  senderPubkey: '02sender...',
  receiverPubkey: '03receiver...',
})

Require a minimum efficiency score before execution:

const payment = await vert.executeWithEfficiency(80, {
  request: {
    destination: '03receiver...',
    amount: '25',
    asset: 'CKB',
    maxFee: '2',
  },
  senderPubkey: '02sender...',
  receiverPubkey: '03receiver...',
})

Temporarily override which configured authorities are used:

const payment = await vert.executeWithKeys(
  [{ pubkey: '03override...', key: 'override-key' }],
  {
    request: {
      destination: '03receiver...',
      amount: '25',
      asset: 'CKB',
      maxFee: '2',
    },
  },
)

Current execution behavior

Vert now plans route-aware execution metadata and threads that plan through the SDK/API layers.

Today that means:

  • Vert ranks discovered routes and builds a route execution plan
  • execute() returns that plan alongside the payment result
  • the live payment path passes route-plan hints into the Fiber submission layer

The long-term goal is true validated multi-route execution. The current implementation is the first pass of that system, and Fiber routing-control semantics still need deeper live validation.

Repository structure

specs/                 Product source-of-truth docs
  features.md
  architecture.md
  schema.md
  user-flow.md
  demo-story.md

docs/
  implementation-checklist.md

packages/
  core/                Types, rules engine, planning logic, explanations
  adapters/            Mock/live/API-backed integration paths
  ui/                  Reusable React UI components

apps/
  demo/                Internal preview and gallery host
  demo2/               Judge-facing wallet-connected sample dapp
  api/                 Hosted API/runtime support for live demo flow

Package roles

@vert/core

The deterministic engine.

Responsible for:

  • payment request validation
  • readiness evaluation
  • execution-plan generation
  • route/failure reasoning
  • suggested actions
  • shared types/contracts

@vert/adapters

The integration layer.

Responsible for:

  • mock scenarios
  • live Fiber-backed evaluation inputs
  • hosted API adapter paths
  • payment continuation and payment status lookup

@vert/ui

The reusable UI layer.

Responsible for:

  • readiness cards
  • execution plan cards
  • diagnostics and action surfaces
  • Vert SDK preview UI

Host apps

  • apps/demo = preview/gallery host
  • apps/demo2 = judge-facing product-like demo
  • apps/api = hosted runtime for evaluate / continue / payment-status endpoints

Current demo flow

The main public demo direction is:

  1. connect wallet
  2. generate or prepare a payment target
  3. run Vertify
  4. inspect readiness and route/funding information
  5. continue to payment
  6. observe live or fallback-labeled payment results

The current architecture supports:

  • real JoyID wallet connection
  • live-or-fallback evaluation
  • payment continuation
  • payment status polling
  • a growing route-planning topology for local/demo infrastructure

Deployment direction

For a judge-facing live platform, the intended architecture is:

Judge browser
→ demo2 frontend
→ hosted Vert API
→ Fiber node(s)

This keeps:

  • the SDK reusable
  • the browser simple
  • the node/backend infrastructure hidden behind a hosted API

Why this matters

Vert is not just trying to say:

  • yes
  • no

Vert is trying to say:

  • yes, and here is the best route
  • yes, but only if split across multiple routes
  • no, and here is the actual bottleneck
  • here is what to do next

That is a significantly stronger product than a basic route-checking helper.

Current status

The repository already includes:

  • a reusable core engine
  • an execution-plan type and planner foundation
  • mock and live adapter layers
  • shared UI primitives
  • a wallet-connected demo flow
  • a hosted API runtime path
  • local multi-node topology tooling for route experiments

The next major quality bar is strengthening the topology and routing data so Vert can demonstrate richer multi-path execution decisions more convincingly.

Key documents

Summary

Vert is a Fiber-oriented SDK that evaluates not just whether a payment can succeed, but how it should succeed.

Its long-term value is in turning routing complexity, aggregate liquidity, fallback behavior, and execution planning into something reusable for wallets and apps.

About

ckb fiber hackathon project

vert-api.vercel.app

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages