use block.timestamp deadlines + trim app-session

[hhl42]

Breaking changes:

• block.timestamp-based deadlines: switch every off-chain deadline / challenge window / timeout from block.number to unix-second comparison against block.timestamp. Regenerate chain bindings.

• Simplify app-session/channel to the stateless IBooleanCond surface: delete the dispute / state-exchange / oracle / deploy-watch / callback machinery that no consumer exercises; redesign AppClient.GetBooleanOutcome to call IBooleanCond directly with per-AppChannel mutex on deploy-on-query.

[Copilot]

Pull request overview

This PR migrates deadline semantics across the codebase from block heights to unix-second timestamps and trims the legacy app-session surface down to stateless IBooleanCond registration/query flows. It touches protocol logic, storage, WebAPI/SDK layers, tooling, tests, generated bindings, and documentation to align the off-chain stack with block.timestamp-based contracts.

Changes:

• Switches many off-chain deadline/timeout comparisons and payloads from block numbers to unix-second timestamps.
• Removes legacy app-session/state-exchange/oracle/dispute APIs and bindings, keeping only virtual-contract registration plus IBooleanCond outcome queries.
• Regenerates or updates bindings/docs/tests/configs to reflect the new timestamp semantics and reduced app surface.

Findings

1. Critical – existing SQL databases will break after upgrade because the desttokens column was renamed without any migration path.
   The schema now expects openchants, and DAL queries/inserts were updated to that name, but schema initialization only runs for brand-new SQLite databases and there are no ALTER TABLE migrations for existing installs. Upgraded nodes with an existing desttokens(openchanblknum) table will start failing as soon as these code paths run.

2. Critical – replayed RouterUpdated events are now stamped with time.Now() instead of the on-chain registration timestamp, so stale routers can be revived as “fresh” after restart.
   On startup the monitor backtracks old events; with the new code, an event from days ago is recorded as if it happened “now”. That means routers whose on-chain registration is already near expiry—or already expired but still within the backtrack window—will be kept alive for another full expiry interval after each restart.

3. Critical – a router that has been deregistered on-chain will be re-registered automatically by the periodic refresh loop.
   checkAndRefreshIfNeeded now does if nowTs-registeredAt > refreshIntervalSec, and registeredAt == 0 means “not registered”. Since nowTs-0 is always large, the next periodic check will call refreshRouterRegistry() and undo an intentional deregistration.

4. Moderate – eventBacktrackBlocks is no longer tied to the 7-day router expiry window, so startup replay can miss still-live routers on faster chains.
   Previously the backtrack distance matched the expiry interval. After the switch to second-based expiry, replay still uses a fixed 50,000 blocks; on a 2s block chain that covers only ~28 hours, far less than the 7-day liveness window, so the routing table can come up missing valid routers until they emit a new event.

5. Moderate – the OSP WebAPI default payment timeout was left at 50, but it is now interpreted as seconds instead of blocks.
   SendToken still routes through ospWebapiDefaultPayTimeout = 50, and the new deadline calculation adds that value to time.Now().Unix(). That silently shrinks the default window from roughly “50 blocks” to “50 seconds”, which is a large behavioral regression for existing WebAPI clients.

6. Moderate – on-chain resolution of virtual-contract payments now has a hidden prerequisite that the caller must query the app first to force deployment.
   The new SDK comments explicitly document that ResolvePayOnChain / ResolveIncomingPaymentOnChain can fail for VIRTUAL_CONTRACT conditions unless OnChainGetBooleanOutcome was called earlier to trigger deploy-on-query. That turns what used to be a self-contained resolve API into one with an undocumented-at-call-site stateful prerequisite, which is a functional regression for consumers that only resolve on-chain.

7. Nit – tools/scripts/README.md still references regenerate-legacy-app-bindings.sh even though this PR deletes that script.
   The updated README says the legacy script “does the same thing for its lone survivor,” but the file no longer exists, so the regeneration instructions are now misleading.

Reviewed changes

