@ocap/tx-protocols 1.30.25 → 1.31.0

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.
Files changed (118) hide show
  1. package/esm/execute.d.mts +7 -0
  2. package/esm/execute.mjs +196 -71
  3. package/esm/gas-security-guard.d.mts +374 -0
  4. package/esm/gas-security-guard.mjs +1101 -0
  5. package/esm/index.d.mts +35 -5
  6. package/esm/index.mjs +3 -1
  7. package/esm/pipes/ensure-cost.mjs +314 -58
  8. package/esm/protocols/account/delegate.mjs +64 -16
  9. package/esm/protocols/account/migrate.d.mts +3 -0
  10. package/esm/protocols/account/migrate.mjs +235 -35
  11. package/esm/protocols/account/revoke-delegate.d.mts +3 -3
  12. package/esm/protocols/account/revoke-delegate.mjs +70 -38
  13. package/esm/protocols/asset/acquire-v2.mjs +29 -12
  14. package/esm/protocols/asset/acquire-v3.mjs +78 -22
  15. package/esm/protocols/asset/calls/transfer-token.mjs +2 -1
  16. package/esm/protocols/asset/calls/transfer.mjs +1 -0
  17. package/esm/protocols/asset/consume.mjs +12 -4
  18. package/esm/protocols/asset/create.mjs +18 -5
  19. package/esm/protocols/asset/mint.mjs +23 -1
  20. package/esm/protocols/asset/pipes/exec-mint-hook.d.mts +21 -1
  21. package/esm/protocols/asset/pipes/exec-mint-hook.mjs +115 -1
  22. package/esm/protocols/asset/pipes/extract-factory-tokens.mjs +14 -8
  23. package/esm/protocols/asset/pipes/verify-itx-address.mjs +9 -0
  24. package/esm/protocols/asset/pipes/verify-itx-assets.mjs +21 -5
  25. package/esm/protocols/asset/update.d.mts +13 -2
  26. package/esm/protocols/asset/update.mjs +133 -14
  27. package/esm/protocols/factory/create.mjs +14 -6
  28. package/esm/protocols/governance/claim-stake.mjs +92 -10
  29. package/esm/protocols/governance/return-stake.mjs +44 -12
  30. package/esm/protocols/governance/revoke-stake.mjs +17 -5
  31. package/esm/protocols/governance/slash-stake.mjs +64 -25
  32. package/esm/protocols/governance/stake.mjs +63 -13
  33. package/esm/protocols/rollup/claim-reward.mjs +39 -20
  34. package/esm/protocols/rollup/close.mjs +1 -1
  35. package/esm/protocols/rollup/create-block.mjs +8 -7
  36. package/esm/protocols/rollup/create.mjs +17 -6
  37. package/esm/protocols/rollup/join.mjs +3 -3
  38. package/esm/protocols/rollup/leave.mjs +1 -1
  39. package/esm/protocols/rollup/migrate.mjs +7 -4
  40. package/esm/protocols/rollup/pipes/verify-evidence.mjs +12 -4
  41. package/esm/protocols/rollup/update.mjs +6 -1
  42. package/esm/protocols/token/create.mjs +23 -12
  43. package/esm/protocols/token/deposit-v2.d.mts +5 -1
  44. package/esm/protocols/token/deposit-v2.mjs +81 -29
  45. package/esm/protocols/token/withdraw-v2.mjs +33 -16
  46. package/esm/protocols/token-factory/burn.mjs +43 -10
  47. package/esm/protocols/token-factory/create.mjs +23 -14
  48. package/esm/protocols/token-factory/mint.mjs +54 -21
  49. package/esm/protocols/token-factory/pipes/verify-icon.mjs +1 -1
  50. package/esm/protocols/token-factory/update.mjs +16 -6
  51. package/esm/protocols/trade/exchange-v2.d.mts +4 -0
  52. package/esm/protocols/trade/exchange-v2.mjs +78 -22
  53. package/esm/protocols/trade/transfer-v2.mjs +44 -13
  54. package/esm/protocols/trade/transfer-v3.mjs +72 -31
  55. package/esm/util.d.mts +3 -1
  56. package/esm/util.mjs +26 -17
  57. package/lib/execute.cjs +193 -67
  58. package/lib/execute.d.cts +7 -0
  59. package/lib/gas-security-guard.cjs +1140 -0
  60. package/lib/gas-security-guard.d.cts +374 -0
  61. package/lib/index.cjs +122 -1
  62. package/lib/index.d.cts +36 -6
  63. package/lib/pipes/ensure-cost.cjs +313 -57
  64. package/lib/protocols/account/delegate.cjs +64 -16
  65. package/lib/protocols/account/migrate.cjs +235 -35
  66. package/lib/protocols/account/migrate.d.cts +3 -0
  67. package/lib/protocols/account/revoke-delegate.cjs +71 -39
  68. package/lib/protocols/account/revoke-delegate.d.cts +3 -3
  69. package/lib/protocols/asset/acquire-v2.cjs +28 -11
  70. package/lib/protocols/asset/acquire-v3.cjs +77 -20
  71. package/lib/protocols/asset/calls/transfer-token.cjs +3 -2
  72. package/lib/protocols/asset/calls/transfer.cjs +1 -0
  73. package/lib/protocols/asset/consume.cjs +11 -3
  74. package/lib/protocols/asset/create.cjs +19 -6
  75. package/lib/protocols/asset/mint.cjs +23 -1
  76. package/lib/protocols/asset/pipes/exec-mint-hook.cjs +117 -1
  77. package/lib/protocols/asset/pipes/exec-mint-hook.d.cts +21 -1
  78. package/lib/protocols/asset/pipes/extract-factory-tokens.cjs +14 -9
  79. package/lib/protocols/asset/pipes/verify-itx-address.cjs +9 -0
  80. package/lib/protocols/asset/pipes/verify-itx-assets.cjs +21 -5
  81. package/lib/protocols/asset/update.cjs +131 -12
  82. package/lib/protocols/asset/update.d.cts +13 -2
  83. package/lib/protocols/factory/create.cjs +14 -6
  84. package/lib/protocols/governance/claim-stake.cjs +92 -9
  85. package/lib/protocols/governance/claim-stake.d.cts +1 -1
  86. package/lib/protocols/governance/return-stake.cjs +44 -11
  87. package/lib/protocols/governance/return-stake.d.cts +1 -1
  88. package/lib/protocols/governance/revoke-stake.cjs +17 -5
  89. package/lib/protocols/governance/revoke-stake.d.cts +1 -1
  90. package/lib/protocols/governance/slash-stake.cjs +64 -24
  91. package/lib/protocols/governance/slash-stake.d.cts +1 -1
  92. package/lib/protocols/governance/stake.cjs +65 -14
  93. package/lib/protocols/rollup/claim-reward.cjs +39 -20
  94. package/lib/protocols/rollup/close.cjs +1 -1
  95. package/lib/protocols/rollup/create-block.cjs +9 -8
  96. package/lib/protocols/rollup/create-block.d.cts +1 -1
  97. package/lib/protocols/rollup/create.cjs +18 -7
  98. package/lib/protocols/rollup/join.cjs +3 -3
  99. package/lib/protocols/rollup/leave.cjs +1 -1
  100. package/lib/protocols/rollup/migrate.cjs +7 -4
  101. package/lib/protocols/rollup/pipes/verify-evidence.cjs +11 -3
  102. package/lib/protocols/rollup/update.cjs +6 -1
  103. package/lib/protocols/token/create.cjs +24 -13
  104. package/lib/protocols/token/deposit-v2.cjs +80 -28
  105. package/lib/protocols/token/deposit-v2.d.cts +5 -1
  106. package/lib/protocols/token/withdraw-v2.cjs +32 -15
  107. package/lib/protocols/token-factory/burn.cjs +42 -9
  108. package/lib/protocols/token-factory/create.cjs +24 -15
  109. package/lib/protocols/token-factory/mint.cjs +53 -20
  110. package/lib/protocols/token-factory/pipes/verify-icon.cjs +1 -1
  111. package/lib/protocols/token-factory/update.cjs +16 -6
  112. package/lib/protocols/trade/exchange-v2.cjs +76 -20
  113. package/lib/protocols/trade/exchange-v2.d.cts +4 -0
  114. package/lib/protocols/trade/transfer-v2.cjs +45 -14
  115. package/lib/protocols/trade/transfer-v3.cjs +72 -30
  116. package/lib/util.cjs +26 -17
  117. package/lib/util.d.cts +4 -2
  118. package/package.json +16 -16
