Mirror from bluesky-social/pds
add example code
+122
-3
+122
-3
ACCOUNT_MIGRATION.md
+122
-3
ACCOUNT_MIGRATION.md
···
34
34
35
35
First, you can grab your entire repository in the from of a [CAR file](https://ipld.io/specs/transport/car/carv1/) by calling `com.atproto.sync.getRepo`. You can then upload those exact bytes to your new PDS through `com.atproto.repo.importRepo`. The new PDS will parse the CAR file, index all blocks and records, and sign a new commit for the repository.
36
36
37
-
Next, you'll need to upload all relevant blobs. These can be discovered by calling `com.atproto.sync.listBlobs` on your old PDS. For each blob, you'll need to download the contents through `com.atproto.sync.getBlob` and upload them to your new PDS through `com.atproto.repo.uploadBlob`.
37
+
Next, you'll need to upload all relevant blobs. These can be discovered by calling `com.atproto.sync.listBlobs` on your old PDS. For each blob, you'll need to download the contents through `com.atproto.sync.getBlob` and upload them to your new PDS through `com.atproto.repo.uploadBlob`.
38
38
39
39
Finally, you'll need to migrate private state. Currently the only private state held on your PDS is your preferences. You can migrate this by calling `app.bsky.actor.getPreferences` on your old PDS, and submitting the results to `app.bsky.actor.putPreferences` on your new PDS.
40
40
41
-
At any point during this process, you can check the status of your new account by calling `com.atproto.server.checkAccountStatus` which will inform you of your repo state, how many records are indexed, how many private state values are stored, how many blobs it is expecting (based on parsing records), and how many blobs have been uploaded.
41
+
At any point during this process, you can check the status of your new account by calling `com.atproto.server.checkAccountStatus` which will inform you of your repo state, how many records are indexed, how many private state values are stored, how many blobs it is expecting (based on parsing records), and how many blobs have been uploaded. If you find you are missing blobs and are not sure which, you may use `com.atproto.repo.listMissingBlobs` on your new PDS to find them.
42
42
43
43
### Updating identity
44
44
···
64
64
65
65
### After migration
66
66
67
-
After migrating, you should be good to start using the app as normal! You'll need to log out and log back in through your new PDS so that the client is talking to the correct service. It's possible that some services (such as feed generators) will have a stale DID cache and may not be able to accurately verify your auth tokens immediately. However, we've found that most services handle this gracefully, and those that don't should sort themselves out pretty quickly.
67
+
After migrating, you should be good to start using the app as normal! You'll need to log out and log back in through your new PDS so that the client is talking to the correct service. It's possible that some services (such as feed generators) will have a stale DID cache and may not be able to accurately verify your auth tokens immediately. However, we've found that most services handle this gracefully, and those that don't should sort themselves out pretty quickly.
68
+
69
+
70
+
## Example Code
71
+
72
+
The below code gives an example of how this account migration flow may function. Please note that it is for documentation purposes only and can not be run exactly as is as there is an out-of-band step where you need to get a confirmation token from your email.
73
+
74
+
It does also not handle some of the more advanced steps such as verifying a full import, looking for missing blobs, adding your own recovery key, or validating the PLC operation itself.
75
+
76
+
```ts
77
+
import AtpAgent from '@atproto/api'
78
+
79
+
const OLD_PDS_URL = 'https://bsky.social'
80
+
const NEW_PDS_URL = 'https://example.com'
81
+
const CURRENT_HANDLE = 'to-migrate.bsky.social'
82
+
const CURRENT_PASSWORD = 'password'
83
+
const NEW_HANDLE = 'migrated.example.com'
84
+
const NEW_ACCOUNT_EMAIL = 'migrated@example.com'
85
+
const NEW_ACCOUNT_PASSWORD = 'password'
86
+
const NEW_PDS_INVITE_CODE = 'example-com-12345-abcde'
87
+
88
+
const migrateAccount = async () => {
89
+
const oldAgent = new AtpAgent({ service: OLD_PDS_URL })
90
+
const newAgent = new AtpAgent({ service: NEW_PDS_URL })
91
+
92
+
await oldAgent.login({
93
+
identifier: CURRENT_HANDLE,
94
+
password: CURRENT_PASSWORD,
95
+
})
96
+
97
+
const accountDid = oldAgent.session?.did
98
+
if (!accountDid) {
99
+
throw new Error('Could not get DID for old account')
100
+
}
101
+
102
+
// Create account
103
+
// ------------------
104
+
105
+
const describeRes = await newAgent.api.com.atproto.server.describeServer()
106
+
const newServerDid = describeRes.data.did
107
+
108
+
const serviceJwtRes = await oldAgent.com.atproto.server.getServiceAuth({
109
+
aud: newServerDid,
110
+
})
111
+
const serviceJwt = serviceJwtRes.data.token
112
+
113
+
await newAgent.api.com.atproto.server.createAccount(
114
+
{
115
+
handle: NEW_HANDLE,
116
+
email: NEW_ACCOUNT_EMAIL,
117
+
password: NEW_ACCOUNT_PASSWORD,
118
+
did: accountDid,
119
+
inviteCode: NEW_PDS_INVITE_CODE,
120
+
},
121
+
{
122
+
headers: { authorization: `Bearer ${serviceJwt}` },
123
+
encoding: 'application/json',
124
+
},
125
+
)
126
+
await newAgent.login({
127
+
identifier: NEW_HANDLE,
128
+
password: NEW_ACCOUNT_PASSWORD,
129
+
})
130
+
131
+
// Migrate Data
132
+
// ------------------
133
+
134
+
const repoRes = await oldAgent.com.atproto.sync.getRepo({ did: accountDid })
135
+
await newAgent.com.atproto.repo.importRepo(repoRes.data, {
136
+
encoding: 'application/vnd.ipld.car',
137
+
})
138
+
139
+
let blobCursor: string | undefined = undefined
140
+
do {
141
+
const listedBlobs = await oldAgent.com.atproto.sync.listBlobs({
142
+
did: accountDid,
143
+
cursor: blobCursor,
144
+
})
145
+
for (const cid of listedBlobs.data.cids) {
146
+
const blobRes = await oldAgent.com.atproto.sync.getBlob({
147
+
did: accountDid,
148
+
cid,
149
+
})
150
+
await newAgent.com.atproto.repo.uploadBlob(blobRes.data, {
151
+
encoding: blobRes.headers['content-type'],
152
+
})
153
+
}
154
+
blobCursor = listedBlobs.data.cursor
155
+
} while (blobCursor)
156
+
157
+
const prefs = await oldAgent.api.app.bsky.actor.getPreferences()
158
+
await newAgent.api.app.bsky.actor.putPreferences(prefs.data)
159
+
160
+
// Migrate Identity
161
+
// ------------------
162
+
163
+
await oldAgent.com.atproto.identity.requestPlcOperationSignature()
164
+
165
+
const getDidCredentials =
166
+
await newAgent.com.atproto.identity.getRecommendedDidCredentials()
167
+
168
+
// @NOTE, this token will need to come from the email from the previous step
169
+
const TOKEN = ''
170
+
171
+
const plcOp = await oldAgent.com.atproto.identity.signPlcOperation({
172
+
token: TOKEN,
173
+
...getDidCredentials.data,
174
+
})
175
+
176
+
await newAgent.com.atproto.identity.submitPlcOperation({
177
+
operation: plcOp.data.operation,
178
+
})
179
+
180
+
// Finalize Migration
181
+
// ------------------
182
+
183
+
await newAgent.com.atproto.server.activateAccount()
184
+
await oldAgent.com.atproto.server.deactivateAccount({})
185
+
}
186
+
```