@arkade-os/sdk 0.5.0-rc.27 → 0.5.0-rc.28

package/README.md

@@ -1476,6 +1476,41 @@ When you call `wallet.notifyIncomingFunds()` or use `waitForIncomingFunds()`, it
 
 `watcherConfig.failsafePollIntervalMs` (default `20_000`) controls how often the watcher replays repository changes into contract events; it does not fetch fresh VTXOs from the indexer.
 
+#### Compiler artifacts
+
+Read compiler format v1 JSON with `arkade.programFromArtifact`, which returns a normalized Program at version 1. `arkade.parseArtifact` reads normalized Program JSON and defaults omitted versions to 1. Only version 1 is supported, with typed `{ name, type }` declarations for every constructor parameter and call argument. Explicit version 0 programs, including persisted contracts, are rejected; there is no automatic migration. Older SDKs reject version 1 programs rather than silently reconstructing a different script. An Arkade function and its same-named Taproot leaf share one call, such as `contract.functions.claim(...)`. Standalone Taproot functions use their own names, such as `contract.functions.unilateral()`. Leaf order in the artifact still determines the Taproot tree. This example assumes a `digest: bytes32` constructor and a `claim` function with one `preimage: bytes32` covenant argument; providers, wallet, artifact JSON and matching digest/preimage values are already available.
+
+Declarations retain the compiler's native scalar names: `pubkey`, `signature`, `bytes`, `bytes20`, `bytes32`, `asset`, `int`, `bool` and `AssetGroup`. There are no `hash` or `sig` type aliases. Byte types take `Uint8Array`; `int`, `bool` and `AssetGroup` take `bigint | number`, with `bool` restricted to `0` or `1`. Fixed widths follow the type itself, without extra width or boolean flags. The SDK requires every `pubkey` to be a 32-byte x-only key, although the language treats it as a bytes alias. Structs and arrays retain the compiler's flattened scalar field names and ordering.
+
+The normalized Program remains an SDK representation: compiler `constructorInputs` become `params`, spend groups and leaves become named `functions`, and covenant `arkade` becomes `arkadeScript`. `parseArtifact` and `stringifyArtifact` read and write that normalized representation; `programFromArtifact` reads the compiler format. Existing deployment and call methods use the same syntax for imported and hand-written programs.
+
+Before upgrading a wallet with persisted v0 contracts, back up its contract rows and retain a compatible SDK. After the upgrade, `manager.getUnsupportedContracts()` lists the v0 rows the wallet still holds: they stay stored, but their VTXOs are not synced and they cannot be spent or exited. To recover a contract in v1, reconstruct its program with typed declarations while preserving the stored constructor values, signer keys, leaf order and emulator position. Compile with the stored keys and compare the resulting `pkScript` with the original; reconnecting to a server with new keys or defaults can change the address. Only after the scripts match, register the reconstructed contract: over a v0 row with the same script, `register()` (like `manager.createContract`) replaces the row's params in place, then syncs its VTXOs. The row keeps its history, and its label and metadata unless you pass new ones. It leaves any other existing row unchanged. If the scripts differ, continue managing the contract with the compatible SDK. Changing the version number alone is not a migration.
+
+```typescript
+import { arkade, ArkAddress } from '@arkade-os/sdk'
+
+const program = arkade.programFromArtifact(artifactJson)
+const client = await arkade.Arkade.connect({
+  arkade: arkProvider,
+  emulator: emulatorProvider,
+  indexer: indexerProvider,
+  identity: wallet.identity,
+  contractManager: await wallet.getContractManager(),
+})
+const contract = client.contract(program, { digest })
+await contract.register({ label: 'Hashlock' })
+await wallet.send({ address: contract.address, amount: 10_000 })
+
+// Call after funding appears in contract.getUtxos().
+const { txid } = await contract.functions.claim(preimage)
+  .to(ArkAddress.decode(recipientAddress).pkScript, 10_000n)
+  .send()
+```
+
+The connected server supplies `<SERVER_KEY>` (the reserved `server` parameter in normalized Programs) and `<SERVER_EXIT_DELAY>`; conflicting overrides fail, and time-based delays that are not multiples of 512 seconds fail rather than changing the advertised delay. Resolved bindings are persisted, so restoring the contract keeps its script through server key or policy changes. A declared constructor named `user` defaults to the connected identity; other constructor keys and flattened struct/array fields remain caller-provided, using names such as `owners.0.key`. Child-output placeholders remain explicit `bytes32` constructor bindings. Leaf call inputs used as script operands cannot produce a fixed address and are rejected; raw CSV operands must be canonical BIP68 encodings.
+
+For compiler-derived programs, call arguments are covenant inputs in declaration order, followed by non-signature leaf inputs in declaration order. Same-named inputs in the two scopes remain separate positional arguments. Leaf signatures are PSBT signatures, not condition arguments: `send()` supports the connected identity and infrastructure signers; additional identities and covenant-tweaked leaf keys require explicit PSBT signing via `build()`. Covenant signature arguments remain caller-provided; transaction-bound Arkade `checkSig` signatures require an Arkade-specific digest helper, which is deferred. CSV leaves require aged onchain outputs and cannot use this offchain builder. Typed call validation and these spending limits apply to every normalized Program. The public `SignerRef` union is unchanged; version 1 programs store emulator signer placement in optional `emulatorIndex` metadata.
+
 #### HD look-ahead window
 
 HD wallets (`walletMode: 'hd'`, or an explicit HD `DescriptorProvider`) also watch a band of *unused* offchain receive scripts around their allocation watermark, so a payment to an address that some other party issued from the same seed — a merchant backend such as BTCPay Server, or the .NET SDK driving the same wallet — arrives without the user calling `restore()`. `lookAheadWindow` (default `20`) is the per-side width of that band: the wallet watches `[watermark - N, watermark + N]`. Speculative entries are subscription-only; they become contract rows, and enter balances, only once funded.

