Update the WAAS client and rename the SDK to OMS Wallet (#15)

* Update the C SDK for the latest WAAS wallet client

* Refresh docs for the latest WAAS wallet flow

* Clean up stale WAAS flow docs

* Rename the SDK surface to OMS Wallet

* Harden session restore and persistence semantics

Author: tolgahan-arikan

.github/workflows/linux-tests.yml

@@ -33,7 +33,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Configure
-        run: cmake -S . -B build -DSEQUENCE_BUILD_DEMO=OFF -DSEQUENCE_BUILD_CLI=OFF
+        run: cmake -S . -B build -DOMS_WALLET_BUILD_DEMO=OFF -DOMS_WALLET_BUILD_CLI=OFF
 
       - name: Build
         run: cmake --build build

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.20)
-project(sequence-c-sdk C)
+project(oms_wallet_c_sdk C)
 
 set(CMAKE_C_STANDARD 99)
 
@@ -13,19 +13,19 @@ pkg_check_modules(SECP256K1 REQUIRED libsecp256k1)
 pkg_check_modules(CJSON REQUIRED IMPORTED_TARGET libcjson)
 link_directories(${SECP256K1_LIBRARY_DIRS})
 
-option(SEQUENCE_BUILD_DEMO "Build demo target" ON)
-option(SEQUENCE_BUILD_CLI "Build CLI target" ON)
+option(OMS_WALLET_BUILD_DEMO "Build demo target" ON)
+option(OMS_WALLET_BUILD_CLI "Build CLI target" ON)
 
 # ---- Library ----
 
