Unblock CI and the demo suite: lint, custody key parsing, multi-step timeout, Palisade clawback

.env.example

@@ -23,6 +23,10 @@
 # ─── IOU integration tests ────────────────────────────────────────────────────
 # Two funded Testnet accounts (issuer + hot wallet). Create with
 # Account.create(), fund via the faucet. Seeds are secrets — do not commit.
+# Both must be set: the token and IOU demos/tests fail fast without the hot
+# wallet. If the built-in faucet is drained or rate-limits, top accounts up at
+# https://test.bithomp.com/faucet — a drained account otherwise surfaces as an
+# unrelated-looking submission failure rather than "out of funds".
 XRPL_ISSUER_SEED=
 XRPL_HOT_WALLET_SEED=
 

docs/api-md/_media/connector-routing.md

@@ -17,7 +17,7 @@ is rejected.
 | Transactor | Local | Ripple Custody | Palisade |
 | ------ | ------ | ------ | ------ |
 | `AccountSet` | signs locally | **native** | **native** |
-| `Clawback` | signs locally | **native** | **native** |
+| `Clawback` | signs locally | **native** | raw fallback¹ |
 | `CredentialAccept` | signs locally | raw fallback¹ | raw fallback¹ |
 | `CredentialCreate` | signs locally | raw fallback¹ | raw fallback¹ |
 | `CredentialDelete` | signs locally | raw fallback¹ | raw fallback¹ |
@@ -69,7 +69,7 @@ operation in-process. Read operations emit no transactor and are omitted.
 | `IOU.authorize()` | `TrustSet` | **native** | **native** |
 | `IOU.lock()` | `TrustSet` | **native** | **native** |
 | `IOU.unlock()` | `TrustSet` | **native** | **native** |
-| `IOU.clawback()` | `Clawback` | **native** | **native** |
+| `IOU.clawback()` | `Clawback` | **native** | raw fallback¹ |
 | `IOU.transfer()` | `Payment` | **native** | **native** |
 | `IOU.buyOffer()` | `OfferCreate` | **native** | **native** |
 | `IOU.sellOffer()` | `OfferCreate` | **native** | **native** |

docs/api-md/classes/IOU.md

@@ -1,19 +1,19 @@
 # Class: IOU
 
