Skip to content

Commit d45992a

Browse files
sarahschwartzsarahschwartz
authored
docs: refactor sso docs, add new methods (#420)
Updates the SSO docs to: - move the web example code snippets to the `examples` folder - rename the account modules page to "accounts" - remove the "supported environments" page to the FAQ - add info and examples for new methods - replaces deprecated web3modal example with reown appkit example TODO: - [x] fix or remove the `onSessionStateChange` example in the getting started section
1 parent b7ac911 commit d45992a

20 files changed

+1567
-194
lines changed

‎content/00.zksync-era/30.unique-features/30.zksync-sso/100.faqs.md

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ description: Frequently asked questions about ZKsync SSO.
55

66
## What login options are supported?
77

8-
Currently, only login with passkeys is supported in ZKsync SSO.
9-
We are working on adding support for logging in with an Externally Owned Account (EOA) in the future.
8+
ZKsync SSO supports both logging in with passkeys and with an Externally Owned Account (EOA) where the private key is available.
9+
It does not support logging in with a browser-based wallet extension.
1010

1111
## How secure is ZKsync SSO?
1212

@@ -39,6 +39,36 @@ Refer to the [Getting Started Guide](/zksync-era/unique-features/zksync-sso/gett
3939

4040
The deployed contract addresses for ZKsync Sepolia testnet are available in the [ZKsync SSO repository](https://github.com/matter-labs/zksync-sso/blob/main/packages/auth-server/stores/era-sepolia.json).
4141

42+
## What environments are supported?
43+
44+
ZKsync SSO currently supports web applications through its JavaScript SDK,
45+
and mobile applications via the React Native and Swift SDKs.
46+
47+
### Web
48+
49+
**Supported Browsers:**
50+
51+
- **Google Chrome**
52+
- **Safari**
53+
- **Mozilla Firefox**
54+
- **Microsoft Edge**
55+
- **Opera**
56+
57+
See the full list of specific versions [here](https://caniuse.com/webauthn).
58+
This broad browser support ensures a smooth user experience across various platforms.
59+
60+
### Mobile
61+
62+
The React Native SDK is now available for building React Native applications.
63+
Native Swift and Kotlin SDKs are **coming soon** and will enable developers to incorporate ZKsync SSO features into native mobile applications.
64+
65+
### Coming Soon
66+
67+
Windows 10 users with [Windows Hello](https://www.microsoft.com/en-us/windows/tips/windows-hello) will
68+
not be able to use PIN or facial recognition until RS256 support is added in a future module.
69+
Until then, using a mobile device or a password manager will be required to create compatable passkeys on Windows 10.
70+
The user may still see these options, but will be unable to create an account with the passkey on this platform.
71+
4272
## Have more questions?
4373

4474
Join our [GitHub Discussions](%%zk_git_repo_zksync-developers%%/discussions/)

‎content/00.zksync-era/30.unique-features/30.zksync-sso/24.passkeys.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,3 +50,37 @@ If you are signed in to SSO with a passkey that you deleted,
5050
make sure to click the :u-icon{name="i-tabler-logout-2"} icon
5151
in the top right corner of the SSO popup window.
5252
This will allow you to be able to sign up again and generate a new passkey.
53+
54+
## Registering a New Passkey
55+
56+
If you don't want to use the `zksyncSsoConnector` via the auth server, you can directly register a new passkey using the `registerNewPasskey` method.
57+
58+
```ts
59+
:code-import{filePath="sso/src/registerPasskey.ts"}
60+
```
61+
62+
This method accepts the following type as the input:
63+
64+
```ts
65+
export type RegisterNewPasskeyArgs = ({ passkeyRegistrationOptions: PublicKeyCredentialCreationOptionsJSON } | GeneratePasskeyRegistrationOptionsArgs) & { origin?: string };
66+
```
67+
68+
The [`PublicKeyCredentialCreationOptionsJSON`](https://github.com/MasterKale/SimpleWebAuthn/blob/467f8f1e18834964acf1302c2142a50372a72e16/packages/types/src/index.ts#L52)
69+
type comes from the [`@simplewebauthn/server`](https://simplewebauthn.dev/docs/packages/server) package.
70+
71+
```ts
72+
export type GeneratePasskeyRegistrationOptionsArgs = Partial<GenerateRegistrationOptionsOpts> & { userName: string; userDisplayName: string };
73+
```
74+
75+
The `GeneratePasskeyRegistrationOptionsArgs` type draws from
76+
the [`GenerateRegistrationOptionsOpts`](https://github.com/MasterKale/SimpleWebAuthn/blob/467f8f1e18834964acf1302c2142a50372a72e16/packages/server/src/registration/generateRegistrationOptions.ts#L85)
77+
type from the [`@simplewebauthn/server`](https://simplewebauthn.dev/docs/packages/server) package.
78+
79+
The `userName` field defines the unique user ID used to generate to the passkey.
80+
81+
The `userDisplayName` field defines the passkey display name.
82+
83+
The `origin` field optionally defines the domain for the passkey's related origin.
84+
This field defaults to the `window.location.origin` value.
85+
86+
You can refer to the [`@simplewebauthn/server`](https://simplewebauthn.dev/docs/packages/server) docs for specifications on the remaining input fields.

‎content/00.zksync-era/30.unique-features/30.zksync-sso/27.account-modules.md

Lines changed: 0 additions & 24 deletions
This file was deleted.

‎content/00.zksync-era/30.unique-features/30.zksync-sso/27.accounts.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
title: Accounts
3+
description: Get familiar with ZKsync SSO smart accounts.
4+
---
5+
6+
## Account Modules
7+
8+
Developers can enhance the functionality of ZKsync SSO accounts by implementing compatible modules via smart contracts.
9+
The module interface is based on [ERC-7579](https://eips.ethereum.org/EIPS/eip-7579#modules)
10+
to allow maximum flexibility while using ZKsync's powerful native account abstraction to developer overhead.
11+
12+
The existing passkey and session features are already implemented as modules,
13+
and installed by default for every new account deployment.
14+
Modules can be added or removed from the account, without having to migrate or upgrade the whole account.
15+
16+
You can contribute to the smart account modules available to ZKsync SSO users by
17+
submitting a PR to the [`zksync-sso-clave-contracts`](https://github.com/matter-labs/zksync-sso-clave-contracts) repository.
18+
19+
Modules must implement the
20+
[`IModuleValidator`](https://github.com/matter-labs/zksync-sso-clave-contracts/tree/main/src/interfaces/IModuleValidator.sol) interface.
21+
The current implemented modules can be found in the [`validators` folder](https://github.com/matter-labs/zksync-sso-clave-contracts/tree/main/src/validators).
22+
23+
Looking for inspiration?
24+
Take a look at the modules already created for [ERC-7579](https://erc7579.com/modules)
25+
26+
## Deploying an Account From a Registered Passkey
27+
28+
You can deploy a modular account from a [registered passkey](/zksync-era/unique-features/zksync-sso/passkeys#registering-a-new-passkey)
29+
using the `deployModularAccount` method:
30+
31+
```ts
32+
:code-import{filePath="sso/src/deployModularAccount.ts"}
33+
```
34+
35+
### ECDSA Signer
36+
37+
You can authorize transactions for an account using an ECDSA signer.
38+
The example below assumes an SSO account has already been deployed as shown in the example above.
39+
The private key here must match one of the owner accounts defined when the account was deployed.
40+
41+
The `ecdsaClient` here can be used like a [`viem` wallet client](https://viem.sh/docs/clients/wallet) to send transactions.
42+
43+
```ts
44+
:code-import{filePath="sso/src/ecdsa.ts"}
45+
```
46+
47+
## Deploying Accounts in React Native
48+
49+
There are two methods available to create a new account and passkey pair: `registerAccount` and `registerAccountWithUniqueId`.
50+
51+
- `registerAccount` creates a random wallet address.
52+
- `registerAccountWithUniqueId` creates a deterministic wallet address based on the deploy wallet private key and the user ID.
53+
54+
Both of these methods accept the same input argument types and return the same `Account` type:
55+
56+
```ts
57+
interface RPInfo {
58+
name: string;
59+
id: RpId;
60+
}
61+
62+
interface AccountInfo {
63+
name: string;
64+
userID: string;
65+
rp: RPInfo;
66+
}
67+
68+
const registerAccountWithUniqueId = async (
69+
accountInfo: AccountInfo,
70+
challenge: string,
71+
config: Config
72+
): Promise<Account>
73+
```
74+
75+
See the [Getting Started](/zksync-era/unique-features/zksync-sso/getting-started) page for an example for how to use these methods.
76+
77+
For web3 native applications, generally `registerAccount` is recommended.
78+
In this case, only the account address must be stored somewhere.
79+
The account address cannot be derived in any way.
80+
81+
For web2 native applications that already have a username or email used to login,
82+
`registerAccountWithUniqueId` can be used to create an address based on that account info.
83+
In this case, the address can be derived from the userID using the `getAccountByUserId` method.
84+
85+
```ts
86+
import { type Account, getAccountByUserId } from "react-native-zksync-sso";
87+
88+
const account: Account = await getAccountByUserId(uniqueAccountId, config);
89+
```

‎content/00.zksync-era/30.unique-features/30.zksync-sso/5.getting-started.md

Lines changed: 14 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -55,139 +55,11 @@ Just 2 steps:
5555
::code-group
5656

5757
```ts [wagmi]
58-
import { zksyncSsoConnector, callPolicy } from "zksync-sso/connector";
59-
import { zksyncSepoliaTestnet } from "viem/chains";
60-
import { createConfig, connect } from "@wagmi/core";
61-
import { erc20Abi } from "viem";
62-
63-
const ssoConnector = zksyncSsoConnector({
64-
// Optional session configuration, if omitted user will have to sign every transaction via Auth Server
65-
session: {
66-
expiry: "1 day",
67-
68-
// Allow up to 0.1 ETH to be spend in gas fees
69-
feeLimit: parseEther("0.1"),
70-
71-
transfers: [
72-
// Allow ETH transfers of up to 0.1 ETH to specific address
73-
{
74-
to: "0x188bd99cd7D4d78d4E605Aeea12C17B32CC3135A",
75-
valueLimit: parseEther("0.1"),
76-
},
77-
],
78-
79-
// Allow calling specific smart contracts (e.g. ERC20 transfer):
80-
contractCalls: [
81-
callPolicy({
82-
address: "0xa1cf087DB965Ab02Fb3CFaCe1f5c63935815f044",
83-
abi: erc20Abi,
84-
functionName: "transfer",
85-
constraints: [
86-
// Only allow transfers to this address. Or any address if omitted
87-
{
88-
index: 0, // First argument of erc20 transfer function, recipient address
89-
value: "0x6cC8cf7f6b488C58AA909B77E6e65c631c204784",
90-
},
91-
92-
// Allow transfering up to 0.2 tokens per hour
93-
// until the session expires
94-
{
95-
index: 1,
96-
limit: {
97-
limit: parseUnits("0.2", TOKEN.decimals),
98-
period: "1 hour",
99-
},
100-
},
101-
],
102-
}),
103-
],
104-
},
105-
// Optional: Receive notifications about session state changes
106-
onSessionStateChange: ({ state, address, chainId }) => {
107-
console.log(`Session state for address ${address} changed: ${state.type} - ${state.message}`);
108-
109-
// Use this to notify users and restart the session if needed
110-
// - Session expired: state.type === 'session_expired'
111-
// - Session inactive (e.g. was revoked): state.type === 'session_inactive'
112-
},
113-
});
114-
115-
const wagmiConfig = createConfig({
116-
connectors: [ssoConnector],
117-
..., // your wagmi config https://wagmi.sh/core/api/createConfig
118-
});
119-
120-
const connectWithSSO = () => {
121-
connect(wagmiConfig, {
122-
connector: ssoConnector,
123-
chainId: zksyncSepoliaTestnet.id, // or another chain id that has SSO support
124-
});
125-
};
58+
:code-import{filePath="sso/src/wagmi.ts"}
12659
```
12760

128-
```ts [web3modal]
129-
import { zksyncSsoConnector, callPolicy } from "zksync-sso/connector";
130-
import { zksyncSepoliaTestnet } from "viem/chains";
131-
import { defaultWagmiConfig } from "@web3modal/wagmi";
132-
import { erc20Abi } from "viem";
133-
134-
const ssoConnector = zksyncSsoConnector({
135-
// Optional session configuration, if omitted user will have to sign every transaction via Auth Server
136-
session: {
137-
expiry: "1 day",
138-
139-
// Allow up to 0.1 ETH to be spend in gas fees
140-
feeLimit: parseEther("0.1"),
141-
142-
transfers: [
143-
// Allow ETH transfers of up to 0.1 ETH to specific address
144-
{
145-
to: "0x188bd99cd7D4d78d4E605Aeea12C17B32CC3135A",
146-
valueLimit: parseEther("0.1"),
147-
},
148-
],
149-
150-
// Allow calling specific smart contracts (e.g. ERC20 transfer):
151-
contractCalls: [
152-
callPolicy({
153-
address: "0xa1cf087DB965Ab02Fb3CFaCe1f5c63935815f044",
154-
abi: erc20Abi,
155-
functionName: "transfer",
156-
constraints: [
157-
// Only allow transfers to this address. Or any address if omitted
158-
{
159-
index: 0, // First argument of erc20 transfer function, recipient address
160-
value: "0x6cC8cf7f6b488C58AA909B77E6e65c631c204784",
161-
},
162-
163-
// Allow transfering up to 0.2 tokens per hour
164-
// until the session expires
165-
{
166-
index: 1,
167-
limit: {
168-
limit: parseUnits("0.2", TOKEN.decimals),
169-
period: "1 hour",
170-
},
171-
},
172-
],
173-
}),
174-
],
175-
},
176-
177-
// Optional: Receive notifications about session state changes
178-
onSessionStateChange: ({ state, address, chainId }) => {
179-
console.log(`Session state for address ${address} changed: ${state.type} - ${state.message}`);
180-
181-
// Use this to notify users and restart the session if needed
182-
// - Session expired: state.type === 'session_expired'
183-
// - Session inactive (e.g. was revoked): state.type === 'session_inactive'
184-
},
185-
});
186-
187-
const wagmiConfig = defaultWagmiConfig({
188-
connectors: [ssoConnector], // add ZKsync SSO as one of the options in the onboarding modal
189-
..., // your web3modal wagmi config https://wagmi.sh/core/api/createConfig
190-
});
61+
```ts [reown]
62+
:code-import{filePath="sso/src/reownAppkit.ts"}
19163
```
19264

19365
::
@@ -287,10 +159,17 @@ Just 2 steps:
287159
const receipt = await accountClient.sendTransaction(tx);
288160
```
289161
290-
## Interfaces
162+
## Examples
163+
164+
We provide several example apps and step-by-step tutorials to help you get started quickly:
291165
292-
You can find the full list of options and their descriptions in the [Interfaces](/zksync-era/unique-features/zksync-sso/interfaces) section.
166+
### Example Apps
293167
294-
## Examples
168+
- [Web examples](https://github.com/matter-labs/zksync-sso/tree/main/examples).
169+
- [React Native example](https://github.com/matter-labs/zksync-sso/tree/main/packages/sdk-platforms/react-native/react-native-zksync-sso/example)
170+
- [Swift example](https://github.com/matter-labs/zksync-sso/tree/main/packages/sdk-platforms/swift/Examples/ExampleApp)
171+
172+
### SSO Tutorials
295173
296-
We provide several example apps to help you get started quickly. Find them on our [GitHub repository](https://github.com/matter-labs/zksync-sso).
174+
- [Build a ZK Game with SSO](https://code.zksync.io/tutorials/build-a-zk-game/building-the-frontend#setting-up-sso-and-contract-interactions)
175+
- [Build a React Native Payment App](https://code.zksync.io/tutorials/sso-react-native)

‎content/00.zksync-era/30.unique-features/30.zksync-sso/60.supported-environments.md

Lines changed: 0 additions & 33 deletions
This file was deleted.

0 commit comments

Comments
 (0)