Copilot reviewed 121 out of 124 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
webapi/proto/web_api.proto	Removes legacy app-session RPC/messages and changes settle-finalized response to timestamp.
webapi/osp_pay_api_server_test.go	Updates OSP WebAPI server tests for trimmed app-session backend surface.
webapi/osp_pay_api_server.go	Removes app-session status plumbing from OSP pay WebAPI server.
webapi/api_server_test.go	Adds regression tests for NotFound app-session handling.
webapi/api_server.go	Trims WebAPI app-session handlers, adds NotFound checks, returns timestamps.
tools/scripts/regenerate-legacy-app-bindings.sh	Deletes legacy binding regeneration script.
tools/scripts/regenerate-go-bindings.sh	Adds generated-file breadcrumb header and new BooleanCond bindings.
tools/scripts/README.md	Updates binding regeneration documentation for new script behavior.
tools/osp-cli/cli/cli_onchain_view.go	Switches CLI output from block-based to timestamp-based on-chain views and IBooleanCond.
tools/osp-cli/cli/cli_onchain_op.go	Updates router-registry CLI interpretation from block numbers to timestamps.
tools/osp-cli/cli/cli_flags.go	Removes legacy app decode flag.
tools/osp-cli/cli/cli_db_view.go	Uses wall-clock timestamps for balance computation.
tools/osp-cli/README.md	Documents IBooleanCond-based app on-chain view command.
tools/channel-migration/channel_migrate.go	Compares migration deadlines against wall-clock timestamps.
testing/testapp/utils.go	Deletes legacy test-app helpers tied to removed app-session surface.
testing/testapp/booleancondmock.go	Adds generated mock binding for IBooleanCond.
testing/profile/rt_config_multiosp.json	Expands configured deadline deltas for second-based semantics.
testing/clientcontroller.go	Updates test client helpers for timestamp responses and trimmed app APIs.
test/manual/rt_config.json	Enlarges manual test deadline deltas for second-based semantics.
test/e2e/sliding_window.go	Reworks virtual condition setup to use BooleanCondMock.
test/e2e/setup_onchain.go	Deploys BooleanCondMock instead of legacy app fixtures.
test/e2e/send_pay_with_app.go	Uses virtual BooleanCondMock registration in payment test.
test/e2e/send_pay_timeout.go	Converts timeout test flow to unix timestamps and shorter safe margins.
test/e2e/send_pay_settle.go	Uses simplified virtual condition registration in settle test.
test/e2e/pay_dispute_with_oracle.go	Removes legacy oracle dispute e2e coverage.
test/e2e/osp_webapi_test.go	Updates OSP WebAPI e2e tests for trimmed app-session flow.
test/e2e/multiosp_routing.go	Converts auto-clear routing test to timestamp-based pay expiry.
test/e2e/e2e_test.go	Drops removed legacy app/oracle dispute subtests.
test/e2e/e2e_setup_test.go	Sets low safe-margin env vars for faster timestamp-based e2e flows.
test/e2e/e2e_crossnet_test.go	Rewrites xnet configs at runtime to match deployed token addresses.
test/e2e/channel_view.go	Uses BooleanCondMock for virtual-condition channel-view test.
storage/schema.sql.go	Renames desttokens open-channel field to timestamp-based column.
storage/schema.sql	Updates SQL schema comment/name from block number to timestamp.
storage/dal_sql.go	Renames DAL helpers/queries from open block number to open timestamp.
storage/dal.go	Renames public DAL methods for dest-token open timestamp.
server/server.go	Creates admin payment deadlines from unix time.
server/osp_webapi_backend.go	Simplifies app-session backend calls and switches deadlines to timestamps.
rtconfig/rtconfig.go	Retunes default timeout bounds to second-based values.
rtconfig/config.proto	Updates runtime-config docs for second-based payment timeout.
rtconfig/config.pb.go	Regenerated comment updates for second-based config semantics.
rpc/rpc_grpc.pb.go	Regenerated gRPC interface requiring UnimplementedRpcServer embedding.
rpc/osp_admin_grpc.pb.go	Regenerated admin gRPC interface embedding requirements.
rpc/osp_admin.pb.go	Regenerated protobuf descriptor ordering.
rpc/multiserver_grpc.pb.go	Regenerated multiserver gRPC interface embedding requirements.
rpc/message.pb.go	Regenerated comment clarifying delegation expiry field semantics.
route/rt_builder.go	Renames router registration tracking from block to timestamp.
route/routerregistry/routerregistry.go	Regenerated router-registry binding for timestamp-based contract storage.
route/controller.go	Converts router refresh/expiry logic to unix timestamps.
proto/rpc.proto	Reorders go_package declaration only.
proto/osp_report.proto	Reorders go_package and normalizes formatting.
proto/osp_admin.proto	Reorders imports/options only.
proto/multiserver.proto	Reorders go_package and formats empty messages inline.
proto/message.proto	Reorders go_package and clarifies delegation-expiry semantics.
proto/entity.proto	Minor proto formatting/comment fixes plus year bump.
proto/chain.proto	Minor proto formatting/comment fixes plus year bump.
proto/app.proto	Deletes legacy app-session protobuf definitions.
migrate/migrate_channel.go	Converts migration deadlines and tolerance window to seconds.
messager/send_cond_pay_request.go	Uses unix timestamps for pay deadline checks and balances.
ledgerview/localview.go	Changes balance computation deadline input from block number to timestamp.
handlers/msghdl/handle_pay_settle_request.go	Converts expired-pay settle validation to timestamps.
handlers/msghdl/handle_cond_pay_request.go	Converts pay validation/delegation logic and sync throttling to timestamps.
handlers/msghdl/handle_cond_pay_receipt.go	Converts delegation expiry validation to timestamps.
entity/entity.pb.go	Regenerated comment/spelling fixes in entity bindings.
docs/backend-usage.md	Adds explicit documentation for second-based deadline semantics.
docs/backend-troubleshooting.md	Updates troubleshooting guidance from block height to wall-clock time.
docs/backend-implementation.md	Documents trimmed IBooleanCond app surface and timestamp-based router registry.
dispute/dispute_withdraw.go	Converts withdraw checks and balances to timestamp semantics.
dispute/dispute_payment.go	Converts payment deadline check to timestamps.
dispute/dispute_channel.go	Confirms channel settle using timestamp finalization time.
deploy/ropsten/rt_config.json	Retunes deployment rtconfig values for second-based semantics.
deploy/mainnet/rt_config.json	Retunes mainnet rtconfig deadline deltas for seconds.
delegate/delegate.go	Creates delegated payment deadlines from unix time.
config/config.go	Retunes global timeout constants and adds env-driven safe margins in seconds.
cnode/utils.go	Uses unix timestamps for balance lookups.
cnode/policy_engine.go	Checks open-channel policy deadlines against unix timestamps.
cnode/pay.go	Converts expired-pay detection to timestamp semantics.
cnode/open_channel.go	Converts open deadlines to seconds and adapts event-monitor window.
cnode/cooperativewithdraw/proposer.go	Creates cooperative-withdraw deadlines from unix time.
cnode/cooperativewithdraw/common.go	Uses timestamp-based withdraw balance checks and pending deadlines.
cnode/cnode.go	Simplifies AppClient construction and delegation expiry handling.
client/celer_client.go	Uses timestamps for pending-open tracking and deadline validation.
client/app_channel.go	Removes legacy app-channel APIs; keeps virtual registration/query surface.
client/api.go	Renames open-channel tracking from block number to timestamp.
chain/channel-eth-go/virtresolver/virtresolver.go	Regenerated virt-resolver binding bytecode.
chain/channel-eth-go/routerregistry/routerregistry.go	Regenerated router-registry binding bytecode.
chain/channel-eth-go/ledgerstruct/ledgerstruct.go	Regenerated ledger-struct binding bytecode.
chain/channel-eth-go/balancelimit/balancelimit.go	Regenerated balance-limit binding bytecode.
chain/chain.pb.go	Regenerated chain protobuf header year.
celersdk/utils.go	Simplifies BooleanCondition conversion for deployed/virtual conditions.
celersdk/types.go	Renames BooleanCondition fields to virtual-address / seconds semantics.
celersdk/pay.go	Uses unix timestamps for SDK payment deadlines and documents virtual deploy prerequisite.
celersdk/api.go	Updates SDK docs for timestamp-based pending-open tracking.
app/singlesessionwithoracle.go	Deletes legacy oracle app binding.
app/oracle.go	Deletes legacy oracle protobuf binding.
app/numericoutcome.go	Deletes legacy numeric outcome binding.
app/booleanoutcome.go	Deletes legacy boolean outcome binding.
app/booleancond.go	Adds generated IBooleanCond binding.
app/apputil.go	Deletes legacy app-state encoding/sorting helpers.
app/appclient_virtresolver_watch_test.go	Deletes legacy virt-resolver watch test tied to removed app machinery.
app/app.pb.go	Deletes generated legacy app protobuf binding.
AGENTS.md	Adds repository rule that all deadlines/timeouts are unix seconds.
.gitignore	Ignores .claude workspace artifact.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.