-set(SEQUENCE_SDK_SOURCES
+set(OMS_WALLET_SDK_SOURCES
         lib/generated/waas/waas.gen.c
-        lib/runtime/sequence_runtime.c
-        lib/wallet/sequence_auth.c
-        lib/wallet/sequence_config.c
-        lib/wallet/sequence_request_signing.c
-        lib/wallet/sequence_wallet_ops.c
-        lib/wallet/sequence_wallet_shared.c
+        lib/runtime/oms_wallet_runtime.c
+        lib/wallet/oms_wallet_auth.c
+        lib/wallet/oms_wallet_config.c
+        lib/wallet/oms_wallet_request_signing.c
+        lib/wallet/oms_wallet_ops.c
+        lib/wallet/oms_wallet_shared.c
         lib/networking/http_client.c
         lib/networking/http_client_common.c
         lib/infrastructure/is_valid_message_signature.c
@@ -37,109 +37,113 @@ set(SEQUENCE_SDK_SOURCES
         lib/evm/keccak256.c
         lib/evm/sign_message.c
         lib/utils/byte_utils.c
+        lib/utils/base64url.c
         lib/utils/globals.c
         lib/utils/hex_utils.c
+        lib/utils/sha256.c
         lib/utils/string_utils.c
         lib/utils/timestamps.c
         lib/utils/uuid.c
 )
 
 if(APPLE)
-    list(APPEND SEQUENCE_SDK_SOURCES
+    list(APPEND OMS_WALLET_SDK_SOURCES
             lib/storage/secure_storage.c
     )
 elseif(UNIX)
-    list(APPEND SEQUENCE_SDK_SOURCES
+    list(APPEND OMS_WALLET_SDK_SOURCES
             lib/storage/secure_storage_posix.c
     )
 else()
-    message(FATAL_ERROR "sequence-c-sdk currently supports macOS and Linux only")
+    message(FATAL_ERROR "oms-wallet-c-sdk currently supports macOS and Linux only")
 endif()
 
-add_library(sequence_c_sdk ${SEQUENCE_SDK_SOURCES})
+add_library(oms_wallet_c_sdk ${OMS_WALLET_SDK_SOURCES})
 
-target_include_directories(sequence_c_sdk
+target_include_directories(oms_wallet_c_sdk
         PUBLIC
         $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/lib>
-        $<INSTALL_INTERFACE:include>
+        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/oms-wallet>
         ${SECP256K1_INCLUDE_DIRS}
         ${CJSON_INCLUDE_DIRS}
 )
 
-target_compile_options(sequence_c_sdk PUBLIC
+target_compile_options(oms_wallet_c_sdk PUBLIC
         ${SECP256K1_CFLAGS_OTHER}
         ${CJSON_CFLAGS_OTHER}
 )
 
-target_link_libraries(sequence_c_sdk PUBLIC
+target_link_libraries(oms_wallet_c_sdk PUBLIC
         CURL::libcurl
         PkgConfig::CJSON
         ${SECP256K1_LIBRARIES}
 )
 
 # macOS frameworks
 if(APPLE)
-    target_link_libraries(sequence_c_sdk PUBLIC
+    target_link_libraries(oms_wallet_c_sdk PUBLIC
             "-framework Security"
             "-framework CoreFoundation"
     )
 endif()
 
 # ---- Demo ----
 
-set(SEQUENCE_RUNTIME_TARGETS "")
+set(OMS_WALLET_RUNTIME_TARGETS "")
 
-if(SEQUENCE_BUILD_DEMO)
-    add_executable(sequence-demo demo.c)
-    target_link_libraries(sequence-demo PRIVATE sequence_c_sdk)
-    list(APPEND SEQUENCE_RUNTIME_TARGETS sequence-demo)
+if(OMS_WALLET_BUILD_DEMO)
+    add_executable(oms_wallet_demo demo.c)
+    target_link_libraries(oms_wallet_demo PRIVATE oms_wallet_c_sdk)
+    set_target_properties(oms_wallet_demo PROPERTIES OUTPUT_NAME "oms-wallet-demo")
+    list(APPEND OMS_WALLET_RUNTIME_TARGETS oms_wallet_demo)
 endif()
 
 # ---- CLI ----
 
-if(SEQUENCE_BUILD_CLI)
-    add_executable(sequence-wallet cli.c)
-    target_link_libraries(sequence-wallet PRIVATE sequence_c_sdk)
-    list(APPEND SEQUENCE_RUNTIME_TARGETS sequence-wallet)
+if(OMS_WALLET_BUILD_CLI)
+    add_executable(oms_wallet_cli cli.c)
+    target_link_libraries(oms_wallet_cli PRIVATE oms_wallet_c_sdk)
+    set_target_properties(oms_wallet_cli PROPERTIES OUTPUT_NAME "oms-wallet")
+    list(APPEND OMS_WALLET_RUNTIME_TARGETS oms_wallet_cli)
 endif()
 
 # ---- Install ----
 
-install(TARGETS sequence_c_sdk
-        EXPORT sequence-c-sdk-targets
+install(TARGETS oms_wallet_c_sdk
+        EXPORT oms-wallet-c-sdk-targets
         LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
         ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
 
-if(SEQUENCE_RUNTIME_TARGETS)
-    install(TARGETS ${SEQUENCE_RUNTIME_TARGETS}
+if(OMS_WALLET_RUNTIME_TARGETS)
+    install(TARGETS ${OMS_WALLET_RUNTIME_TARGETS}
             RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
 endif()
 
 install(DIRECTORY lib/
-        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/sequence
+        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/oms-wallet
         FILES_MATCHING PATTERN "*.h"
-        PATTERN "sequence_wallet_internal.h" EXCLUDE)
+        PATTERN "oms_wallet_internal.h" EXCLUDE)
 
-install(EXPORT sequence-c-sdk-targets
-        FILE sequence-c-sdk-targets.cmake
-        NAMESPACE sequence::
-        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/sequence-c-sdk)
+install(EXPORT oms-wallet-c-sdk-targets
+        FILE oms-wallet-c-sdk-targets.cmake
+        NAMESPACE oms_wallet::
+        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/oms-wallet-c-sdk)
 
 if(BUILD_TESTING)
-    add_executable(sequence_request_signing_test
-            tests/sequence_request_signing_test.c)
-    target_link_libraries(sequence_request_signing_test PRIVATE sequence_c_sdk)
-    add_test(NAME sequence_request_signing_test COMMAND sequence_request_signing_test)
+    add_executable(oms_wallet_request_signing_test
+            tests/oms_wallet_request_signing_test.c)
+    target_link_libraries(oms_wallet_request_signing_test PRIVATE oms_wallet_c_sdk)
+    add_test(NAME oms_wallet_request_signing_test COMMAND oms_wallet_request_signing_test)
 
     add_executable(timestamps_test
             tests/timestamps_test.c)
-    target_link_libraries(timestamps_test PRIVATE sequence_c_sdk)
+    target_link_libraries(timestamps_test PRIVATE oms_wallet_c_sdk)
     add_test(NAME timestamps_test COMMAND timestamps_test)
 
     if(UNIX AND NOT APPLE)
         add_executable(secure_storage_test
                 tests/secure_storage_test.c)
-        target_link_libraries(secure_storage_test PRIVATE sequence_c_sdk)
+        target_link_libraries(secure_storage_test PRIVATE oms_wallet_c_sdk)
         add_test(NAME secure_storage_test COMMAND secure_storage_test)
     endif()
 endif()

Formula/wallet.rb

@@ -1,5 +1,5 @@
 class Wallet < Formula
-  desc "Sequence C SDK"
+  desc "OmsWallet C SDK"
   homepage "https://github.com/0xsequence/c-sdk"
   url "https://github.com/0xsequence/c-sdk/archive/refs/tags/v0.3.0.tar.gz"
   sha256 "e4949620a97b2952ec774280df2344c5a047d4e96a19c8019f96e9a0c365996c"
@@ -18,6 +18,6 @@ def install
 
   test do
     # Basic smoke test
-    assert_match "Usage", shell_output("#{bin}/sequence-wallet --help")
+    assert_match "Usage", shell_output("#{bin}/oms-wallet --help")
   end
 end

README.md

@@ -1,4 +1,4 @@
-# Sequence C SDK
+# OmsWallet C SDK
 
 ## Support Matrix
 
@@ -36,39 +36,47 @@ cmake --build build
 Optional targets:
 
 ```shell
-cmake -S . -B build -DSEQUENCE_BUILD_DEMO=OFF -DSEQUENCE_BUILD_CLI=OFF
+cmake -S . -B build -DOMS_WALLET_BUILD_DEMO=OFF -DOMS_WALLET_BUILD_CLI=OFF
 ```
 
-`SEQUENCE_BUILD_DEMO` and `SEQUENCE_BUILD_CLI` only control those runtime
+`OMS_WALLET_BUILD_DEMO` and `OMS_WALLET_BUILD_CLI` only control those runtime
 binaries. They do not disable the library or the test targets.
 
 ## Initialization
 
-Call `sequence_config_init(...)` before using wallet, indexer, or API helpers.
+Call `oms_wallet_config_init(...)` before using wallet, indexer, or API helpers.
 The SDK no longer falls back to built-in runtime URLs when config is unset.
 
 Minimal setup:
 
 ```c
-#include "wallet/sequence_config.h"
+#include <wallet/oms_wallet_config.h>
 
-if (sequence_config_init("YOUR_ACCESS_KEY") != 0) {
+if (oms_wallet_config_init("YOUR_ACCESS_KEY") != 0) {
     /* handle config initialization failure */
 }
 ```
 
 Common overrides:
 
 ```c
-sequence_config_set_indexer_url_template("https://dev-{value}-indexer.sequence.app/rpc/Indexer/");
-sequence_config_set_api_rpc_url("https://dev-api.sequence.app/rpc/API");
-sequence_config_set_wallet_rpc_url("https://your-wallet-host/rpc/Wallet");
-sequence_config_set_wallet_auth_scope("@1:test");
-sequence_config_set_origin_header("Origin: http://localhost:3000");
-sequence_config_set_storage_dir("/var/lib/sequence-c-sdk");
+oms_wallet_config_set_indexer_url_template("https://dev-{value}-indexer.sequence.app/rpc/Indexer/");
+oms_wallet_config_set_api_rpc_url("https://dev-api.sequence.app/rpc/API");
+oms_wallet_config_set_wallet_rpc_url("https://your-wallet-host/rpc/Wallet");
+oms_wallet_config_set_origin_header("Origin: http://localhost:3000");
+oms_wallet_config_set_storage_dir("/var/lib/oms-wallet-c-sdk");
 ```
 
-Call `sequence_config_cleanup()` when you are done with SDK-owned config state.
+The default wallet auth scope is `proj_1`. Only override it if your environment
+requires a different scope.
+
+Call `oms_wallet_config_cleanup()` when you are done with SDK-owned config state.
+
+`oms_wallet_restore_session()` returns:
+
+- `1` when a usable saved session was restored
+- `0` when no usable saved session exists yet
+- `-1` on an actual storage or restore failure
 
 ## Linux Secure Storage
 
@@ -78,73 +86,81 @@ On Linux, secure storage uses a file-per-key backend with:
 - file permissions: `0600`
 - atomic replace on write
 
+This Linux backend is permission-protected filesystem storage. It is not
+encrypted at rest like macOS Keychain storage.
+
 Default storage path:
 
-- `$HOME/.sequence-c-sdk` when `HOME` is set
-- `./.sequence-c-sdk` otherwise
+- `$HOME/.oms-wallet-c-sdk` when `HOME` is set
+- `./.oms-wallet-c-sdk` otherwise
 
 Override the storage location with:
 
 ```c
-sequence_config_set_storage_dir("/path/to/app-state");
+oms_wallet_config_set_storage_dir("/path/to/app-state");
 ```
 
-#### Temporary generated-client patch
-
-The vendored generated WAAS C client currently includes a small local
-compatibility patch in `lib/generated/waas/waas.gen.c` to tolerate a missing
-`iss` field in the live `CompleteAuth` response.
+Persisted keys used by the SDK:
 
-This is temporary and should be removed once the WAAS API contract is updated
-or fixed upstream.
+- `access-key`: CLI-stored access key used to initialize SDK config
+- `seckey`: signer private key for the current session
+- `challenge`: pending email sign-in challenge
+- `verifier`: pending email sign-in verifier
+- `oms_wallet_id`: selected wallet id for follow-up wallet operations
+- `oms_wallet_address`: last selected wallet address
 
 #### Run tests
 
 ```shell
 ctest --test-dir build --output-on-failure
 
 # Focused request-signing parity test
-./build/sequence_request_signing_test
+./build/oms_wallet_request_signing_test
 ```
 
 Current test coverage:
 
-- `sequence_request_signing_test`: validates canonical request payloads, preimages, digests, signatures, and authorization headers against checked-in vectors
+- `oms_wallet_request_signing_test`: validates canonical request payloads, preimages, digests, signatures, and authorization headers against checked-in vectors
 - `timestamps_test`: validates nonce monotonicity from `timestamp_next_nonce()`
+- `secure_storage_test`: Linux-only regression test for the POSIX secure-storage backend
 
 #### Run the demo or cli
 
 ```shell
-./build/sequence-demo
+./build/oms-wallet-demo
 ```
 
 ```shell
 # Init
-./build/sequence-wallet init --access-key AQAAAAAAAAK2JvvZhWqZ51riasWBftkrVXE
+./build/oms-wallet init --access-key AQAAAAAAAAK2JvvZhWqZ51riasWBftkrVXE
 
 # Get token balances
-./build/sequence-wallet get-token-balances --chain-id 137 --contract-address 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 --wallet-address 0x8e3E38fe7367dd3b52D1e281E4e8400447C8d8B9 --include-metadata
+./build/oms-wallet get-token-balances --chain-id 137 --contract-address 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 --wallet-address 0x8e3E38fe7367dd3b52D1e281E4e8400447C8d8B9 --include-metadata
 
 # Sign in with Email
-./build/sequence-wallet sign-in-with-email --email andygruening@gmail.com
+./build/oms-wallet sign-in-with-email --email andygruening@gmail.com
+
+# Confirm Email sign in and automatically select the first matching wallet,
+# or create one if none exists for that type
+./build/oms-wallet confirm-email-sign-in --code 123456 --wallet-type ethereum
 
-# Confirm Email sign in
-./build/sequence-wallet confirm-email-sign-in --code 123456 --wallet-type Ethereum_EOA
+# Or, omit --wallet-type to list the available wallets returned by CompleteAuth
+./build/oms-wallet confirm-email-sign-in --code 123456
 
-# Use wallet
-./build/sequence-wallet use-wallet --wallet-type Ethereum_EOA
+# Optional: switch to a specific wallet later
+./build/oms-wallet use-wallet --wallet-id <wallet-id>
 
-# Create wallet
-./build/sequence-wallet create-wallet
+# Optional: create an additional wallet of the default type (ethereum)
+./build/oms-wallet create-wallet
 
 # Sign message
-./build/sequence-wallet sign-message --chain-id 80002 --message test
+./build/oms-wallet sign-message --chain-id 80002 --message test
 
 # Verify signature
-./build/sequence-wallet verify-signature --chain-id 80002 --wallet-address 0xb7461CcfFfc7378747C6f82804E4dEc04b9E6148 --message test --signature 0x...
+./build/oms-wallet verify-signature --chain-id 80002 --wallet-address 0xb7461CcfFfc7378747C6f82804E4dEc04b9E6148 --message test --signature 0x...
 
 # Send transaction
-./build/sequence-wallet send-transaction --chain-id 80002 --to 0xE5E8B483FfC05967FcFed58cc98D053265af6D99 --value 0
+./build/oms-wallet send-transaction --chain-id 80002 --to 0xE5E8B483FfC05967FcFed58cc98D053265af6D99 --value 0
 ```
 
 #### Homebrew version release