@inversealtruism/cairn-sdk 0.3.2 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/board.cjs +1 -1
- package/dist/board.js +2 -2
- package/dist/chunk-7UOTIAYK.js +224 -0
- package/dist/{chunk-CZWDA3A5.js → chunk-DUTVUIQF.js} +1 -1
- package/dist/{chunk-FMXNJQWL.js → chunk-ERBT4DFD.js} +2 -2
- package/dist/{chunk-JKC5K253.js → chunk-OCEHXK6A.js} +1 -1
- package/dist/{chunk-BN3PFJDY.js → chunk-PIPN6FSA.js} +53 -16
- package/dist/{chunk-AGU6K5EZ.js → chunk-QATE6AIP.js} +25 -13
- package/dist/connect.cjs +53 -17
- package/dist/connect.d.cts +11 -2
- package/dist/connect.d.ts +11 -2
- package/dist/connect.js +2 -2
- package/dist/content.cjs +1 -1
- package/dist/content.js +2 -2
- package/dist/controller.cjs +77 -29
- package/dist/controller.d.cts +4 -1
- package/dist/controller.d.ts +4 -1
- package/dist/controller.js +3 -3
- package/dist/index.cjs +317 -71
- package/dist/index.d.cts +65 -18
- package/dist/index.d.ts +65 -18
- package/dist/index.js +235 -181
- package/dist/react.cjs +77 -29
- package/dist/react.js +3 -3
- package/dist/registry.cjs +219 -7
- package/dist/registry.d.cts +16 -11
- package/dist/registry.d.ts +16 -11
- package/dist/registry.js +2 -1
- package/package.json +21 -28
- package/dist/chunk-BGJZF7S2.js +0 -69
package/dist/index.d.cts
CHANGED
|
@@ -10,9 +10,10 @@ export { ContentClientOptions, PreparedContent } from './content.cjs';
|
|
|
10
10
|
import { RegistryClient } from './registry.cjs';
|
|
11
11
|
import { WalletConnection, DetectOptions } from './connect.cjs';
|
|
12
12
|
export { AttestParams, CairnProvider, ConnectResult, FillParams, ProposeParams, ProviderDetail, ProviderInfo, SealClaimParams, SendParams, SignInResult, SiwcParams, SiwcResult, TxResult, WalletCapabilities, WalletPermission, connect, detectProvider, discoverProviders, getWallet, isInstalled } from './connect.cjs';
|
|
13
|
+
import { ProvenOfferTerms } from '@inversealtruism/cairnx-core';
|
|
14
|
+
export { FillEndorsement, FillOutputPlan, FillPreview, FillSafety, ProvenOfferTerms, bindOfferTerms, feeBpsAt, fillEndorsement, fillIsSafe, fillOutputPlan, previewFill, requiredFillOutputs } from '@inversealtruism/cairnx-core';
|
|
13
15
|
import { InclusionResult } from '@inversealtruism/csd-light';
|
|
14
16
|
export { CairnController, CairnControllerOptions, CairnState } from './controller.cjs';
|
|
15
|
-
export { bindOfferTerms, feeBpsAt } from '@inversealtruism/cairnx-core';
|
|
16
17
|
import '@inversealtruism/csd-client';
|
|
17
18
|
import '@inversealtruism/csd-tx';
|
|
18
19
|
import '@inversealtruism/csd-codec';
|
|
@@ -105,15 +106,6 @@ declare class NamesClient {
|
|
|
105
106
|
state(): Promise<unknown>;
|
|
106
107
|
}
|
|
107
108
|
|
|
108
|
-
/** The fee/rebate-relevant fields of an offer, derived from the MERKLE-PROVEN offer (never a served object). */
|
|
109
|
-
interface ProvenOfferTerms {
|
|
110
|
-
height: number;
|
|
111
|
-
feeBps: number;
|
|
112
|
-
value?: string;
|
|
113
|
-
taker?: string;
|
|
114
|
-
bid?: string;
|
|
115
|
-
min?: string;
|
|
116
|
-
}
|
|
117
109
|
/** The trust-labeled verdict. `ok:false` + `transient:true` = a retryable chain-catching-up soft-fail (NOT a
|
|
118
110
|
* proven mismatch). `payto`/`seller`/`terms` are populated whenever they could be merkle-derived. */
|
|
119
111
|
interface OfferFillCheck {
|
|
@@ -127,13 +119,24 @@ interface OfferFillCheck {
|
|
|
127
119
|
seller?: string;
|
|
128
120
|
terms?: ProvenOfferTerms;
|
|
129
121
|
blockHeight?: number;
|
|
122
|
+
/** B7b (REBIND W3/M1): the PROVEN CSD outputs to build for `pay` (a WHOLE fill of a non-partial offer),
|
|
123
|
+
* sized from the merkle-proven offer by the single-sourced `fillOutputPlan`. Present only when `pay` was
|
|
124
|
+
* passed and the offer could be sized. Build EXACTLY these; never the resolver-served outputs a lying
|
|
125
|
+
* resolver could redirect. A partial (min-bearing) offer is left unsized (its running paid/delivered is
|
|
126
|
+
* not provable at this corroboration layer; the wallet's fill-SPV is the payment-grade sizer). */
|
|
127
|
+
outputPlan?: {
|
|
128
|
+
to: string;
|
|
129
|
+
value: bigint;
|
|
130
|
+
}[];
|
|
130
131
|
}
|
|
131
132
|
|
|
132
133
|
/**
|
|
133
134
|
* Pre-verify an offer on-chain before building a `fillOffer` payment. `light` is a PoW-verifying light client
|
|
134
135
|
* (its `verifyTxInclusion` surfaces the merkle-proven tx + committed appPayloadHash); `client` reads source txs
|
|
135
136
|
* for the prevout-owner author bind. Pass `servedOffer` (the resolver's offer object) to also bind its
|
|
136
|
-
* payto/seller/terms to the proven values.
|
|
137
|
+
* payto/seller/terms to the proven values. The FULL object is required: a served offer missing want.payto
|
|
138
|
+
* or seller is refused (P75-5). A token-priced offer's served want.ticker/want.amount are bound verbatim to
|
|
139
|
+
* the record. See the module header for the trust posture.
|
|
137
140
|
*/
|
|
138
141
|
declare function preverifyOffer(opts: {
|
|
139
142
|
light: {
|
|
@@ -144,11 +147,20 @@ declare function preverifyOffer(opts: {
|
|
|
144
147
|
};
|
|
145
148
|
offerId: string;
|
|
146
149
|
servedOffer?: unknown;
|
|
150
|
+
/** B7b (REBIND W3/M1): the CSD base units you intend to pay. When given, the result carries `outputPlan`
|
|
151
|
+
* (the PROVEN CSD outputs to build for a WHOLE fill of a non-partial offer, sized by the single-sourced
|
|
152
|
+
* `fillOutputPlan`) and, if you also pass `plannedOutputs`, binds them EXACTLY to that proven plan.
|
|
153
|
+
* A partial (min-bearing) offer is left unsized here; the wallet's fill-SPV is its payment-grade sizer. */
|
|
154
|
+
pay?: bigint | string | number;
|
|
155
|
+
/** B7b: your planned per-address CSD sums (the outputs you WILL build), bound both ways to `outputPlan`.
|
|
156
|
+
* Requires `pay`. A missing/low leg is a doomed underpay; an extra/high leg is a W3 overpay or an N26
|
|
157
|
+
* smuggled output - both refused. */
|
|
158
|
+
plannedOutputs?: Record<string, bigint | string | number>;
|
|
147
159
|
}): Promise<OfferFillCheck>;
|
|
148
160
|
|
|
149
161
|
/** Stable machine-readable error codes (branch on these, not the message text). */
|
|
150
162
|
type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "ACCOUNT_CHANGED" | "FIRST_PARTY_ONLY" | "RATE_LIMITED" | "APPROVAL_CLOSED" | "FORBIDDEN" | "INTERNAL" | "GHOST_INPUTS_SKIPPED" | "VERIFY_UNAVAILABLE" | "VERIFY_TAMPER" | "INSUFFICIENT" | "TOO_MANY_INPUTS" | "FEE_TOO_LOW" | "FEE_CAP" | "BAD_FEE" | "ZERO_ADDR_REFUSED" | "BAD_OUTPUTS" | "NO_OUTPUTS" | "BAD_REQUEST" | "OFFER_UNKNOWN" | "FILL_UNSAFE" | "FILL_WRONG_TARGET" | "SOURCE_DIVERGENCE" | "SUBMIT_REJECTED" | "SUBMIT_MAYBE_INFLIGHT" | "SUBMIT_DUPLICATE" | "NOTHING_TO_CONSOLIDATE" | "UNKNOWN";
|
|
151
|
-
declare const SDK_VERSION = "0.
|
|
163
|
+
declare const SDK_VERSION = "0.4.1";
|
|
152
164
|
interface CairnErrorOptions {
|
|
153
165
|
code?: CairnErrorCode;
|
|
154
166
|
docsPath?: string;
|
|
@@ -168,7 +180,7 @@ declare class CairnError extends Error {
|
|
|
168
180
|
/** Relative docs path (under the SDK docs base), if any. */
|
|
169
181
|
readonly docsPath?: string;
|
|
170
182
|
/** The cairn-sdk version that produced this error. */
|
|
171
|
-
readonly version = "0.
|
|
183
|
+
readonly version = "0.4.1";
|
|
172
184
|
/**
|
|
173
185
|
* Whether a dApp may safely AUTO-retry this failure. `false` for fund-safety refusals and user-intent
|
|
174
186
|
* declines (the default); `true` only for provably transient infra faults where nothing was signed.
|
|
@@ -307,8 +319,9 @@ declare class Cairn {
|
|
|
307
319
|
wallet?: WalletConnection;
|
|
308
320
|
private readonly cairnHttp;
|
|
309
321
|
private _spvLight;
|
|
310
|
-
private
|
|
322
|
+
private _spvSeedInflight;
|
|
311
323
|
private readonly _spvCp;
|
|
324
|
+
private readonly _cairnBase;
|
|
312
325
|
constructor(config?: CairnConfig);
|
|
313
326
|
/**
|
|
314
327
|
* PoW-VERIFIED header merkle at a height (audit M3 — the no-PoW half). Lazily seeds a light
|
|
@@ -317,11 +330,38 @@ declare class Cairn {
|
|
|
317
330
|
* checkpoint (can't verify backward) or if verification fails — the IndexerClient then degrades
|
|
318
331
|
* to the honest "proof-consistent" instead of over-claiming "verified-inclusion". The verified
|
|
319
332
|
* header chain is cached across calls; the first call near tip syncs the post-checkpoint span.
|
|
333
|
+
* MF-03: a STRUCTURAL forward-sync break (a reorg orphaned the cached tip) reseeds ONCE via
|
|
334
|
+
* withSpvReseed. RESIDUAL: a height at or below the cached tip answers from the cached branch with
|
|
335
|
+
* NO network touch, so a tx in a reorg-orphaned block can still read "verified-inclusion" until a
|
|
336
|
+
* read PAST the tip trips the reseed; this closes the permanent post-reorg brick, not reorg-blindness.
|
|
320
337
|
*/
|
|
321
338
|
private verifiedHeaderMerkleAt;
|
|
322
|
-
|
|
323
|
-
|
|
339
|
+
private withSpvReseed;
|
|
340
|
+
private seedFreshSpvLight;
|
|
341
|
+
/** The PoW-verifying SPV light client, seeded from the pinned checkpoint and cached across calls
|
|
342
|
+
* (shared by the M3 header-merkle bind and the F13 offer pre-verify). The client is committed to
|
|
343
|
+
* the field ONLY after a fully successful seed (MF-14): a failed seed leaves NO cached state, so
|
|
344
|
+
* the next call retries on a fresh client instead of wedging on "seedTrusted must be called on a
|
|
345
|
+
* fresh client". Concurrent first callers share ONE in-flight seed. Re-seeded only when a
|
|
346
|
+
* structural (reorg) break is detected, see withSpvReseed. */
|
|
324
347
|
private seededSpvLight;
|
|
348
|
+
/**
|
|
349
|
+
* W12 batch header transport for the checkpoint..tip forward sync, backed by the cairn server's
|
|
350
|
+
* `/api/headers/:from/:count`. Carries ZERO trust: the LightClient re-verifies every header's PoW /
|
|
351
|
+
* prev-link / LWMA, so a forged or stale row fails closed and retrying transport proves nothing new.
|
|
352
|
+
* Retry budget: a 429 (per-IP header budget) or 502/503 (a height past the lagging indexer, or the
|
|
353
|
+
* server's 10s deadline), a transport/timeout error, or a body-read fault (an oversize stream past the
|
|
354
|
+
* SPV_MAX_BATCH_BYTES cap, or a non-JSON 200 body such as a CF interstitial) is a transient
|
|
355
|
+
* data-availability hiccup; back off (honouring Retry-After) a bounded number of times, then THROW so
|
|
356
|
+
* `sync()` fails closed. A non-dense range is rejected terminally (never retried).
|
|
357
|
+
*
|
|
358
|
+
* B7d / F6 DEPENDENCY: `/api/headers` serves no Access-Control-Allow-Origin today (`corsPublic` is
|
|
359
|
+
* mounted on `/explorer/api`, `/trade/api` and `/api/rpc`, not here). A SAME-ORIGIN dApp (hosted on the
|
|
360
|
+
* cairn base) reaches it now; a CROSS-ORIGIN third-party dApp cannot until B7d adds the CORS mount and
|
|
361
|
+
* restarts the cairn service. This code is correct as written; it becomes reachable cross-origin only
|
|
362
|
+
* once B7d ships. This is a recorded dependency, not a blocker for authoring/testing.
|
|
363
|
+
*/
|
|
364
|
+
private fetchHeadersBatch;
|
|
325
365
|
/**
|
|
326
366
|
* F13 — corroborate an offer ON-CHAIN before building a `fillOffer` payment's `outputs`. Merkle-proves the
|
|
327
367
|
* offer into the PoW-verified header chain (from the pinned SPV checkpoint), binds the record to its on-chain
|
|
@@ -333,8 +373,15 @@ declare class Cairn {
|
|
|
333
373
|
* This is best-effort corroboration, NOT the payment-grade boundary: the Cairn Wallet's OWN on-device
|
|
334
374
|
* fill-SPV (0.2.60+, fails-closed before signing) is that. A dApp settling real value should still clear this
|
|
335
375
|
* before building `outputs`, so it never hands the wallet a payment a lying resolver would redirect.
|
|
376
|
+
*
|
|
377
|
+
* Pass opts.pay (the CSD base units you intend to pay) to receive the PROVEN outputPlan for a whole fill of a
|
|
378
|
+
* non-partial offer, and opts.plannedOutputs to bind your planned per-address sums to it before signing; build
|
|
379
|
+
* EXACTLY the outputPlan, never resolver-served outputs.
|
|
336
380
|
*/
|
|
337
|
-
verifyOfferForFill(offerId: string, servedOffer?: unknown
|
|
381
|
+
verifyOfferForFill(offerId: string, servedOffer?: unknown, opts?: {
|
|
382
|
+
pay?: bigint | string | number;
|
|
383
|
+
plannedOutputs?: Record<string, bigint | string | number>;
|
|
384
|
+
}): Promise<OfferFillCheck>;
|
|
338
385
|
/**
|
|
339
386
|
* Detect + connect the Cairn Wallet (browser only). Wires the wallet into
|
|
340
387
|
* `cairn.board` for signed writes. Resolves to the connected address.
|
|
@@ -346,4 +393,4 @@ declare class Cairn {
|
|
|
346
393
|
get connected(): boolean;
|
|
347
394
|
}
|
|
348
395
|
|
|
349
|
-
export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, Http, HttpError, IndexerClient, type NameDetail, type NameResolution, NamesClient, NotInstalledError, type OfferFillCheck, type PrimaryName,
|
|
396
|
+
export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, Http, HttpError, IndexerClient, type NameDetail, type NameResolution, NamesClient, NotInstalledError, type OfferFillCheck, type PrimaryName, RegistryClient, SDK_VERSION, SubmitInFlightError, type TokenInfo, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, errorCode, mapProviderError, mapSubmitResultError, preverifyOffer };
|
package/dist/index.d.ts
CHANGED
|
@@ -10,9 +10,10 @@ export { ContentClientOptions, PreparedContent } from './content.js';
|
|
|
10
10
|
import { RegistryClient } from './registry.js';
|
|
11
11
|
import { WalletConnection, DetectOptions } from './connect.js';
|
|
12
12
|
export { AttestParams, CairnProvider, ConnectResult, FillParams, ProposeParams, ProviderDetail, ProviderInfo, SealClaimParams, SendParams, SignInResult, SiwcParams, SiwcResult, TxResult, WalletCapabilities, WalletPermission, connect, detectProvider, discoverProviders, getWallet, isInstalled } from './connect.js';
|
|
13
|
+
import { ProvenOfferTerms } from '@inversealtruism/cairnx-core';
|
|
14
|
+
export { FillEndorsement, FillOutputPlan, FillPreview, FillSafety, ProvenOfferTerms, bindOfferTerms, feeBpsAt, fillEndorsement, fillIsSafe, fillOutputPlan, previewFill, requiredFillOutputs } from '@inversealtruism/cairnx-core';
|
|
13
15
|
import { InclusionResult } from '@inversealtruism/csd-light';
|
|
14
16
|
export { CairnController, CairnControllerOptions, CairnState } from './controller.js';
|
|
15
|
-
export { bindOfferTerms, feeBpsAt } from '@inversealtruism/cairnx-core';
|
|
16
17
|
import '@inversealtruism/csd-client';
|
|
17
18
|
import '@inversealtruism/csd-tx';
|
|
18
19
|
import '@inversealtruism/csd-codec';
|
|
@@ -105,15 +106,6 @@ declare class NamesClient {
|
|
|
105
106
|
state(): Promise<unknown>;
|
|
106
107
|
}
|
|
107
108
|
|
|
108
|
-
/** The fee/rebate-relevant fields of an offer, derived from the MERKLE-PROVEN offer (never a served object). */
|
|
109
|
-
interface ProvenOfferTerms {
|
|
110
|
-
height: number;
|
|
111
|
-
feeBps: number;
|
|
112
|
-
value?: string;
|
|
113
|
-
taker?: string;
|
|
114
|
-
bid?: string;
|
|
115
|
-
min?: string;
|
|
116
|
-
}
|
|
117
109
|
/** The trust-labeled verdict. `ok:false` + `transient:true` = a retryable chain-catching-up soft-fail (NOT a
|
|
118
110
|
* proven mismatch). `payto`/`seller`/`terms` are populated whenever they could be merkle-derived. */
|
|
119
111
|
interface OfferFillCheck {
|
|
@@ -127,13 +119,24 @@ interface OfferFillCheck {
|
|
|
127
119
|
seller?: string;
|
|
128
120
|
terms?: ProvenOfferTerms;
|
|
129
121
|
blockHeight?: number;
|
|
122
|
+
/** B7b (REBIND W3/M1): the PROVEN CSD outputs to build for `pay` (a WHOLE fill of a non-partial offer),
|
|
123
|
+
* sized from the merkle-proven offer by the single-sourced `fillOutputPlan`. Present only when `pay` was
|
|
124
|
+
* passed and the offer could be sized. Build EXACTLY these; never the resolver-served outputs a lying
|
|
125
|
+
* resolver could redirect. A partial (min-bearing) offer is left unsized (its running paid/delivered is
|
|
126
|
+
* not provable at this corroboration layer; the wallet's fill-SPV is the payment-grade sizer). */
|
|
127
|
+
outputPlan?: {
|
|
128
|
+
to: string;
|
|
129
|
+
value: bigint;
|
|
130
|
+
}[];
|
|
130
131
|
}
|
|
131
132
|
|
|
132
133
|
/**
|
|
133
134
|
* Pre-verify an offer on-chain before building a `fillOffer` payment. `light` is a PoW-verifying light client
|
|
134
135
|
* (its `verifyTxInclusion` surfaces the merkle-proven tx + committed appPayloadHash); `client` reads source txs
|
|
135
136
|
* for the prevout-owner author bind. Pass `servedOffer` (the resolver's offer object) to also bind its
|
|
136
|
-
* payto/seller/terms to the proven values.
|
|
137
|
+
* payto/seller/terms to the proven values. The FULL object is required: a served offer missing want.payto
|
|
138
|
+
* or seller is refused (P75-5). A token-priced offer's served want.ticker/want.amount are bound verbatim to
|
|
139
|
+
* the record. See the module header for the trust posture.
|
|
137
140
|
*/
|
|
138
141
|
declare function preverifyOffer(opts: {
|
|
139
142
|
light: {
|
|
@@ -144,11 +147,20 @@ declare function preverifyOffer(opts: {
|
|
|
144
147
|
};
|
|
145
148
|
offerId: string;
|
|
146
149
|
servedOffer?: unknown;
|
|
150
|
+
/** B7b (REBIND W3/M1): the CSD base units you intend to pay. When given, the result carries `outputPlan`
|
|
151
|
+
* (the PROVEN CSD outputs to build for a WHOLE fill of a non-partial offer, sized by the single-sourced
|
|
152
|
+
* `fillOutputPlan`) and, if you also pass `plannedOutputs`, binds them EXACTLY to that proven plan.
|
|
153
|
+
* A partial (min-bearing) offer is left unsized here; the wallet's fill-SPV is its payment-grade sizer. */
|
|
154
|
+
pay?: bigint | string | number;
|
|
155
|
+
/** B7b: your planned per-address CSD sums (the outputs you WILL build), bound both ways to `outputPlan`.
|
|
156
|
+
* Requires `pay`. A missing/low leg is a doomed underpay; an extra/high leg is a W3 overpay or an N26
|
|
157
|
+
* smuggled output - both refused. */
|
|
158
|
+
plannedOutputs?: Record<string, bigint | string | number>;
|
|
147
159
|
}): Promise<OfferFillCheck>;
|
|
148
160
|
|
|
149
161
|
/** Stable machine-readable error codes (branch on these, not the message text). */
|
|
150
162
|
type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "ACCOUNT_CHANGED" | "FIRST_PARTY_ONLY" | "RATE_LIMITED" | "APPROVAL_CLOSED" | "FORBIDDEN" | "INTERNAL" | "GHOST_INPUTS_SKIPPED" | "VERIFY_UNAVAILABLE" | "VERIFY_TAMPER" | "INSUFFICIENT" | "TOO_MANY_INPUTS" | "FEE_TOO_LOW" | "FEE_CAP" | "BAD_FEE" | "ZERO_ADDR_REFUSED" | "BAD_OUTPUTS" | "NO_OUTPUTS" | "BAD_REQUEST" | "OFFER_UNKNOWN" | "FILL_UNSAFE" | "FILL_WRONG_TARGET" | "SOURCE_DIVERGENCE" | "SUBMIT_REJECTED" | "SUBMIT_MAYBE_INFLIGHT" | "SUBMIT_DUPLICATE" | "NOTHING_TO_CONSOLIDATE" | "UNKNOWN";
|
|
151
|
-
declare const SDK_VERSION = "0.
|
|
163
|
+
declare const SDK_VERSION = "0.4.1";
|
|
152
164
|
interface CairnErrorOptions {
|
|
153
165
|
code?: CairnErrorCode;
|
|
154
166
|
docsPath?: string;
|
|
@@ -168,7 +180,7 @@ declare class CairnError extends Error {
|
|
|
168
180
|
/** Relative docs path (under the SDK docs base), if any. */
|
|
169
181
|
readonly docsPath?: string;
|
|
170
182
|
/** The cairn-sdk version that produced this error. */
|
|
171
|
-
readonly version = "0.
|
|
183
|
+
readonly version = "0.4.1";
|
|
172
184
|
/**
|
|
173
185
|
* Whether a dApp may safely AUTO-retry this failure. `false` for fund-safety refusals and user-intent
|
|
174
186
|
* declines (the default); `true` only for provably transient infra faults where nothing was signed.
|
|
@@ -307,8 +319,9 @@ declare class Cairn {
|
|
|
307
319
|
wallet?: WalletConnection;
|
|
308
320
|
private readonly cairnHttp;
|
|
309
321
|
private _spvLight;
|
|
310
|
-
private
|
|
322
|
+
private _spvSeedInflight;
|
|
311
323
|
private readonly _spvCp;
|
|
324
|
+
private readonly _cairnBase;
|
|
312
325
|
constructor(config?: CairnConfig);
|
|
313
326
|
/**
|
|
314
327
|
* PoW-VERIFIED header merkle at a height (audit M3 — the no-PoW half). Lazily seeds a light
|
|
@@ -317,11 +330,38 @@ declare class Cairn {
|
|
|
317
330
|
* checkpoint (can't verify backward) or if verification fails — the IndexerClient then degrades
|
|
318
331
|
* to the honest "proof-consistent" instead of over-claiming "verified-inclusion". The verified
|
|
319
332
|
* header chain is cached across calls; the first call near tip syncs the post-checkpoint span.
|
|
333
|
+
* MF-03: a STRUCTURAL forward-sync break (a reorg orphaned the cached tip) reseeds ONCE via
|
|
334
|
+
* withSpvReseed. RESIDUAL: a height at or below the cached tip answers from the cached branch with
|
|
335
|
+
* NO network touch, so a tx in a reorg-orphaned block can still read "verified-inclusion" until a
|
|
336
|
+
* read PAST the tip trips the reseed; this closes the permanent post-reorg brick, not reorg-blindness.
|
|
320
337
|
*/
|
|
321
338
|
private verifiedHeaderMerkleAt;
|
|
322
|
-
|
|
323
|
-
|
|
339
|
+
private withSpvReseed;
|
|
340
|
+
private seedFreshSpvLight;
|
|
341
|
+
/** The PoW-verifying SPV light client, seeded from the pinned checkpoint and cached across calls
|
|
342
|
+
* (shared by the M3 header-merkle bind and the F13 offer pre-verify). The client is committed to
|
|
343
|
+
* the field ONLY after a fully successful seed (MF-14): a failed seed leaves NO cached state, so
|
|
344
|
+
* the next call retries on a fresh client instead of wedging on "seedTrusted must be called on a
|
|
345
|
+
* fresh client". Concurrent first callers share ONE in-flight seed. Re-seeded only when a
|
|
346
|
+
* structural (reorg) break is detected, see withSpvReseed. */
|
|
324
347
|
private seededSpvLight;
|
|
348
|
+
/**
|
|
349
|
+
* W12 batch header transport for the checkpoint..tip forward sync, backed by the cairn server's
|
|
350
|
+
* `/api/headers/:from/:count`. Carries ZERO trust: the LightClient re-verifies every header's PoW /
|
|
351
|
+
* prev-link / LWMA, so a forged or stale row fails closed and retrying transport proves nothing new.
|
|
352
|
+
* Retry budget: a 429 (per-IP header budget) or 502/503 (a height past the lagging indexer, or the
|
|
353
|
+
* server's 10s deadline), a transport/timeout error, or a body-read fault (an oversize stream past the
|
|
354
|
+
* SPV_MAX_BATCH_BYTES cap, or a non-JSON 200 body such as a CF interstitial) is a transient
|
|
355
|
+
* data-availability hiccup; back off (honouring Retry-After) a bounded number of times, then THROW so
|
|
356
|
+
* `sync()` fails closed. A non-dense range is rejected terminally (never retried).
|
|
357
|
+
*
|
|
358
|
+
* B7d / F6 DEPENDENCY: `/api/headers` serves no Access-Control-Allow-Origin today (`corsPublic` is
|
|
359
|
+
* mounted on `/explorer/api`, `/trade/api` and `/api/rpc`, not here). A SAME-ORIGIN dApp (hosted on the
|
|
360
|
+
* cairn base) reaches it now; a CROSS-ORIGIN third-party dApp cannot until B7d adds the CORS mount and
|
|
361
|
+
* restarts the cairn service. This code is correct as written; it becomes reachable cross-origin only
|
|
362
|
+
* once B7d ships. This is a recorded dependency, not a blocker for authoring/testing.
|
|
363
|
+
*/
|
|
364
|
+
private fetchHeadersBatch;
|
|
325
365
|
/**
|
|
326
366
|
* F13 — corroborate an offer ON-CHAIN before building a `fillOffer` payment's `outputs`. Merkle-proves the
|
|
327
367
|
* offer into the PoW-verified header chain (from the pinned SPV checkpoint), binds the record to its on-chain
|
|
@@ -333,8 +373,15 @@ declare class Cairn {
|
|
|
333
373
|
* This is best-effort corroboration, NOT the payment-grade boundary: the Cairn Wallet's OWN on-device
|
|
334
374
|
* fill-SPV (0.2.60+, fails-closed before signing) is that. A dApp settling real value should still clear this
|
|
335
375
|
* before building `outputs`, so it never hands the wallet a payment a lying resolver would redirect.
|
|
376
|
+
*
|
|
377
|
+
* Pass opts.pay (the CSD base units you intend to pay) to receive the PROVEN outputPlan for a whole fill of a
|
|
378
|
+
* non-partial offer, and opts.plannedOutputs to bind your planned per-address sums to it before signing; build
|
|
379
|
+
* EXACTLY the outputPlan, never resolver-served outputs.
|
|
336
380
|
*/
|
|
337
|
-
verifyOfferForFill(offerId: string, servedOffer?: unknown
|
|
381
|
+
verifyOfferForFill(offerId: string, servedOffer?: unknown, opts?: {
|
|
382
|
+
pay?: bigint | string | number;
|
|
383
|
+
plannedOutputs?: Record<string, bigint | string | number>;
|
|
384
|
+
}): Promise<OfferFillCheck>;
|
|
338
385
|
/**
|
|
339
386
|
* Detect + connect the Cairn Wallet (browser only). Wires the wallet into
|
|
340
387
|
* `cairn.board` for signed writes. Resolves to the connected address.
|
|
@@ -346,4 +393,4 @@ declare class Cairn {
|
|
|
346
393
|
get connected(): boolean;
|
|
347
394
|
}
|
|
348
395
|
|
|
349
|
-
export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, Http, HttpError, IndexerClient, type NameDetail, type NameResolution, NamesClient, NotInstalledError, type OfferFillCheck, type PrimaryName,
|
|
396
|
+
export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, Http, HttpError, IndexerClient, type NameDetail, type NameResolution, NamesClient, NotInstalledError, type OfferFillCheck, type PrimaryName, RegistryClient, SDK_VERSION, SubmitInFlightError, type TokenInfo, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, errorCode, mapProviderError, mapSubmitResultError, preverifyOffer };
|