package/dist/adapters/expo.cjs

@@ -1,18 +1,18 @@
 'use strict';
 
-var chunkDKHBOT5W_cjs = require('../chunk-DKHBOT5W.cjs');
-require('../chunk-URILS6HH.cjs');
-require('../chunk-ZN7BX5XT.cjs');
+var chunk3P7SXAAC_cjs = require('../chunk-3P7SXAAC.cjs');
+require('../chunk-6BJJ47JM.cjs');
+require('../chunk-FGKBQH5S.cjs');
 
 
 
 Object.defineProperty(exports, "ExpoArkProvider", {
   enumerable: true,
-  get: function () { return chunkDKHBOT5W_cjs.ExpoArkProvider; }
+  get: function () { return chunk3P7SXAAC_cjs.ExpoArkProvider; }
 });
 Object.defineProperty(exports, "ExpoIndexerProvider", {
   enumerable: true,
-  get: function () { return chunkDKHBOT5W_cjs.ExpoIndexerProvider; }
+  get: function () { return chunk3P7SXAAC_cjs.ExpoIndexerProvider; }
 });
 //# sourceMappingURL=expo.cjs.map
 //# sourceMappingURL=expo.cjs.map

package/dist/adapters/expo.d.cts

@@ -1,9 +1,9 @@
-import { r as RestArkProvider, o as SettlementEvent, T as TxNotificationEvent, s as RestIndexerProvider, t as SubscriptionResponse } from '../index-BpiwCcFb.cjs';
-export { u as ArkProvider, v as IndexerProvider } from '../index-BpiwCcFb.cjs';
-import '@scure/btc-signer/utils.js';
-import '@scure/btc-signer/psbt.js';
+import { r as RestArkProvider, o as SettlementEvent, T as TxNotificationEvent, s as RestIndexerProvider, t as SubscriptionResponse } from '../ark-CgZYyMpf.cjs';
+export { u as ArkProvider, v as IndexerProvider } from '../ark-CgZYyMpf.cjs';
 import '@scure/btc-signer';
 import '@scure/btc-signer/transaction.js';
+import '@scure/btc-signer/utils.js';
+import '@scure/btc-signer/psbt.js';
 
 /**
  * Expo-compatible Arkade provider implementation using expo/fetch for SSE support.

package/dist/adapters/expo.d.ts

@@ -1,9 +1,9 @@
-import { r as RestArkProvider, o as SettlementEvent, T as TxNotificationEvent, s as RestIndexerProvider, t as SubscriptionResponse } from '../index-BpiwCcFb.js';
-export { u as ArkProvider, v as IndexerProvider } from '../index-BpiwCcFb.js';
-import '@scure/btc-signer/utils.js';
-import '@scure/btc-signer/psbt.js';
+import { r as RestArkProvider, o as SettlementEvent, T as TxNotificationEvent, s as RestIndexerProvider, t as SubscriptionResponse } from '../ark-CgZYyMpf.js';
+export { u as ArkProvider, v as IndexerProvider } from '../ark-CgZYyMpf.js';
 import '@scure/btc-signer';
 import '@scure/btc-signer/transaction.js';
+import '@scure/btc-signer/utils.js';
+import '@scure/btc-signer/psbt.js';
 
 /**
  * Expo-compatible Arkade provider implementation using expo/fetch for SSE support.

package/dist/adapters/expo.js

@@ -1,5 +1,5 @@
-export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-X42Z36L5.js';
-import '../chunk-FTJ2YWJJ.js';
-import '../chunk-RUWTAAJK.js';
+export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-FSSINCR6.js';
+import '../chunk-PHSUZSRH.js';
+import '../chunk-CG7S6CDR.js';
 //# sourceMappingURL=expo.js.map
 //# sourceMappingURL=expo.js.map