Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
284 commits
Select commit Hold shift + click to select a range
4a0eb3b
Revert "fix: solve trezor signing bug"
Jul 31, 2025
448133f
get proper abi to check for nft metadata
Jul 31, 2025
4fdd033
Update package.json
Jul 31, 2025
7752518
update utils version
Jul 31, 2025
b40d750
update from eth-sig-util to @metamask/eth-sig-util
Aug 1, 2025
ea6248b
rm global ethers packages
Aug 3, 2025
3d19763
update ethers packages
Aug 3, 2025
adfd37e
reject invalid private keys based on network type
Aug 3, 2025
0b5cf24
fix: bypass wrong validation for hardware wallets
lucasgabrielgsp Aug 4, 2025
df8bd1a
rm deprecated sendtransaction and add hw support for speedup/cancel
Aug 4, 2025
62723dc
fix: adjust speed/cancel txs for hw wallets
lucasgabrielgsp Aug 4, 2025
e6bc214
chore: merge changes
lucasgabrielgsp Aug 4, 2025
9ba71ca
set legacy type so ethers doesnt override it for legacy sends
Aug 5, 2025
c2e89ee
send/cancel fix for gas prices if not set or 0
Aug 5, 2025
ac2a585
use fallback if tx doesnt exist from provider
Aug 5, 2025
443e1f7
fix potential precision issues with amounts/balances
Aug 6, 2025
72b10d4
fix psbt unknownKeyVals key lookup
Aug 7, 2025
632e9e2
fix sending odd decimal amounts, resolve based on provided decimals n…
Aug 8, 2025
f72b297
speedup reliability and error codes
Aug 11, 2025
acdc443
feat: add support for utxo networks with ledger
lucasgabrielgsp Aug 13, 2025
94d4028
chore: merge changes
lucasgabrielgsp Aug 13, 2025
cfb90e8
add cancellation checks and ledger display true fallback, add wallet …
Aug 13, 2025
8d89f49
feat: use internal UTXO client to handle UTXO networks
lucasgabrielgsp Aug 13, 2025
7b749dd
chore: merge changes
lucasgabrielgsp Aug 13, 2025
1cd2b7d
convertExtendedKeyVersion + fix fromBase58
Aug 13, 2025
700e447
enhance convertToLedgerFormat to add derivations for change/outputs
Aug 13, 2025
8ae72e4
log any missing derivation paths on inputs and outputs
Aug 13, 2025
1a418c6
use device friendly xpub format in signpsbt
Aug 13, 2025
947b785
add wif import support for utxo
Aug 21, 2025
2a1d872
update sjs lib
Aug 21, 2025
d864f46
add watch only utxo support
Aug 22, 2025
84cdd52
direct BB validation + update sjs lib
Aug 22, 2025
c0eaf25
add std seed word lengths
Aug 23, 2025
c3316d8
clamp utxo fee to 1 to ensure rounding issues wont prevent sends on t…
Aug 26, 2025
c0ebe97
add support for importing legacy utxo address types
Aug 27, 2025
19c72e3
rm network labels from default labels for import/watch-only accounts
Aug 27, 2025
f46ec84
update to latest bjs lib and add taproot support
Aug 27, 2025
266e3c1
use sjs bip84, rm bip39/84 bs58check from dependencies
Aug 27, 2025
3b89eb0
rm depenenceis from utils
Aug 27, 2025
653ff53
update sjs lib
Aug 27, 2025
40f523b
fix signers (readonly for hw and proper signer for creating psbts for…
Aug 28, 2025
05faa94
update sjs lib
Aug 28, 2025
ef97827
update sjs lib
Aug 28, 2025
f4c7539
update sjs lib
Aug 28, 2025
391c1f8
rm unused dependencies and factor out descriptors
Aug 29, 2025
8b98fd3
fix wif import test
Aug 29, 2025
d3163fc
rm zksync ethers provider
Aug 29, 2025
c2c48d1
omit legacy tx fields if sending non legacy txs
Aug 29, 2025
0e37df6
always import address index 0 for hw accounts
Aug 30, 2025
72b10d9
fix ledger conversion checking for path in derivation properly
Sep 1, 2025
99873a9
clean up input path checks
Sep 1, 2025
07d8ec2
Update package.json
Sep 1, 2025
413e1c5
only use bitcoinjs for typing but use embedded one from sjs lib for c…
Sep 1, 2025
32cdc58
fix prevhash hex string issue
Sep 1, 2025
6e72b15
use sjs finalize psbt helper instead of custom validator in trezor si…
Sep 1, 2025
81b62b2
update btc test bb
Sep 2, 2025
4cc1363
add psbt typings
Sep 2, 2025
83ffec6
update versions
Sep 2, 2025
3dc524f
fix fromBitcoinJS to allow string/buffer input
Sep 2, 2025
5aa1232
resolve networks re: testnet for psbt conversions
Sep 2, 2025
f3b6ce4
fix external psbt wrapping typing confusion + fromPali fix
Sep 2, 2025
6a98ff5
Update package.json
Sep 2, 2025
f35ce2a
use paytowitness for both p2wpkh and p2wsh outputs
Sep 2, 2025
76ea2e7
update ledger-bitcoin code
Sep 2, 2025
16ef984
pass errors up on connect to hw
Sep 3, 2025
9c139a5
await hw destroys on lock
Sep 4, 2025
7b16b61
chore: merge changes from main
lucasgabrielgsp Sep 10, 2025
a2ba45d
generic verifyUtxoAddress for ledger/trezor
Sep 11, 2025
1555f74
Revert "chore: merge changes from main"
lucasgabrielgsp Sep 12, 2025
772a4b7
Merge branch 'main' of https://github.com/sidhujag/sysweb3
Sep 12, 2025
54e3ed5
use correct xpub extended key version bytes for ledger, avoid dbl con…
Sep 12, 2025
03221ff
fix: use named policy
lucasgabrielgsp Sep 19, 2025
46c098f
Update package.json
Sep 25, 2025
c173343
fix: add zksync support to getting fees correctly
lucasgabrielgsp Oct 6, 2025
16758f5
1.0.564
Oct 14, 2025
a742a37
fix: solve ledger connection across networks
lucasgabrielgsp Oct 22, 2025
e356d61
Merge branch 'main' of https://github.com/sidhujag/sysweb3
lucasgabrielgsp Oct 22, 2025
a089723
update version of keyring to 1.0.565
Oct 22, 2025
2796048
fix 001, 007
Dec 29, 2025
6ab4b69
refactor(ledger): remove excessive debug logging from PSBT enrichment
guilhermefleury Dec 29, 2025
97a3006
rm hash from vault storage, use aes-gcm for blob storage
Dec 30, 2025
9fbb26c
use default wallet policy instead of custom HMAC for ledger
Dec 30, 2025
6c3cf80
Update package.json
Dec 30, 2025
f942eb0
go back to wallet policy as it was
Dec 31, 2025
ffa2577
harden web3 provider singleton to check network state and recreate
Dec 31, 2025
7f39c15
Update package.json
Dec 31, 2025
e902bb1
handle max send when sending tx
Dec 31, 2025
84caffa
dont block evm signer from being set of xpub is missing
Dec 31, 2025
b08edb2
Update package.json
Dec 31, 2025
b497151
Revert "handle max send when sending tx"
Dec 31, 2025
1ad4272
Update package.json
Dec 31, 2025
8287885
update dependences include kdf to 900k
Jan 16, 2026
dae621b
Fix imported zpub signing and remove zkSync handling
May 27, 2026
f91fc36
Merge pull request #3 from sidhujag/keyring-zpub-zksync-cleanup
sidhujag May 27, 2026
955d013
Update yarn.lock
May 27, 2026
642f17b
feat(keyring): add passkey smart account metadata
May 31, 2026
63a5a8d
fix(keyring): reject duplicate passkey accounts
May 31, 2026
50f3bf4
fix(keyring): include passkeys in duplicate checks
May 31, 2026
5b87330
Merge pull request #4 from sidhujag/feat/passkey-smart-account-keyring
sidhujag May 31, 2026
f1a752e
rm rec id
Jun 4, 2026
ed8081d
fix(keyring): drop passkey sponsor URL hash type
Jun 3, 2026
4498888
createSmartAccount
Jun 7, 2026
8bbac7a
update types
Jun 7, 2026
d77d20c
perf(keyring,utils): reduce Blockbook round trips in UTXO flows
Jun 10, 2026
15ba687
v1.0.592 keyring + v1.1.273 utils
Jun 10, 2026
04de856
Merge pull request #5 from sidhujag/perf/utxo-blockbook-call-reduction
sidhujag Jun 10, 2026
00c91cf
fix(keyring): preserve JSON-RPC error code and revert data on provide…
Jun 12, 2026
4beff5c
Merge pull request #6 from sidhujag/fix/preserve-jsonrpc-error-data
sidhujag Jun 12, 2026
fee7f5b
feat(keyring): add SLH-DSA setup secret support
Jun 17, 2026
cbdda9e
Merge pull request #7 from sidhujag/jardin-fors-replace-slh
sidhujag Jun 17, 2026
1dfb846
fix(keyring): avoid default gas limit floor
Jun 30, 2026
e4c5de7
fix(keyring): keep calldata gas fallback conservative
Jun 30, 2026
b7ad21e
fix test/update packages
Jun 30, 2026
135ef6d
Merge pull request #8 from sidhujag/fix/estimate-gas-without-default-…
sidhujag Jun 30, 2026
34f103b
Migrate EVM signing to ethers v6
Jul 4, 2026
528eb91
Address ethers v6 review findings
Jul 4, 2026
7bc031b
Fix EIP-155 signature and zero-decimal token handling
Jul 4, 2026
fecbb39
Address remaining ethers v6 review findings
Jul 4, 2026
baea992
Fix local EVM fee and token amount handling
Jul 4, 2026
93e2220
Address access list and ABI encoding review
Jul 4, 2026
f1f00e4
Populate gas price for type one EVM sends
Jul 4, 2026
9378f43
Avoid redefining EVM transaction response fields
Jul 4, 2026
f7cbb72
Preserve wrapped EVM response fields
Jul 4, 2026
1fe1424
Use cached raw hex for personal sign decoding
Jul 4, 2026
5d36cac
Serialize compat BigNumbers as JSON
Jul 4, 2026
0a43105
Normalize EVM token overrides for ethers v6
Jul 4, 2026
47dc416
Normalize EVM transaction type values
Jul 4, 2026
197a692
Reject malformed EVM private key hex
Jul 4, 2026
91f0905
Normalize token metadata integer results
Jul 4, 2026
878967f
Preserve token balances and call block tags
Jul 4, 2026
cb28eb1
Attach blockTag to provider call requests
Jul 4, 2026
fb914b4
Use super call for normalized provider requests
Jul 4, 2026
222ede4
Restore provider call spy safely
Jul 4, 2026
ebefc63
Wrap provider responses and zero base fees
Jul 4, 2026
66c28a9
Preserve ERC1155 balances exactly
Jul 4, 2026
adebc72
Forward block tags for balance requests
Jul 4, 2026
c3a0311
Resolve named EVM recipients locally
Jul 4, 2026
260c470
Reject unsafe numeric transaction values
Jul 4, 2026
3f573b6
update sjs lib
Jul 4, 2026
2d40cb5
Merge pull request #9 from sidhujag/chore/ethers-v6-keyring-migration
sidhujag Jul 5, 2026
2a96c7a
perf(keyring): reduce provider RPC fanout
Jul 5, 2026
822771a
chore(keyring): import ethers from exported subpaths
Jul 5, 2026
b53a4c3
chore: use ethers package exports across runtime packages
Jul 5, 2026
b72afb5
keyring v1.0.604
Jul 5, 2026
2145fdf
Revert "keyring v1.0.604"
Jul 5, 2026
d8894a8
Revert "chore: use ethers package exports across runtime packages"
Jul 5, 2026
087d2e1
Revert "chore(keyring): import ethers from exported subpaths"
Jul 5, 2026
d92ac5e
Reapply "chore(keyring): import ethers from exported subpaths"
Jul 5, 2026
149ac33
Reapply "chore: use ethers package exports across runtime packages"
Jul 5, 2026
6d1cc40
Reapply "keyring v1.0.604"
Jul 5, 2026
7d43850
fix getAddress
Jul 5, 2026
f8bb709
fix(keyring): verify static provider chain id
Jul 5, 2026
7a03e2f
fix(keyring): refresh static provider chain check
Jul 5, 2026
26dad76
fix(keyring): update local signer provider test doubles
Jul 5, 2026
1649179
Merge pull request #10 from sidhujag/perf/provider-rpc-call-reduction
sidhujag Jul 5, 2026
4ef7dab
Update package.json
Jul 5, 2026
231bba4
fix(keyring): harden EVM transaction fee handling
Jul 5, 2026
bd12e9e
Revert "fix(keyring): harden EVM transaction fee handling"
Jul 5, 2026
8cb2515
fix(keyring): harden EVM transaction fee handling
Jul 5, 2026
9ca540d
fix(keyring): default token fee params before signing
Jul 5, 2026
b3108ac
fix(keyring): preserve zero priority fee overrides
Jul 5, 2026
df10bed
fix(keyring): clean formatted transaction estimation
Jul 5, 2026
bdc8d4c
fix(keyring): clear type for legacy gas estimates
Jul 5, 2026
4da9adf
Merge pull request #11 from sidhujag/fix/evm-tx-v6-boundaries
sidhujag Jul 5, 2026
eb6bcfa
keyring v1.0.607
Jul 5, 2026
58d300d
fix(keyring): bump cancel replacements from network fees
Jul 5, 2026
2209a45
fix(keyring): preserve nonzero priority fee floor
Jul 5, 2026
6ca05d7
Merge pull request #12 from sidhujag/fix/cancel-replacement-fees
sidhujag Jul 5, 2026
bd1c46d
Update package.json
Jul 5, 2026
60b55fd
fix 1155 sends
Jul 6, 2026
84bf274
chore: require syscoinjs-lib 1.0.273
sidhujag Aug 6, 2026
fbbb71e
build: pin TypeScript 5 for utils
sidhujag Aug 6, 2026
4ba44cf
chore: require sysweb3-utils 1.1.278
sidhujag Aug 6, 2026
c6a8f15
Merge pull request #13 from sidhujag/codex/bump-syscoinjs-lib-1-0-273
sidhujag Aug 6, 2026
fbb4762
fix(keyring): return pending EVM broadcast response
sidhujag Oct 5, 2026
4324011
Merge pull request #14 from sidhujag/codex/fix-pending-evm-send-response
sidhujag Oct 5, 2026
27e4409
fix(keyring): distinguish unlock authentication and operational failures
sidhujag Oct 9, 2026
6cee9a8
test(keyring): cover malformed vaults and post-authentication failures
sidhujag Oct 9, 2026
15dd94f
fix(keyring): preserve secrets through interrupted legacy migration
sidhujag Oct 9, 2026
7f80edd
fix(keyring): classify EVM failures at the broadcast boundary
sidhujag Oct 9, 2026
5e253bf
fix(keyring): resume CBC migration after interrupted metadata writes
sidhujag Oct 9, 2026
8d049c8
Merge pull request #15 from sidhujag/codex/keyring-unlock-error-class…
sidhujag Oct 9, 2026
16baa93
Harden vault persistence and account-scoped hardware signing
sidhujag Oct 9, 2026
b91367e
Use real PSBT fixtures for signing return validation
sidhujag Oct 9, 2026
7eba1e9
Commit fresh vault records together and preserve joint PSBT signing
sidhujag Oct 9, 2026
1f6b576
Use an empty store for fresh-vault initialization fixture
sidhujag Oct 9, 2026
51a998a
Refuse fresh initialization over existing wallet records
sidhujag Oct 9, 2026
9fc8bad
Document safe initialization and persistent secret handling
sidhujag Oct 9, 2026
4c3a61c
Preserve finalized external inputs during hardware signing
sidhujag Oct 9, 2026
b919dc9
Document finalized external hardware input handling
sidhujag Oct 9, 2026
2a0f9bc
Serialize fresh vault creation across extension contexts
sidhujag Oct 9, 2026
3e67528
Preserve key-path Taproot signing with omitted internal keys
sidhujag Oct 9, 2026
98568a5
Skip unnecessary Ledger lookups for finalized witness inputs
sidhujag Oct 9, 2026
2a57510
Reject script-path metadata in inferred Taproot key paths
sidhujag Oct 9, 2026
cf0966d
Merge pull request #16 from sidhujag/codex/crypto-storage-trezor-hard…
sidhujag Oct 9, 2026
073bbe2
Pin package-local TypeScript for standalone builds
sidhujag Oct 9, 2026
5cb3ecb
Authenticate and cap EVM replacement signing in keyring
sidhujag Oct 11, 2026
ce8b194
Enable Trezor Suite flow and verify current Ledger connections
sidhujag Oct 11, 2026
26b13c3
Merge pull request #17 from sidhujag/codex/authenticated-evm-replacem…
sidhujag Oct 11, 2026
6830bfd
Merge pull request #18 from sidhujag/codex/current-hardware-connect
sidhujag Oct 11, 2026
0f74472
Correlate RPC responses and recover stale read replies once
sidhujag Oct 12, 2026
3a6cc66
Merge pull request #19 from sidhujag/codex/rpc-response-integrity
sidhujag Oct 12, 2026
0663da4
fix(keyring): preserve valid zero-tip EIP-1559 pricing
sidhujag Oct 14, 2026
a67b317
ci(keyring): run standard fee and RPC regressions
sidhujag Oct 14, 2026
272822d
fix(keyring): retain zero-tip cancellation and BigNumberish fees
sidhujag Oct 14, 2026
ebcb70f
fix(keyring): recognize scoped ethers unsupported fee errors
sidhujag Oct 14, 2026
4f91de1
Merge pull request #20 from sidhujag/codex/zero-tip-eip1559
sidhujag Oct 14, 2026
385d00c
chore(keyring): bump release to 1.0.617
sidhujag Oct 14, 2026
eb97e8d
chore(utils): adopt tested SDK dust release
sidhujag Oct 15, 2026
c002fdd
chore(keyring): adopt tested shared dust dependency releases
sidhujag Oct 15, 2026
4ac5e48
fix(keyring): resolve native MAX from one funding snapshot (#21)
sidhujag Oct 16, 2026
fda76b6
fix(keyring): bind EVM approvals to wallet context (#22)
sidhujag Oct 16, 2026
f75624a
feat: add shared Sentry signing and collateral-safe funding (#23)
sidhujag Oct 17, 2026
9c5f8c0
fix(sentry): derive BLS keys from Core-compatible seed input (#24)
sidhujag Oct 17, 2026
a40437f
Add typed legacy governance voting authorization (#25)
sidhujag Oct 17, 2026
6780a39
fix(keyring): bind cancellation to signing context
sidhujag Oct 19, 2026
5ca27b7
fix(keyring): require cancellation context for every caller
sidhujag Oct 19, 2026
4e58c59
Merge pull request #26 from sidhujag/codex/cancel-context-safety
sidhujag Oct 19, 2026
db96abc
fix: authenticate cancellation originals and require host admission (…
sidhujag Oct 20, 2026
7b0c503
fix(network): normalize explorer pathname without changing query values
sidhujag Oct 21, 2026
6c42ac0
Merge pull request #28 from sidhujag/codex/network-explorer-path-norm…
sidhujag Oct 21, 2026
35aec43
fix(keyring): derive concrete watch descriptor receive addresses
sidhujag Oct 21, 2026
127bfb3
test: run watch descriptor regressions in CI
sidhujag Oct 21, 2026
fe9be1d
Merge pull request #29 from sidhujag/codex/watch-descriptor-address
sidhujag Oct 21, 2026
bcd1fc4
Add session-bound encryption for private application records
sidhujag Oct 25, 2026
e0cfa8b
Run private record custody and package build checks in CI
sidhujag Oct 25, 2026
7d301d3
Merge pull request #30 from sidhujag/codex/privacy-note-vault
sidhujag Oct 25, 2026
06b0849
Guard formatted EVM sends at the final signing boundary
sidhujag Oct 25, 2026
ecc5d17
Merge pull request #31 from sidhujag/codex/privacy-signing-guard
sidhujag Oct 25, 2026
e3b7c7c
chore: pin SDK build tooling to Node 26
sidhujag Oct 26, 2026
69f9e8d
Merge pull request #32 from sidhujag/codex/node26-build-runtime
sidhujag Oct 26, 2026
4eeab23
fix: require patched syscoinjs in utils
sidhujag Oct 26, 2026
2bbf7ed
Merge pull request #33 from sidhujag/codex/utils-bitcoin-dependency-f…
sidhujag Oct 26, 2026
4d7735d
fix: require patched Bitcoin dependencies in keyring
sidhujag Oct 26, 2026
6cb2d5b
Merge pull request #34 from sidhujag/codex/keyring-bitcoin-dependency…
sidhujag Oct 26, 2026
09b313b
fix: pin keyring git dependency selector
sidhujag Oct 26, 2026
74542f4
Merge pull request #35 from sidhujag/codex/keyring-eth-object-lock-pin
sidhujag Oct 26, 2026
9ceded8
refactor: isolate vault persistence behind async host storage
sidhujag Nov 3, 2026
94964df
refactor: separate transaction hardware adapters from software core
sidhujag Nov 3, 2026
70ea398
feat: add an isolated software keyring entry
sidhujag Nov 3, 2026
36da909
fix: preserve Pali EVM fee approvals in the shared keyring
sidhujag Nov 3, 2026
825f21d
chore: prepare keyring 1.0.628
sidhujag Nov 3, 2026
304db67
Merge pull request #36 from sidhujag/codex/software-keyring-host
sidhujag Nov 3, 2026
2c8daed
Merge pull request #37 from sidhujag/codex/transaction-hardware-boundary
sidhujag Nov 3, 2026
1036c5d
Merge pull request #38 from sidhujag/codex/software-keyring-entry
sidhujag Nov 3, 2026
21adde0
Merge pull request #39 from sidhujag/codex/evm-approval-source-parity
sidhujag Nov 3, 2026
07bbe00
Merge pull request #40 from sidhujag/codex/keyring-1.0.628
sidhujag Nov 3, 2026
a379bbf
build: omit compiled tests from keyring release
sidhujag Nov 3, 2026
db34141
Merge pull request #41 from sidhujag/codex/keyring-release-files
sidhujag Nov 3, 2026
5e2e065
Migrate Trezor integration to Connect 10 with fenced lifecycle
sidhujag Nov 3, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .eslintrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,11 @@
],
"pathGroups": [
{
"pattern": "@pollum-io/**",
"pattern": "syscoin/**",
"group": "index"
}
],
"pathGroupsExcludedImportTypes": ["@pollum-io/**"],
"pathGroupsExcludedImportTypes": ["syscoin/**"],
"newlines-between": "always",
"alphabetize": {
"order": "asc",
Expand Down
58 changes: 55 additions & 3 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,63 @@ jobs:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '16'
check-latest: true
- run: yarn install
node-version-file: '.nvmrc'
- name: Install pinned Yarn
run: npm install --global yarn@1.22.22 --ignore-scripts
- run: yarn install --frozen-lockfile
- name: Install keyring source-test dependencies
run: |
for package in sysweb3-core sysweb3-network sysweb3-utils sysweb3-keyring; do
yarn --cwd "packages/$package" install --frozen-lockfile --ignore-scripts
done
- run: |
touch .env
echo SEED_LAW_COOK=${{ secrets.SEED_LAW_COOK }} >> .env
echo SEED_PEACE_GLOBE=${{ secrets.SEED_PEACE_GLOBE }} >> .env
echo SEED_SWALLOW_HEALTH=${{ secrets.SEED_SWALLOW_HEALTH }} >> .env
- name: Validate transaction signing and RPC regressions
working-directory: packages/sysweb3-keyring
timeout-minutes: 10
# Existing unit fixtures leave timers/listeners after completion.
# --forceExit retains Jest's failure exit status; it does not skip tests.
run: |
NODE_ENV=test node ../../node_modules/jest/bin/jest.js --config jest.config.js --runInBand --silent --forceExit \
test/unit/transactions/ethereum-fee-data.spec.ts \
test/unit/providers-rpc-integrity.spec.ts \
test/unit/transactions/ethereum-transactions.spec.ts \
test/unit/transactions/ethereum-hardware-context.spec.ts \
test/unit/transactions/ethereum-send-context.spec.ts \
test/unit/transactions/ethereum-submission-boundary.spec.ts \
test/unit/transactions/ethereum-cancellation-identity.spec.ts \
test/unit/transactions/ethereum-cancellation-fee-consent.spec.ts \
test/unit/transactions/evm-local-signer.spec.ts \
test/unit/transactions/ethereum-replacement.spec.ts \
test/unit/transactions/syscoin-transactions.spec.ts \
test/unit/transactions/software-boundary.spec.ts \
test/unit/transactions/native-sweep.spec.ts
- name: Validate network RPC regressions
working-directory: packages/sysweb3-network
run: |
NODE_ENV=test node ../../node_modules/jest/bin/jest.js --config jest.config.js --runInBand --silent
- name: Build keyring and validate vault custody
run: |
node node_modules/typescript/bin/tsc -p packages/sysweb3-keyring/tsconfig.json
cd packages/sysweb3-keyring
# The initialization fixtures retain their existing hardware timers.
# forceExit preserves the test result; it does not skip assertions.
NODE_ENV=test node ../../node_modules/jest/bin/jest.js --config jest.config.js --runInBand --silent --forceExit \
test/unit/storage-core.spec.ts \
test/unit/keyring-manager/software-entry.spec.ts \
test/unit/keyring-manager/initialization.spec.ts \
test/unit/keyring-manager/unlock-errors.spec.ts \
test/unit/keyring-manager/vault-kdf-compatibility.spec.ts \
test/unit/keyring-manager/storage-adapter.spec.ts \
test/unit/keyring-manager/private-records.spec.ts
node test/software-entry-runtime.cjs
- name: Validate watch-only descriptor regressions
working-directory: packages/sysweb3-keyring
run: |
NODE_ENV=test node ../../node_modules/jest/bin/jest.js --config jest.config.js --runInBand --silent \
test/unit/keyring-manager/import-watchonly.spec.ts \
test/unit/keyring-manager/watch-descriptor-lifecycle.spec.ts \
test/unit/utils/watch-descriptor.spec.ts
33 changes: 33 additions & 0 deletions .github/workflows/sentry.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
name: Sentry protocol SDK
on:
pull_request:
paths:
- '.nvmrc'
- 'packages/sysweb3-sentry/**'
- '.github/workflows/sentry.yml'
push:
branches: [master, main]
paths:
- '.nvmrc'
- 'packages/sysweb3-sentry/**'
- '.github/workflows/sentry.yml'
permissions:
contents: read
jobs:
sentry-protocol:
runs-on: ubuntu-latest
timeout-minutes: 10
defaults:
run:
working-directory: packages/sysweb3-sentry
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
- uses: actions/setup-node@v4
with:
node-version-file: '.nvmrc'
cache: npm
cache-dependency-path: packages/sysweb3-sentry/package-lock.json
- run: npm ci --ignore-scripts --workspaces=false
- run: npm test
6 changes: 3 additions & 3 deletions .husky/pre-commit
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# Load nvm if it exists
# Load nvm commands without replacing the caller's selected Node runtime.
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" --no-use

# Now yarn should be able to find node
# Yarn enforces the private repository's development engine requirement.
yarn lint-staged
1 change: 1 addition & 0 deletions .nvmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
26.12.1
269 changes: 269 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,269 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Building

```bash
# Build all packages
yarn build

# Build specific package
cd packages/sysweb3-core && yarn build
cd packages/sysweb3-keyring && yarn build
cd packages/sysweb3-network && yarn build
cd packages/sysweb3-utils && yarn build
```

### Testing

```bash
# Run all tests
yarn test

# Run tests for specific package
cd packages/sysweb3-keyring && yarn test

# Run specific test file
yarn test keyring-manager.spec.ts

# Run tests in watch mode
yarn test --watch

# Run tests with coverage
yarn test --coverage
```

### Linting and Type Checking

```bash
# Run linting
yarn lint
yarn lint:fix # Auto-fix issues

# Type checking
yarn type-check

# Format code
yarn format
```

## Architecture Overview

SysWeb3 is a multi-chain JavaScript/TypeScript library organized as a monorepo with four core packages:

### Package Dependencies

```
sysweb3-network (base layer - no internal deps)
↓
sysweb3-core (depends on network)
↓
sysweb3-utils (depends on network)
↓
sysweb3-keyring (depends on core, network, utils)
```

### Key Architectural Patterns

1. **Multi-Chain Support**: The system supports both UTXO-based chains (Bitcoin, Syscoin) and account-based chains (Ethereum, EVM-compatible). Network switching is handled through the `INetworkType` enum.

2. **HD Wallet Architecture**: Uses BIP32/BIP44/BIP84 standards for hierarchical deterministic wallets. The `SyscoinHDSigner` manages UTXO accounts while Ethereum uses standard derivation paths.

3. **Hardware Wallet Abstraction**: Trezor and Ledger support is abstracted through `TrezorKeyring` and `LedgerKeyring` classes, providing a unified interface.

4. **State Management**: The `KeyringManager` maintains wallet state including accounts, networks, and balances. State persistence is handled through encrypted vault storage.

5. **Network Synchronization**: Critical logic in `shouldUpdateHDSigner()` determines when HD signers need recreation based on network parameter changes (testnet/mainnet, SLIP44, blockbook URL).

### Critical Components

1. **KeyringManager** (`packages/sysweb3-keyring/src/keyring-manager.ts`): Central orchestrator for all wallet operations. Handles account creation, network switching, and transaction signing.

2. **Network RPC Validation** (`packages/sysweb3-network/src/rpc.ts`): Validates both Ethereum and Bitcoin-like RPC endpoints. Critical for ensuring correct network configuration.

3. **Transaction Handlers**: Separate implementations for Syscoin (`SyscoinTransactions`) and Ethereum (`EthereumTransactions`) transaction creation and signing.

4. **Storage Layer** (`packages/sysweb3-keyring/src/storage.ts`): Handles encrypted vault operations for secure key storage.

### Performance Considerations

1. **Balance Fetching**: Only fetch balances for the active account to reduce network calls
2. **HD Signer Caching**: Reuse HD signers when network parameters haven't changed
3. **Parallel Operations**: Use Promise.all for concurrent network requests where possible
4. **Memory Management**: Clean up unused signers when switching networks

### Security Best Practices

1. **Imported Accounts**: Single-address accounts (WIF imports) cannot perform HD operations
2. **Password Validation**: Always validate passwords before sensitive operations
3. **State Isolation**: Proper cleanup in test environments to prevent state contamination
4. **Error Handling**: Never expose sensitive data in error messages

## Common Development Tasks

### Adding a New Network

1. Add network configuration to `packages/sysweb3-network/src/networks.ts`
2. Update chain validation in `packages/sysweb3-network/src/rpc.ts`
3. Add network-specific tests
4. Update TypeScript types if needed

### Debugging Network Issues

1. Check `shouldUpdateHDSigner()` logic for HD signer recreation
2. Verify network parameters (chainId, slip44)
3. Validate RPC endpoint with `validateSysRpc()` or `validateEthRpc()`
4. Check blockbook URL format for UTXO chains

### Testing Hardware Wallets

Hardware wallet tests use mocks by default. See test setup in:

- `packages/sysweb3-keyring/test/__mocks__/ledger-mock.js`
- `packages/sysweb3-keyring/test/__mocks__/trezor-mock.js`

# Multi-Keyring Architecture: Single Active Keyring Model

## Overview

The multi-keyring architecture has been updated to follow a **single active unlocked keyring** model for enhanced security and clean state management.

## Storage Separation by slip44

### Vault Storage

Each keyring now stores its vault data in a slip44-specific location:

- **Syscoin (slip44=57)**: `vault-57`
- **Ethereum (slip44=60)**: `vault-60`
- **Bitcoin (slip44=0)**: `vault-0`
- **Litecoin (slip44=2)**: `vault-2`
- etc.

This ensures complete isolation between different network types. The vault contains:

- `mnemonic`: The encrypted seed phrase (shared across all keyrings from the same seed)

### Global Settings Storage (Managed by Pali)

Settings that are shared across all keyrings are stored separately by Pali's MainController:

- **`global-settings`**: Contains:
- `hasEncryptedVault`: Global vault status (true if any vault exists)
- `advancedSettings`: User preferences shared across all networks
- `coinsList`: Cached token/asset lists
- **`vault-keys`**: Password hash and salt (shared for all keyrings)

### Redux State

Stored separately under the `'state'` key and contains UI state, account data, network settings, etc.

### Storage Keys Summary

- `sysweb3-vault-{slip44}` - Encrypted mnemonics per slip44 (actual Chrome storage keys)
- `sysweb3-vault-keys` - Password hash/salt (shared)
- `sysweb3-global-settings` - Global settings (managed by Pali)
- `sysweb3-state` - Redux state

Note: The keyring package only manages vault storage. Global wallet settings are managed by Pali's MainController.

### Migration Support

The storage layer includes automatic migration:

1. If a slip44-specific vault doesn't exist, it checks for the legacy global `vault`
2. If found, it migrates the data to the slip44-specific location
3. This ensures backward compatibility while moving to the new architecture

## Key Principles

### 1. **One Unlocked Keyring at a Time**

- Only the active keyring should be unlocked
- All other keyrings remain locked
- This prevents cross-keyring state contamination and provides clear security boundaries

### 2. **Session Transfer on Switch**

- When switching between keyrings (different slip44), session data is transferred
- The previous keyring is locked immediately after session transfer
- This ensures continuity while maintaining security

### 3. **Fail-Fast on Locked Target**

- If switching to a locked keyring and no session can be transferred, the operation fails
- This forces explicit unlock and prevents silent failures

## Implementation Details

### Key Methods Updated:

#### `switchActiveKeyring()`

```typescript
// Handles the complete keyring switching flow:
// 1. Check if session transfer is needed (different slip44 + current unlocked)
// 2. Create target keyring if it doesn't exist
// 3. Transfer session from current to target keyring
// 4. Lock the previous keyring
// 5. Set up network on the new active keyring
// 6. Lock all other keyrings as a safety measure
```

#### `unlockFromController()`

```typescript
// When unlocking:
// 1. Unlock the active keyring with password
// 2. Lock all other keyrings to maintain single-active principle
// 3. Continue with normal unlock flow
```

#### `lockWallet()`

```typescript
// When locking:
// Lock ALL keyrings, not just the active one
// This ensures complete security when user explicitly locks
```

## Benefits

1. **Security**: Clear boundaries - only one keyring has access to sensitive data at a time
2. **Simplicity**: No complex state synchronization between multiple unlocked keyrings
3. **Predictability**: Always know which keyring is active and unlocked
4. **Memory Efficiency**: Only one set of decrypted keys in memory

## Edge Cases Handled

1. **Creating new keyring**: Session is automatically transferred from existing unlocked keyring
2. **Switching to same slip44**: No session transfer needed, just network setup
3. **No unlocked keyring**: Switching fails with clear error message
4. **Explicit lock**: All keyrings are locked for complete security

## Session Data Transfer

The session data includes:

- `sessionPassword`: The encrypted session password
- `sessionMnemonic`: The encrypted mnemonic
- `sessionMainMnemonic`: The main account mnemonic
- `currentSessionSalt`: The salt for session encryption

This data is transferred atomically to prevent partial states.

## Future Considerations

1. **Performance**: Session transfer is fast (just copying encrypted data)
2. **UX**: Users experience seamless network switching without re-entering passwords
3. **Multi-device**: This architecture supports future multi-device scenarios cleanly

### Session Management

The KeyringManager uses encrypted session storage for temporary runtime data:

- `sessionPassword`: The hashed password for the current session
- `sessionMnemonic`: The encrypted mnemonic phrase
Loading
Loading