-Defined in: [verticals/iou.ts:59](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L59)
+Defined in: [verticals/iou.ts:60](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L60)
 
 The IOU (trust-line currency) vertical, exposed as `client.iou`. Write operations
 act as the issuer ([IOUWriteOptions.from](../interfaces/IOUWriteOptions.md#from), default the primary signer);
 reads take an explicit `account` or default to the primary. Callers name
-their own counterparty (`holder`/`destination`) per call.
+their own counterparty (`holder`/`to`) per call.
 
 ## Constructors
 
 ### new IOU()
 
 > **new IOU**(`host`): [`IOU`](IOU.md)
 
-Defined in: [verticals/iou.ts:67](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L67)
+Defined in: [verticals/iou.ts:68](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L68)
 
 Construct the IOU vertical.
 
@@ -33,7 +33,7 @@ Construct the IOU vertical.
 
 > **authorize**(`params`, `options`?): `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\<[`IOUAuthorizeIntent`](../interfaces/IOUAuthorizeIntent.md)\>\>
 
-Defined in: [verticals/iou.ts:182](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L182)
+Defined in: [verticals/iou.ts:183](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L183)
 
 Grant authorization for a holder to hold this IOU. Only meaningful when
 the issuer's account has `asfRequireAuth` set.
@@ -61,7 +61,7 @@ The submission result, with `{ holder }` as the intent output.
 
 > **buyOffer**(`params`, `options`?): `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\<`undefined`\>\>
 
-Defined in: [verticals/iou.ts:333](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L333)
+Defined in: [verticals/iou.ts:332](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L332)
 
 Place an order on the DEX to acquire more of this IOU.
 
@@ -88,7 +88,7 @@ The submission result.
 
 > **cancelOffer**(`params`, `options`?): `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\<\{ `offerSequence`: `number`; \}\>\>
 
-Defined in: [verticals/iou.ts:365](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L365)
+Defined in: [verticals/iou.ts:364](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L364)
 
 Cancel a standing offer placed by this IOU's issuer.
 
@@ -112,7 +112,7 @@ output.
 
 > **clawback**(`params`, `options`?): `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\<[`IOUClawbackIntent`](../interfaces/IOUClawbackIntent.md)\>\>
 
-Defined in: [verticals/iou.ts:264](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L264)
+Defined in: [verticals/iou.ts:267](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L267)
 
 Reclaim a holder's balance back to the issuer.
 
@@ -141,7 +141,7 @@ output.
 
 > **issue**(`params`, `options`?): `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\<[`IOUIssueIntent`](../interfaces/IOUIssueIntent.md)\>\>
 
-Defined in: [verticals/iou.ts:100](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L100)
+Defined in: [verticals/iou.ts:101](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L101)
 
 Generate a new trust-line-based IOU in one call: the issuer enables
 rippling (`AccountSet`), the hot wallet extends trust to the maximum limit
@@ -191,7 +191,7 @@ one was requested) as its intent output.
 
 > **list**(`params`?): `Promise`\<[`IOUListResult`](../interfaces/IOUListResult.md)\>
 
-Defined in: [verticals/iou.ts:149](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L149)
+Defined in: [verticals/iou.ts:150](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L150)
 
 List every IOU trust line for an account. No signer required.
 
@@ -213,7 +213,7 @@ The `iouID`s and shaped trust lines, index-aligned.
 
 > **listOffers**(`params`): `Promise`\<[`ListOffersResult`](../interfaces/ListOffersResult.md)\>
 
-Defined in: [verticals/iou.ts:160](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L160)
+Defined in: [verticals/iou.ts:161](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L161)
 
 List all open offers in the market for this IOU (both sides), tagged
 buy/sell relative to it. No signer required.
@@ -236,7 +236,7 @@ The shaped offers, composable into `buyOffer`/`sellOffer`.
 
 > **lock**(`params`, `options`?): `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\<[`IOULockIntent`](../interfaces/IOULockIntent.md)\>\>
 
-Defined in: [verticals/iou.ts:217](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L217)
+Defined in: [verticals/iou.ts:220](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L220)
 
 Freeze a holder's ability to send and receive this IOU: Individual
 Freeze followed by Deep Freeze.
@@ -265,7 +265,7 @@ intent output.
 
 > **retrieve**(`params`): `Promise`\<[`IOURetrieveResult`](../interfaces/IOURetrieveResult.md)\>
 
-Defined in: [verticals/iou.ts:139](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L139)
+Defined in: [verticals/iou.ts:140](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L140)
 
 Read a single IOU trust line (point-in-time). No signer required.
 
@@ -287,7 +287,7 @@ The `iouID` and the trust-line snapshot (or `undefined`).
 
 > **sellOffer**(`params`, `options`?): `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\<`undefined`\>\>
 
-Defined in: [verticals/iou.ts:349](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L349)
+Defined in: [verticals/iou.ts:348](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L348)
 
 Place an order on the DEX to sell this IOU.
 
@@ -314,7 +314,7 @@ The submission result.
 
 > **transfer**(`params`, `options`?): `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\<[`IOUTransferIntent`](../interfaces/IOUTransferIntent.md)\>\>
 
-Defined in: [verticals/iou.ts:297](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L297)
+Defined in: [verticals/iou.ts:300](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L300)
 
 Send a specified amount of this IOU to a destination account.
 
@@ -329,7 +329,7 @@ Send a specified amount of this IOU to a destination account.
 
 `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\<[`IOUTransferIntent`](../interfaces/IOUTransferIntent.md)\>\>
 
-The submission result, with `{ destination, amount }` as the
+The submission result, with `{ to, amount }` as the
 intent output.
 
 ***
@@ -338,7 +338,7 @@ intent output.
 
 > **unlock**(`params`, `options`?): `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\<[`IOULockIntent`](../interfaces/IOULockIntent.md)\>\>
 
-Defined in: [verticals/iou.ts:239](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L239)
+Defined in: [verticals/iou.ts:242](https://github.com/ripple/simpleXRPL/blob/main/src/verticals/iou.ts#L242)
 
 Restore a holder's ability to send and receive this IOU: clears Deep
 Freeze then Individual Freeze.

docs/api-md/classes/IntentInspector.md

@@ -1,6 +1,6 @@
 # Class: IntentInspector
 
-Defined in: [client/intent-inspector.ts:34](https://github.com/ripple/simpleXRPL/blob/main/src/client/intent-inspector.ts#L34)
+Defined in: [client/intent-inspector.ts:36](https://github.com/ripple/simpleXRPL/blob/main/src/client/intent-inspector.ts#L36)
 
 Read-only observation of custodian governance intents the SDK previously
 created (TDD §10.4): resume polling or waiting on an intent by id after its
@@ -20,7 +20,7 @@ and can't be addressed by an intent id alone.
 
 > **new IntentInspector**(`signers`): [`IntentInspector`](IntentInspector.md)
 
-Defined in: [client/intent-inspector.ts:43](https://github.com/ripple/simpleXRPL/blob/main/src/client/intent-inspector.ts#L43)
+Defined in: [client/intent-inspector.ts:46](https://github.com/ripple/simpleXRPL/blob/main/src/client/intent-inspector.ts#L46)
 
 Construct an intent inspector over the client's signers.
 
@@ -40,7 +40,7 @@ Construct an intent inspector over the client's signers.
 
 > **await**(`intentId`, `timeoutMs`?): `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\>
 
-Defined in: [client/intent-inspector.ts:68](https://github.com/ripple/simpleXRPL/blob/main/src/client/intent-inspector.ts#L68)
+Defined in: [client/intent-inspector.ts:74](https://github.com/ripple/simpleXRPL/blob/main/src/client/intent-inspector.ts#L74)
 
 Resume blocking on an intent until it reaches a terminal state.
 
@@ -71,11 +71,47 @@ The terminal submission result.
 
 ***
 
+### awaitOnChain()
+
+> **awaitOnChain**(`intentId`, `timeoutMs`?): `Promise`\<`undefined` \| [`OnChainResult`](../interfaces/OnChainResult.md)\>
+
+Defined in: [client/intent-inspector.ts:98](https://github.com/ripple/simpleXRPL/blob/main/src/client/intent-inspector.ts#L98)
+
+Poll the custodian's transaction layer until the XRPL transaction linked to
+`intentId` is confirmed on-chain, then return its outcome.
+
+This covers the second async layer that [await](IntentInspector.md#await) does not: `await`
+returns when the governance intent reaches `Executed` (policy approved),
+while `awaitOnChain` returns when the XRPL transaction is actually
+confirmed on the ledger. Both calls are needed to know that funds or state
+changes have fully landed.
+
+Only available when a Ripple Custody signer is configured.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `intentId` | `string` | The intent id returned at submission. |
+| `timeoutMs`? | `number` | How long to poll before giving up (custodian default if omitted). |
+
+#### Returns
+
+`Promise`\<`undefined` \| [`OnChainResult`](../interfaces/OnChainResult.md)\>
+
+The on-chain result, or `undefined` when the timeout elapses.
+
+#### Throws
+
+[SimpleXRPLError](SimpleXRPLError.md) if no Ripple Custody signer is configured.
+
+***
+
 ### handleFor()
 
 > **handleFor**(`intentId`): [`SubmissionHandle`](../interfaces/SubmissionHandle.md)
 
-Defined in: [client/intent-inspector.ts:83](https://github.com/ripple/simpleXRPL/blob/main/src/client/intent-inspector.ts#L83)
+Defined in: [client/intent-inspector.ts:118](https://github.com/ripple/simpleXRPL/blob/main/src/client/intent-inspector.ts#L118)
 
 Build a handle over an intent by id, via the first custodian that can
 observe governance intents.
@@ -102,7 +138,7 @@ A handle to poll or wait on the intent.
 
 > **status**(`intentId`): `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\>
 
-Defined in: [client/intent-inspector.ts:54](https://github.com/ripple/simpleXRPL/blob/main/src/client/intent-inspector.ts#L54)
+Defined in: [client/intent-inspector.ts:60](https://github.com/ripple/simpleXRPL/blob/main/src/client/intent-inspector.ts#L60)
 
 A non-blocking snapshot of an intent's current state.
 

docs/api-md/classes/LocalSigner.md

@@ -36,7 +36,7 @@ This custodian signs locally.
 
 > **get** **primary**(): [`AccountRef`](../interfaces/AccountRef.md)
 
-Defined in: [custodians/local/local-signer.ts:72](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L72)
+Defined in: [custodians/local/local-signer.ts:77](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L77)
 
 The primary account this signer owns.
 
@@ -58,7 +58,7 @@ The custodian's primary account; it owns this account.
 
 > **capabilities**(): [`SignerCapabilities`](../interfaces/SignerCapabilities.md)
 
-Defined in: [custodians/local/local-signer.ts:168](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L168)
+Defined in: [custodians/local/local-signer.ts:173](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L173)
 
 What this custodian can sign, consulted at dispatch time.
 
@@ -78,7 +78,7 @@ Capabilities allowing any transactor via raw signing.
 
 > **listAccounts**(): `Promise`\<[`Account`](../interfaces/Account.md)[]\>
 
-Defined in: [custodians/local/local-signer.ts:177](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L177)
+Defined in: [custodians/local/local-signer.ts:182](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L182)
 
 The full account list, discovered at construction.
 
@@ -98,7 +98,7 @@ One account per wallet, keyed by r-address.
 
 > **sign**(`tx`, `ctx`): `Promise`\<[`SignedEnvelope`](../interfaces/SignedEnvelope.md)\>
 
-Defined in: [custodians/local/local-signer.ts:193](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L193)
+Defined in: [custodians/local/local-signer.ts:198](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L198)
 
 Produce a signed envelope for a transaction (raw-signing paths).
 
@@ -133,7 +133,7 @@ The signed envelope (blob + hash).
 
 > **submitAndWait**(`tx`, `ctx`): `Promise`\<[`SubmissionResult`](../type-aliases/SubmissionResult.md)\>
 
-Defined in: [custodians/local/local-signer.ts:216](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L216)
+Defined in: [custodians/local/local-signer.ts:221](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L221)
 
 Submit and block until the transaction reaches a terminal state. The
 custodian returns the transport result; the vertical attaches the typed
@@ -167,7 +167,7 @@ The xrpld-sourced submission result.
 
 > **submitAsync**(`tx`, `ctx`): `Promise`\<[`SubmissionHandle`](../interfaces/SubmissionHandle.md)\>
 
-Defined in: [custodians/local/local-signer.ts:250](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L250)
+Defined in: [custodians/local/local-signer.ts:255](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L255)
 
 Submit and return a handle once the backend has accepted the intent.
 
@@ -198,7 +198,7 @@ A pre-resolved handle over the submitted transaction.
 
 > `static` **create**(`options`): [`LocalSigner`](LocalSigner.md)
 
-Defined in: [custodians/local/local-signer.ts:93](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L93)
+Defined in: [custodians/local/local-signer.ts:98](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L98)
 
 Build a signer from pre-constructed wallets.
 
@@ -224,7 +224,7 @@ A signer holding the given wallets.
 
 > `static` **fromEnv**(`options`?): [`LocalSigner`](LocalSigner.md)
 
-Defined in: [custodians/local/local-signer.ts:118](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L118)
+Defined in: [custodians/local/local-signer.ts:123](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L123)
 
 Build a signer from `XRPL_*_SEED` environment variables (one wallet per
 seed). The primary defaults to the first seed in scan order.
@@ -251,7 +251,7 @@ A signer holding one wallet per discovered seed.
 
 > `static` **fromSeed**(`seed`): [`LocalSigner`](LocalSigner.md)
 
-Defined in: [custodians/local/local-signer.ts:82](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L82)
+Defined in: [custodians/local/local-signer.ts:87](https://github.com/ripple/simpleXRPL/blob/main/src/custodians/local/local-signer.ts#L87)
 
 Build a signer from a single seed.