feat: add Soroban contract error parser, admin client, and updated bi…

CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to `@fundable/sdk` are documented here.
 
+## 0.2.3
+
+Hardened Soroban contract alignment release.
+
+### Added
+
+- Administrative and maintenance clients on `client.admin` (`StellarAdminClient`, `FlowAdminClient`, `LockupAdminClient`, `RouterAdminClient`) exposing:
+  - `proposeUpgrade`, `executeUpgrade`, and direct `upgrade`
+  - Two-step admin transfers: `proposeAdmin`, `acceptAdmin`
+  - Stream TTL extension: `extendStreamTtl`
+  - Router NFT upgrades: `upgradeNft`
+- Comprehensive Soroban error mappings covering Flow 1–28 (e.g. `TokenTransferMismatch`, `TokenDecimalsMismatch`, `ArithmeticError`), Lockup 101–120 (including corrected 111 `NegativeUnlockAmount`, `StartUnlockAmountExceedsTotal`, `GranularityZero`), Stream NFT 201–205, Router 301–305 (`InvalidContractAddress`), Paymaster 401–408.
+- Client-side validations for Lockup unlock amounts (`assertLockupUnlockAmounts`) and token decimals (`assertTokenDecimalsMatch`).
+- Stream NFT delegated queries for Router stream metadata and status.
+
+### Changed
+
+- Regenerated TypeScript contract bindings for Flow, Lockup, Router, Stream NFT, and Paymaster from hardened contract WASM builds.
+- Router `createFlow` and `createLockup` aligned with hardened contract interface, delegating stream token minting and indexing to the Stream NFT contract.
+- Re-exported error parsing and Soroban error definitions (`SOROBAN_CONTRACT_ERRORS`, `parseSorobanErrorCode`, `translateSorobanError`, `toStellarFundableError`).
+
 ## 0.2.1
 
 ### Fixed

docs/generated-bindings.md

@@ -88,3 +88,34 @@ Reproducible WASM SHA-256 values:
 The SDK `0.2.0` bindings were generated from the four reproducible release
 artifacts with the corresponding `pnpm generate:* -- /absolute/path.wasm`
 commands. The transitional Paymaster was intentionally not regenerated.
+
+## Hardened contract release provenance (SDK v0.2.3)
+
+- Contract verification: `make build` and `cargo test` (98 tests passed)
+- Stellar CLI: `stellar 22.0.2`
+
+Optimized WASM SHA-256 values:
+
+| Contract | SHA-256 |
+| --- | --- |
+| Flow | `3903d1dee59ef048a64d5287bb9e27e05d54c3c8dc3962e28c16b2031d074906` |
+| Lockup | `e752e3589144c340136c0fa6a1ab344dd794ad547d3fe0bebcce7c1f995b59fc` |
+| Router | `36e881b771aa6f64bb0d96915e61e6d65a0f976bce332b4b73102ac8d228c4c9` |
+| Stream NFT | `61ec4bfa817780d65ed439b01dc39d703162c6801346427df7a05d4256f94726` |
+| Paymaster | `b068fcfa6103a2686997939d1942629c9f97ce941df85109fd0181f4622e9195` |
+
+The bindings were regenerated with `scripts/generate-stellar-binding.mjs` for all five contracts:
+- `pnpm generate:flow -- /path/to/flow.wasm`
+- `pnpm generate:lockup -- /path/to/lockup.wasm`
+- `pnpm generate:router -- /path/to/router.wasm`
+- `pnpm generate:stream-nft -- /path/to/stream_nft.wasm`
+- `pnpm generate:paymaster -- /path/to/paymaster.wasm`
+
+Key contract changes reflected in SDK v0.2.3:
+- Contract initialization (`initialize`) methods require explicit `admin` authorization.
+- Two-step administrative transfers: `propose_admin` followed by `accept_admin`.
+- Timelocked contract upgrades: `propose_upgrade` followed by `execute_upgrade` (or direct `upgrade` for immediate upgrades).
+- Stream TTL extension: `extend_stream_ttl`.
+- Router delegates NFT ownership and stream indexing to the Stream NFT contract; `create_flow_stream` and `create_lockup_stream` cleanly handle routing without redundant caller parameters.
+- Comprehensive contract error coverage mapped: Flow 1–28, Lockup 101–120, Stream NFT 201–205, Router 301–305, Paymaster 401–408.
+

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fundable/sdk",
-    "version": "0.2.1",
+    "version": "0.2.3",
     "private": false,
     "description": "Multichain TypeScript SDK for Fundable Protocol; Stellar adapter included",
     "license": "MIT",