@@ -0,0 +1,374 @@
1
+ import { BN } from "@ocap/util";
2
+ import { IChainConfig, IStakeState } from "@ocap/types";
3
+
4
+ //#region src/gas-security-guard.d.ts
5
+ declare const DEFAULT_MAX_FREE_GAS_TX_SIZE = 4096;
6
+ declare const DEFAULT_MAX_FREE_GAS_STATE_OPS = 6;
7
+ declare const DEFAULT_BURST_WINDOW_MS = 60000;
8
+ declare const DEFAULT_BASE_BURST_ALLOWANCE = 10;
9
+ declare const DEFAULT_BURST_REJECT_MULTIPLE = 100;
10
+ declare const DEFAULT_DELEGATED_BURST_MULTIPLE = 20;
11
+ declare const DEFAULT_STRIKE_WINDOW_MS = 600000;
12
+ declare const DEFAULT_WARNING_STRIKE_THRESHOLD = 2;
13
+ declare const DEFAULT_THROTTLE_STRIKE_THRESHOLD = 5;
14
+ declare const DEFAULT_SLASH_STRIKE_THRESHOLD = 10;
15
+ declare const DEFAULT_THROTTLE_COOLDOWN_MS = 15000;
16
+ declare const DEFAULT_GAS_PASS_EPOCH_SECONDS = 60;
17
+ declare const DEFAULT_FISHERMAN_BOUNTY_BPS = 1000;
18
+ /**
19
+ * High-overhead creator, factory, token-issuance, rollup, and batch transaction types
20
+ * that ALWAYS require direct gas payment (`requiresDirectGas: true`) and cannot waive
21
+ * gas via self-staked `Stake-for-Gas` or Unlinkable Gas Pass.
22
+ */
23
+ declare const DIRECT_GAS_REQUIRED_TX_TYPES: ReadonlySet<string>;
24
+ /**
25
+ * Everyday end-user transaction types eligible for `Stake-for-Gas` free gas waiver
26
+ * when within the 3D envelope (`txType` allowlist + `txSize <= 4096` + `stateOps <= 6`).
27
+ */
28
+ declare const FREE_GAS_ELIGIBLE_TX_TYPES: ReadonlySet<string>;
29
+ type SecurityStrikeTier = 'NORMAL' | 'WARNING' | 'THROTTLED' | 'SLASH_TRIGGERED';
30
+ type StrikeReasonCategory = 'WAF_REJECT' | 'INVARIANT_VIOLATION' | 'PROTOCOL_REJECT' | 'QUOTA_EXCEEDED' | 'BENIGN_REJECT' | 'PAYMASTER_VIOLATION';
31
+ interface ITxGasQuotaTelemetry {
32
+ loadRatio: number;
33
+ remainingNormalQuota: number;
34
+ currentGasMultiplier: number;
35
+ nextTxEstimatedGas: string;
36
+ recommendedBackoffMs: number;
37
+ stakeRequiredFor1x: string;
38
+ }
39
+ interface ITxSecurityWarning {
40
+ tier: SecurityStrikeTier;
41
+ code: string;
42
+ message: string;
43
+ actor: string;
44
+ strikeCount: number;
45
+ warningThreshold: number;
46
+ throttleThreshold: number;
47
+ slashThreshold: number;
48
+ gasStakeQuotaRemaining: number;
49
+ cooldownUntilMs: number;
50
+ telemetry: ITxGasQuotaTelemetry;
51
+ }
52
+ interface IAbuseSlashEvidence {
53
+ evidenceHash: string;
54
+ offender: string;
55
+ stakeAddress: string;
56
+ strikeCount: number;
57
+ reasonCodes: string[];
58
+ recentTxHashes: string[];
59
+ slashedTokens: Record<string, string>;
60
+ fishermanAddress?: string;
61
+ fishermanBounty: string;
62
+ vaultDestination: string;
63
+ vaultAmount: string;
64
+ timestamp: string;
65
+ }
66
+ interface IUnlinkableGasPass {
67
+ stakeId: string;
68
+ epoch: number;
69
+ nullifier: string;
70
+ commitment: string;
71
+ passSecret?: string;
72
+ pk?: string;
73
+ signature?: string;
74
+ }
75
+ interface IPaymasterDecodedClaims {
76
+ iss?: string;
77
+ txHash?: string;
78
+ exp?: number | string;
79
+ nbf?: number | string;
80
+ iat?: number | string;
81
+ allowedTargets?: string[];
82
+ allowedTxTypes?: string[];
83
+ maxGasPerTx?: string | number;
84
+ mode?: 'waiver' | 'paymaster';
85
+ chargeSponsorBalance?: boolean;
86
+ }
87
+ interface IGasSecurityConfig {
88
+ /** Master switch (`transaction.security.enabled`); false disables strikes, throttle, burst quota and slash */
89
+ enabled: boolean;
90
+ /** Strike-based expiring admission cooldown */
91
+ throttle: boolean;
92
+ /** Per-sender burst quota enforced at admission (never reprices gas) */
93
+ burstEscalation: boolean;
94
+ /** Experimental: slash inside the failing queued tx's own write set */
95
+ autoSlash: boolean;
96
+ /** Process-local gas pass nullifier registry (non-deterministic across processes) */
97
+ gasPassNullifierCheck: boolean;
98
+ burstRejectMultiple: number;
99
+ /** Normalized addresses never struck, throttled or burst-limited (operators' own infrastructure) */
100
+ exemptActors: string[];
101
+ /** Aggregate per-delegatee cap across all principals = hard limit x this */
102
+ delegatedBurstMultiple: number;
103
+ maxFreeGasTxSize: number;
104
+ maxFreeGasStateOps: number;
105
+ burstWindowMs: number;
106
+ baseBurstAllowance: number;
107
+ strikeWindowMs: number;
108
+ warningThreshold: number;
109
+ throttleThreshold: number;
110
+ slashThreshold: number;
111
+ throttleCooldownMs: number;
112
+ gasPassEpochSeconds: number;
113
+ fishermanBountyBps: number;
114
+ }
115
+ interface IStrikeEvent {
116
+ timestampMs: number;
117
+ weight: number;
118
+ code: string;
119
+ txHash?: string;
120
+ }
121
+ interface IActorSecurityRecord {
122
+ actor: string;
123
+ bursts: Array<{
124
+ t: number;
125
+ h?: string;
126
+ variants?: string[];
127
+ }>;
128
+ strikes: IStrikeEvent[];
129
+ cooldownUntilMs: number;
130
+ lastSlashEvidence?: IAbuseSlashEvidence;
131
+ lastWarning?: ITxSecurityWarning;
132
+ }
133
+ interface IConsumedNullifierEntry {
134
+ epoch: number;
135
+ txHash: string;
136
+ }
137
+ interface IGasSecurityRegistry {
138
+ actors: Map<string, IActorSecurityRecord>;
139
+ consumedNullifiers: Map<string, Map<string, IConsumedNullifierEntry>>;
140
+ txWarningsByHash: Map<string, ITxSecurityWarning>;
141
+ }
142
+ declare function getGasSecurityRegistry(statedb?: unknown): IGasSecurityRegistry;
143
+ declare function resetGasSecurityState(statedb?: unknown): void;
144
+ declare function normalizeActorAddress(raw: unknown): string;
145
+ declare function normalizeShortTxType(txType: unknown): string;
146
+ declare function resolveGasSecurityConfig(config?: Partial<IChainConfig>): IGasSecurityConfig;
147
+ interface IStakeForGasEligibilityResult {
148
+ eligible: boolean;
149
+ reason?: string;
150
+ }
151
+ /**
152
+ * 3D `Stake-for-Gas` Eligibility Gate:
153
+ * 1. `txType` must be in `FREE_GAS_ELIGIBLE_TX_TYPES` (everyday user actions only).
154
+ * 2. `txSize` must be <= `maxFreeGasTxSize` (default 4096 bytes).
155
+ * 3. `stateOps` (`estimate.create + estimate.update`) must be <= `maxFreeGasStateOps` (default 6).
156
+ * 4. Failed transactions (`isFailedTxGasCharge === true`) NEVER waive gas.
157
+ */
158
+ declare function evaluateStakeForGasEligibility(params: {
159
+ txType?: string;
160
+ txSize?: number;
161
+ gasEstimate?: {
162
+ create?: number;
163
+ update?: number;
164
+ };
165
+ isFailedTxGasCharge?: boolean;
166
+ isThirdPartySponsor?: boolean;
167
+ enforceSponsor3DEligibility?: boolean;
168
+ config?: Partial<IChainConfig>;
169
+ }): IStakeForGasEligibilityResult;
170
+ /**
171
+ * Extracts all target DIDs referenced by a transaction (`itx.to`, `itx.factory`, `itx.tokenFactory`,
172
+ * `itx.address`, `itx.assets`, `itx.inputs`, `itx.outputs`, `itx.sender`, `itx.receiver`) for
173
+ * Paymaster `allowedTargets` scoping.
174
+ */
175
+ declare function extractTransactionTargets(tx: Record<string, unknown> | undefined, decodedItx?: Record<string, unknown> | undefined, txType?: string): string[];
176
+ /**
177
+ * Verifies Merchant / DApp Paymaster (`extra.gasStakeHeaders` JWT) scope constraints:
178
+ * - `allowedTxTypes`: if present, transaction type must be in `allowedTxTypes`.
179
+ * - `allowedTargets`: if present, transaction must touch at least one target and EVERY target
180
+ * touched by the transaction (excluding the sender `tx.from` itself in multi-input change)
181
+ * must be in `allowedTargets`.
182
+ * - `maxGasPerTx`: if present, `totalGas` must not exceed `maxGasPerTx`.
183
+ */
184
+ declare function verifyPaymasterConstraints(params: {
185
+ decoded: IPaymasterDecodedClaims;
186
+ tx?: Record<string, unknown>;
187
+ itx?: Record<string, unknown>;
188
+ txType?: string;
189
+ totalGas?: BN;
190
+ }): {
191
+ valid: boolean;
192
+ reason?: string;
193
+ isPaymasterDirectCharge: boolean;
194
+ };
195
+ /**
196
+ * Computes the SHA-256 hash of a stake owner's secret for Unlinkable Gas Pass verification:
197
+ * `SHA256("ocap:gas-pass-secret:v1:" + passSecret)`
198
+ */
199
+ declare function computeUnlinkableGasPassSecretHash(passSecret: string): string;
200
+ /**
201
+ * Computes the deterministic commitment for a Consumer Self-Use Unlinkable Gas Pass:
202
+ * `SHA256("ocap:gas-pass:v1:" + normalizeActorAddress(stakeId) + ":" + epoch + ":" + nullifier + ":" + txHash)`
203
+ */
204
+ declare function computeUnlinkableGasPassCommitment(params: {
205
+ stakeId: string;
206
+ epoch: number;
207
+ nullifier: string;
208
+ txHash: string;
209
+ }): string;
210
+ /**
211
+ * Verifies and consumes a Consumer Self-Use Unlinkable Gas Pass (`extra.gasPass`),
212
+ * allowing a user who staked ABT on their main DID to pay/waive gas from a fresh
213
+ * unlinked sub-DID without revealing their main DID on-chain in `tx.from`, while
214
+ * strictly enforcing cryptographic authorization (`passSecret` matching `stakeState.gasPassSecretHash`
215
+ * or `pk`+`signature` signed by `stakeState.sender`), `nullifier` single-use per epoch, and
216
+ * stake-proportional quota.
217
+ */
218
+ declare function verifyAndConsumeUnlinkableGasPass(params: {
219
+ gasPass: IUnlinkableGasPass;
220
+ stakeState: IStakeState | null | undefined;
221
+ txHash: string;
222
+ nowMs?: number;
223
+ config: IChainConfig;
224
+ statedb?: unknown;
225
+ }): {
226
+ valid: boolean;
227
+ reason?: string;
228
+ stakeId?: string;
229
+ };
230
+ /**
231
+ * Stake-scaled per-sender burst quota (`rho = n_burst / B_normal(S)`) with machine-readable telemetry.
232
+ *
233
+ * RELIABILITY CONTRACT: the counter is process-local, so it is used for ADMISSION only (reject before the
234
+ * single-writer queue). It never reprices gas, never changes a waiver and never touches receipts; the executed
235
+ * outcome of a tx is a pure function of (tx, on-chain state). A request is rejected only above
236
+ * `baseBurstAllowance * stakeMultiple * burstRejectMultiple` (`hardLimitExceeded`); between 1x and the hard limit
237
+ * it is admitted and only advisory telemetry is returned (`quotaExceeded`).
238
+ */
239
+ declare function evaluateBurstQuota(params: {
240
+ actor: string;
241
+ stakeState?: IStakeState | null;
242
+ baseGas?: BN;
243
+ config: IChainConfig;
244
+ statedb?: unknown;
245
+ nowMs?: number;
246
+ txHash?: string;
247
+ /** Actual (signed) tx hash when `txHash` is the unsigned hash shared by signature variants */
248
+ variantHash?: string;
249
+ /** Overrides `burstRejectMultiple` for the hard limit (aggregate delegatee window) */
250
+ rejectMultiple?: number;
251
+ /** Record this request in the sliding window (default true); rejected requests are never recorded */
252
+ recordBurst?: boolean;
253
+ }): {
254
+ burstCount: number;
255
+ normalAllowance: number;
256
+ hardLimit: number;
257
+ loadRatio: number;
258
+ quotaExceeded: boolean;
259
+ hardLimitExceeded: boolean;
260
+ telemetry: ITxGasQuotaTelemetry;
261
+ };
262
+ declare function classifyErrorStrikeCategory(err: {
263
+ code?: string;
264
+ message?: string;
265
+ } | undefined): {
266
+ shouldRecordStrike: boolean;
267
+ category: StrikeReasonCategory;
268
+ code: string;
269
+ };
270
+ declare function computeActorTier(strikeCount: number, cfg: IGasSecurityConfig): SecurityStrikeTier;
271
+ declare function getActorSecurityStatus(params: {
272
+ actor: string;
273
+ config?: Partial<IChainConfig>;
274
+ statedb?: unknown;
275
+ nowMs?: number;
276
+ telemetry?: ITxGasQuotaTelemetry;
277
+ }): {
278
+ strikeCount: number;
279
+ tier: SecurityStrikeTier;
280
+ cooldownUntilMs: number;
281
+ lastSlashEvidence?: IAbuseSlashEvidence;
282
+ warning?: ITxSecurityWarning;
283
+ };
284
+ /**
285
+ * Resolves the list of cryptographically verified actor addresses that may be penalized
286
+ * with a security strike for a failed or rejected transaction:
287
+ * - Never attributes strikes to `tx.from` or `tx.delegator` unless `VerifySignature` has
288
+ * cryptographically verified the transaction signature (`CRITICAL-2` protection).
289
+ * - When `tx.delegator` is present, attributes strikes ONLY to `tx.delegator` (the verified signer / delegatee),
290
+ * never to the principal `tx.from`, whether or not the delegation verified.
291
+ * - Never attributes sender-induced strikes to a third-party `gasStake.owner` (`CRITICAL-3`).
292
+ */
293
+ declare function resolveVerifiedStrikeActors(ctx: Record<string, unknown> | undefined): Promise<string[]>;
294
+ /**
295
+ * Records a weighted security strike against one or more verified actor addresses,
296
+ * updates their tier (`NORMAL` -> `WARNING` -> `THROTTLED` -> `SLASH_TRIGGERED`), and if `SLASH_TRIGGERED` is reached,
297
+ * executes automatic `Stake-for-Gas` slashing into `config.vaults.slashedStake` (with optional Fisherman bounty split
298
+ * and 0% token burn per Axiom #3).
299
+ */
300
+ declare function recordActorSecurityStrike(params: {
301
+ actors: string[];
302
+ category: StrikeReasonCategory;
303
+ reasonCode: string;
304
+ txHash?: string;
305
+ config?: Partial<IChainConfig>;
306
+ statedb?: unknown;
307
+ txn?: unknown;
308
+ fishermanAddress?: string;
309
+ nowMs?: number;
310
+ telemetry?: ITxGasQuotaTelemetry;
311
+ }): Promise<{
312
+ primaryWarning?: ITxSecurityWarning;
313
+ slashEvidence?: IAbuseSlashEvidence;
314
+ }>;
315
+ interface IActorSecuritySnapshot {
316
+ actors: Map<string, IActorSecurityRecord | null>;
317
+ txWarningExisted?: boolean;
318
+ prevTxWarning?: ITxSecurityWarning;
319
+ txHash?: string;
320
+ }
321
+ declare function snapshotActorSecurityRecords(actors: string[], statedb?: unknown, txHash?: string): IActorSecuritySnapshot;
322
+ declare function restoreActorSecurityRecords(snapshot: IActorSecuritySnapshot, statedb?: unknown): void;
323
+ /**
324
+ * Executes automatic `Stake-for-Gas` slashing when an actor crosses `slashThreshold` (opt-in via
325
+ * `transaction.security.autoSlash`; ONLY inside the enclosing queued tx's own write set, `params.txn` is required):
326
+ * - Transfers 100% of the offender's staked official tokens out of `toStakeAddress(offender, offender)`:
327
+ * - `fishermanBountyBps` (default 10%) to `fishermanAddress` (if provided and distinct from `offender`).
328
+ * - Remaining 90% (or 100% if no fisherman) to `config.vaults.slashedStake` (or `config.vaults.txGas[0]` / `config.vaults.txFee`).
329
+ * - ZERO official tokens are ever burned (Axiom #3).
330
+ * - Creates and persists a deterministic `IAbuseSlashEvidence` record in `statedb.evidence`.
331
+ */
332
+ declare function executeAutoGasStakeSlash(params: {
333
+ offender: string;
334
+ strikeCount: number;
335
+ strikes: IStrikeEvent[];
336
+ config?: Partial<IChainConfig>;
337
+ statedb?: unknown;
338
+ txn?: unknown;
339
+ fishermanAddress?: string;
340
+ nowMs?: number;
341
+ }): Promise<IAbuseSlashEvidence | null>;
342
+ /**
343
+ * Pre-queue ADMISSION control. This is the only consumer of the process-local strike / burst counters:
344
+ * it decides whether a request is accepted into the single-writer queue at all. It never changes the gas,
345
+ * waiver or receipts of a tx that is admitted, so executed outcomes stay a pure function of (tx, chain state)
346
+ * and cannot diverge between the two OS processes on main or across restarts.
347
+ *
348
+ * - `throttle`: the verified signer (`tx.delegator || tx.from`, i.e. the delegatee for delegated txs) is rejected
349
+ * with `TOO_MANY_TXS` while its strike-driven cooldown is active. Cooldowns always expire; actors without any
350
+ * strikes (and actors without stake) are never locked.
351
+ * - `burstEscalation`: the per-sender sliding-window quota rejects with `TOO_MANY_TXS` only above
352
+ * `baseBurstAllowance * stakeMultiple * burstRejectMultiple`. Keyed by the sender, never by the gas sponsor, so a
353
+ * sponsoring app is not capped across all of its users.
354
+ */
355
+ declare function assertTxAdmission(params: {
356
+ tx: {
357
+ from?: string;
358
+ delegator?: string;
359
+ nonce?: unknown;
360
+ } | undefined;
361
+ txHash?: string;
362
+ /** Hash of the tx without signatures: all signature-malleated twins of one logical tx share it */
363
+ unsignedTxHash?: string;
364
+ config?: Partial<IChainConfig>;
365
+ statedb?: unknown;
366
+ nowMs?: number;
367
+ }): Promise<{
368
+ telemetry?: ITxGasQuotaTelemetry;
369
+ warning?: ITxSecurityWarning;
370
+ }>;
371
+ declare function getTxSecurityWarningByHash(txHash: string, statedb?: unknown): ITxSecurityWarning | undefined;
372
+ declare function setTxSecurityWarningForHash(txHash: string, warning: ITxSecurityWarning, statedb?: unknown): void;
373
+ //#endregion
374
+ export { DEFAULT_BASE_BURST_ALLOWANCE, DEFAULT_BURST_REJECT_MULTIPLE, DEFAULT_BURST_WINDOW_MS, DEFAULT_DELEGATED_BURST_MULTIPLE, DEFAULT_FISHERMAN_BOUNTY_BPS, DEFAULT_GAS_PASS_EPOCH_SECONDS, DEFAULT_MAX_FREE_GAS_STATE_OPS, DEFAULT_MAX_FREE_GAS_TX_SIZE, DEFAULT_SLASH_STRIKE_THRESHOLD, DEFAULT_STRIKE_WINDOW_MS, DEFAULT_THROTTLE_COOLDOWN_MS, DEFAULT_THROTTLE_STRIKE_THRESHOLD, DEFAULT_WARNING_STRIKE_THRESHOLD, DIRECT_GAS_REQUIRED_TX_TYPES, FREE_GAS_ELIGIBLE_TX_TYPES, IAbuseSlashEvidence, IActorSecuritySnapshot, IGasSecurityConfig, IPaymasterDecodedClaims, IStakeForGasEligibilityResult, ITxGasQuotaTelemetry, ITxSecurityWarning, IUnlinkableGasPass, SecurityStrikeTier, StrikeReasonCategory, assertTxAdmission, classifyErrorStrikeCategory, computeActorTier, computeUnlinkableGasPassCommitment, computeUnlinkableGasPassSecretHash, evaluateBurstQuota, evaluateStakeForGasEligibility, executeAutoGasStakeSlash, extractTransactionTargets, getActorSecurityStatus, getGasSecurityRegistry, getTxSecurityWarningByHash, normalizeActorAddress, normalizeShortTxType, recordActorSecurityStrike, resetGasSecurityState, resolveGasSecurityConfig, resolveVerifiedStrikeActors, restoreActorSecurityRecords, setTxSecurityWarningForHash, snapshotActorSecurityRecords, verifyAndConsumeUnlinkableGasPass, verifyPaymasterConstraints };