src/generated/paymaster/src/index.ts

@@ -90,6 +90,9 @@ export interface Client {
    * 
    * # Errors
    * * `PaymasterError::AlreadyInitialized` — if called more than once.
+   * 
+   * # Security
+   * The intended admin must authorize the initialization.
    */
   initialize: ({admin, allowed_fee_tokens}: {admin: string, allowed_fee_tokens: Array<string>}, options?: MethodOptions) => Promise<AssembledTransaction<null>>
 
@@ -123,6 +126,12 @@ export interface Client {
    * 
    * This wraps `forward()` with a simplified interface where the relayer
    * address is the fee recipient and fee_amount == max_fee.
+   * 
+   * # Note on Expiration
+   * 
+   * This wrapper sets the expiration to `current_ledger + 1000` (~83 minutes
+   * at ~5 sec/ledger). This is NOT "no expiration" — it is a generous but
+   * finite window. For indefinite authorization, use `forward()` directly.
    */
   collect_fee_and_invoke: ({user, fee_token, max_fee, relayer, target_contract, function_name, args}: {user: string, fee_token: string, max_fee: i128, relayer: string, target_contract: string, function_name: string, args: Array<any>}, options?: MethodOptions) => Promise<AssembledTransaction<any>>
 
@@ -148,11 +157,11 @@ export class Client extends ContractClient {
         "AAAAAAAABABBdG9taWNhbGx5IGNvbGxlY3QgYSB0b2tlbiBmZWUgZnJvbSB0aGUgdXNlciBhbmQgaW52b2tlIHRoZSB0YXJnZXQKY29udHJhY3QgZnVuY3Rpb24sIHVzaW5nIHRoZSBPcGVuWmVwcGVsaW4gZmVlIGFic3RyYWN0aW9uIGhlbHBlcnMuCgpUaGUgdXNlciBtdXN0IGF1dGhvcml6ZSBib3RoIHRoZSBmZWUgdHJhbnNmZXIgYW5kIHRoZSBkb3duc3RyZWFtCmNvbnRyYWN0IGludm9jYXRpb24gdmlhIFNvcm9iYW4ncyBuYXRpdmUgYXV0aCBmcmFtZXdvcmsuCgojIEFyZ3VtZW50cwoqIGB1c2VyYCDigJQgVGhlIGVuZCB1c2VyIHBheWluZyB0aGUgZmVlIGFuZCBhdXRob3JpemluZyB0aGUgY2FsbC4KKiBgZmVlX3Rva2VuYCDigJQgVGhlIFNBQy9TRVAtNDEgdG9rZW4gdXNlZCBmb3IgZmVlIHBheW1lbnQuCiogYGZlZV9hbW91bnRgIOKAlCBUaGUgYWN0dWFsIGZlZSBhbW91bnQgdG8gdHJhbnNmZXIgZnJvbSB1c2VyLgoqIGBtYXhfZmVlX2Ftb3VudGAg4oCUIFRoZSBtYXhpbXVtIGZlZSB0aGUgdXNlciBhdXRob3JpemVkLgoqIGBleHBpcmF0aW9uX2xlZGdlcmAg4oCUIFRoZSBsZWRnZXIgYXQgd2hpY2ggdGhlIGFwcHJvdmFsIGV4cGlyZXMuCiogYGZlZV9yZWNpcGllbnRgIOKAlCBUaGUgYWRkcmVzcyByZWNlaXZpbmcgdGhlIGZlZSAodHlwaWNhbGx5IHRoZSByZWxheWVyKS4KKiBgdGFyZ2V0X2NvbnRyYWN0YCDigJQgVGhlIGNvbnRyYWN0IHRvIGludm9rZSAoZS5nLiBSb3V0ZXIpLgoqIGBmdW5jdGlvbl9uYW1lYCDigJQgVGhlIGZ1bmN0aW9uIHRvIGNhbGwgb24gdGhlIHRhcmdldCBjb250cmFjdC4KKiBgYXJnc2Ag4oCUIEFyZ3VtZW50cyB0byBwYXNzIHRvIHRoZSB0YXJnZXQgZnVuY3Rpb24uCgojIFJldHVybnMKVGhlIHJhdyBgVmFsYCByZXN1bHQgZnJvbSB0aGUgdGFyZ2V0IGNvbnRyYWN0IGludm9jYXRpb24uCgojIEVycm9ycwoqIGBQYXltYXN0ZXJFcnJvcjo6Tm90SW5pdGlhbGl6ZWRgIOKAlCBjb250cmFjdCBub3QgaW5pdGlhbGl6ZWQuCiogYFBheW1hc3RlckVycm9yOjpUb2tlbk5vdEFsAAAAB2ZvcndhcmQAAAAACQAAAAAAAAAEdXNlcgAAABMAAAAAAAAACWZlZV90b2tlbgAAAAAAABMAAAAAAAAACmZlZV9hbW91bnQAAAAAAAsAAAAAAAAADm1heF9mZWVfYW1vdW50AAAAAAALAAAAAAAAABFleHBpcmF0aW9uX2xlZGdlcgAAAAAAAAQAAAAAAAAADWZlZV9yZWNpcGllbnQAAAAAAAATAAAAAAAAAA90YXJnZXRfY29udHJhY3QAAAAAEwAAAAAAAAANZnVuY3Rpb25fbmFtZQAAAAAAABEAAAAAAAAABGFyZ3MAAAPqAAAAAAAAAAEAAAAA",
         "AAAAAAAAAElVcGdyYWRlIHRoZSBjb250cmFjdCBXQVNNIGJ5dGVjb2RlLgoKIyBBdXRoClJlcXVpcmVzIGFkbWluIGF1dGhvcml6YXRpb24uAAAAAAAAB3VwZ3JhZGUAAAAAAQAAAAAAAAANbmV3X3dhc21faGFzaAAAAAAAA+4AAAAgAAAAAA==",
         "AAAAAAAAABpSZXR1cm5zIHRoZSBhZG1pbiBhZGRyZXNzLgAAAAAACWdldF9hZG1pbgAAAAAAAAAAAAABAAAAEw==",
-        "AAAAAAAAAUxJbml0aWFsaXplIHRoZSBQYXltYXN0ZXIgd2l0aCBhbiBhZG1pbiBhbmQgYW4gaW5pdGlhbCBsaXN0IG9mCmFsbG93ZWQgZmVlIHRva2Vucy4KCiMgQXJndW1lbnRzCiogYGFkbWluYCDigJQgVGhlIGFkbWluIGFkZHJlc3MgKGNhbiB1cGdyYWRlIGFuZCBtYW5hZ2UgdG9rZW4gd2hpdGVsaXN0KS4KKiBgYWxsb3dlZF9mZWVfdG9rZW5zYCDigJQgSW5pdGlhbCBsaXN0IG9mIHRva2VuIGFkZHJlc3NlcyBhY2NlcHRlZApmb3IgZmVlIHBheW1lbnQuCgojIEVycm9ycwoqIGBQYXltYXN0ZXJFcnJvcjo6QWxyZWFkeUluaXRpYWxpemVkYCDigJQgaWYgY2FsbGVkIG1vcmUgdGhhbiBvbmNlLgAAAAppbml0aWFsaXplAAAAAAACAAAAAAAAAAVhZG1pbgAAAAAAABMAAAAAAAAAEmFsbG93ZWRfZmVlX3Rva2VucwAAAAAD6gAAABMAAAAA",
+        "AAAAAAAAAY5Jbml0aWFsaXplIHRoZSBQYXltYXN0ZXIgd2l0aCBhbiBhZG1pbiBhbmQgYW4gaW5pdGlhbCBsaXN0IG9mCmFsbG93ZWQgZmVlIHRva2Vucy4KCiMgQXJndW1lbnRzCiogYGFkbWluYCDigJQgVGhlIGFkbWluIGFkZHJlc3MgKGNhbiB1cGdyYWRlIGFuZCBtYW5hZ2UgdG9rZW4gd2hpdGVsaXN0KS4KKiBgYWxsb3dlZF9mZWVfdG9rZW5zYCDigJQgSW5pdGlhbCBsaXN0IG9mIHRva2VuIGFkZHJlc3NlcyBhY2NlcHRlZApmb3IgZmVlIHBheW1lbnQuCgojIEVycm9ycwoqIGBQYXltYXN0ZXJFcnJvcjo6QWxyZWFkeUluaXRpYWxpemVkYCDigJQgaWYgY2FsbGVkIG1vcmUgdGhhbiBvbmNlLgoKIyBTZWN1cml0eQpUaGUgaW50ZW5kZWQgYWRtaW4gbXVzdCBhdXRob3JpemUgdGhlIGluaXRpYWxpemF0aW9uLgAAAAAACmluaXRpYWxpemUAAAAAAAIAAAAAAAAABWFkbWluAAAAAAAAEwAAAAAAAAASYWxsb3dlZF9mZWVfdG9rZW5zAAAAAAPqAAAAEwAAAAA=",
         "AAAAAAAAAFVBZGQgYSB0b2tlbiB0byB0aGUgYWxsb3dlZCBmZWUgdG9rZW4gd2hpdGVsaXN0LgoKIyBBdXRoClJlcXVpcmVzIGFkbWluIGF1dGhvcml6YXRpb24uAAAAAAAADWFkZF9mZWVfdG9rZW4AAAAAAAABAAAAAAAAAAV0b2tlbgAAAAAAABMAAAAA",
         "AAAAAAAAAFpSZW1vdmUgYSB0b2tlbiBmcm9tIHRoZSBhbGxvd2VkIGZlZSB0b2tlbiB3aGl0ZWxpc3QuCgojIEF1dGgKUmVxdWlyZXMgYWRtaW4gYXV0aG9yaXphdGlvbi4AAAAAABByZW1vdmVfZmVlX3Rva2VuAAAAAQAAAAAAAAAFdG9rZW4AAAAAAAATAAAAAA==",
         "AAAAAAAAADtDaGVjayBpZiBhIHNwZWNpZmljIHRva2VuIGlzIGluIHRoZSBhbGxvd2VkIGZlZSB0b2tlbiBsaXN0LgAAAAAUaXNfZmVlX3Rva2VuX2FsbG93ZWQAAAABAAAAAAAAAAV0b2tlbgAAAAAAABMAAAABAAAAAQ==",
-        "AAAAAAAAAMNCYWNrd2FyZHMtY29tcGF0aWJsZSBlbnRyeSBwb2ludCBtYXRjaGluZyB0aGUgb3JpZ2luYWwgUGF5bWFzdGVyIEFQSS4KClRoaXMgd3JhcHMgYGZvcndhcmQoKWAgd2l0aCBhIHNpbXBsaWZpZWQgaW50ZXJmYWNlIHdoZXJlIHRoZSByZWxheWVyCmFkZHJlc3MgaXMgdGhlIGZlZSByZWNpcGllbnQgYW5kIGZlZV9hbW91bnQgPT0gbWF4X2ZlZS4AAAAAFmNvbGxlY3RfZmVlX2FuZF9pbnZva2UAAAAAAAcAAAAAAAAABHVzZXIAAAATAAAAAAAAAAlmZWVfdG9rZW4AAAAAAAATAAAAAAAAAAdtYXhfZmVlAAAAAAsAAAAAAAAAB3JlbGF5ZXIAAAAAEwAAAAAAAAAPdGFyZ2V0X2NvbnRyYWN0AAAAABMAAAAAAAAADWZ1bmN0aW9uX25hbWUAAAAAAAARAAAAAAAAAARhcmdzAAAD6gAAAAAAAAABAAAAAA==",
+        "AAAAAAAAAbJCYWNrd2FyZHMtY29tcGF0aWJsZSBlbnRyeSBwb2ludCBtYXRjaGluZyB0aGUgb3JpZ2luYWwgUGF5bWFzdGVyIEFQSS4KClRoaXMgd3JhcHMgYGZvcndhcmQoKWAgd2l0aCBhIHNpbXBsaWZpZWQgaW50ZXJmYWNlIHdoZXJlIHRoZSByZWxheWVyCmFkZHJlc3MgaXMgdGhlIGZlZSByZWNpcGllbnQgYW5kIGZlZV9hbW91bnQgPT0gbWF4X2ZlZS4KCiMgTm90ZSBvbiBFeHBpcmF0aW9uCgpUaGlzIHdyYXBwZXIgc2V0cyB0aGUgZXhwaXJhdGlvbiB0byBgY3VycmVudF9sZWRnZXIgKyAxMDAwYCAofjgzIG1pbnV0ZXMKYXQgfjUgc2VjL2xlZGdlcikuIFRoaXMgaXMgTk9UICJubyBleHBpcmF0aW9uIiDigJQgaXQgaXMgYSBnZW5lcm91cyBidXQKZmluaXRlIHdpbmRvdy4gRm9yIGluZGVmaW5pdGUgYXV0aG9yaXphdGlvbiwgdXNlIGBmb3J3YXJkKClgIGRpcmVjdGx5LgAAAAAAFmNvbGxlY3RfZmVlX2FuZF9pbnZva2UAAAAAAAcAAAAAAAAABHVzZXIAAAATAAAAAAAAAAlmZWVfdG9rZW4AAAAAAAATAAAAAAAAAAdtYXhfZmVlAAAAAAsAAAAAAAAAB3JlbGF5ZXIAAAAAEwAAAAAAAAAPdGFyZ2V0X2NvbnRyYWN0AAAAABMAAAAAAAAADWZ1bmN0aW9uX25hbWUAAAAAAAARAAAAAAAAAARhcmdzAAAD6gAAAAAAAAABAAAAAA==",
         "AAAABQAAADZFdmVudCBlbWl0dGVkIHdoZW4gdG9rZW5zIGFyZSBzd2VwdCBmcm9tIHRoZSBjb250cmFjdC4AAAAAAAAAAAALVG9rZW5zU3dlcHQAAAAAAQAAAAx0b2tlbnNfc3dlcHQAAAADAAAAAAAAAAV0b2tlbgAAAAAAABMAAAABAAAAAAAAAAlyZWNpcGllbnQAAAAAAAATAAAAAQAAAAAAAAAGYW1vdW50AAAAAAALAAAAAAAAAAI=",
         "AAAABQAAADJFdmVudCBlbWl0dGVkIHdoZW4gYSBmZWUgaXMgY29sbGVjdGVkIGZyb20gYSB1c2VyLgAAAAAAAAAAAAxGZWVDb2xsZWN0ZWQAAAABAAAADWZlZV9jb2xsZWN0ZWQAAAAAAAAEAAAAAAAAAAR1c2VyAAAAEwAAAAEAAAAAAAAACXJlY2lwaWVudAAAAAAAABMAAAABAAAAAAAAAAV0b2tlbgAAAAAAABMAAAAAAAAAAAAAAAZhbW91bnQAAAAAAAsAAAAAAAAAAg==",
         "AAAABQAAADxFdmVudCBlbWl0dGVkIHdoZW4gYSBjYWxsIGlzIGZvcndhcmRlZCB0byBhIHRhcmdldCBjb250cmFjdC4AAAAAAAAAD0ZvcndhcmRFeGVjdXRlZAAAAAABAAAAEGZvcndhcmRfZXhlY3V0ZWQAAAAEAAAAAAAAAAR1c2VyAAAAEwAAAAEAAAAAAAAAD3RhcmdldF9jb250cmFjdAAAAAATAAAAAQAAAAAAAAAJdGFyZ2V0X2ZuAAAAAAAAEQAAAAAAAAAAAAAAC3RhcmdldF9hcmdzAAAAA+oAAAAAAAAAAAAAAAI=",