DID Upgrade Documentation (#1077)

Co-authored-by: Scott Phillips <[email protected]>

Author: Joshua Coffey

docs/reference/services/provider-service.md

@@ -270,6 +270,72 @@ Deletes a webhook from an ecosystem.
 
 {{ proto_method_tabs("services.provider.v1.Provider.DeleteWebhook") }}
 
+---
+
+## Upgrade Wallet DID
+
+!!! warning "Restricted API"
+    This feature is not yet publicly available, and the list of supported DID Methods is not final.
+
+    Please contact Trinsic to enable this endpoint on your account.
+
+!!! info "Ledger Interactions"
+    Many DID methods are based on distributed ledgers (commonly known as "blockchains"), so the following should be kept in mind when registering a DID which uses a ledger:
+
+    - Depending on the DID method chosen, registering a DID may incur a ledger write fee, which is different for each ledger. **You are responsible for these fees.**
+        - We will provide clear documentation regarding these fees before this feature becomes generally available.
+    - Newly-registered DIDs may not be immediately resolvable, as most ledgers cannot provide instantaneous writes.
+        - Issuance and verification of credentials against these DIDs will still function during this time, but only within the Trinsic platform.
+
+Upgrades a wallet's DID from the default `did:key` to another DID Method. This endpoint may only be called by an ecosystem provider.
+
+Trinsic will register a DID Document for you, and update the wallet's `public_did` property to the newly-registered DID. Credentials previously issued by this wallet will not have their `issuer` field updated to the new DID, but they will still verify correctly.
+
+Presently, once a wallet's DID has been upgraded, its DID Method cannot be changed again. However, it is possible to perform further upgrades _within_ a method, to go from a testing to production network (for example, `did:ion:test` to `did:ion`). 
+
+{{ proto_sample_start() }}
+    === "Trinsic CLI"
+        ```bash
+        trinsic provider upgrade-did --wallet-id {wallet_id} --method ion --method-options testnet
+        ```
+
+    === "TypeScript"
+        <!--codeinclude--> 
+        ```typescript
+        [UpgradeDid](../../../web/test/ProviderService.test.ts) inside_block:upgradeDid
+        ```
+        <!--/codeinclude-->
+
+    === "C#"
+        <!--codeinclude-->
+        ```csharp
+        [UpgradeDid](../../../dotnet/Tests/Tests.cs) inside_block:upgradeDid
+        ```
+        <!--/codeinclude-->
+
+    === "Python"
+        <!--codeinclude-->
+        ```python
+        [UpgradeDid](../../../python/samples/provider_demo.py) inside_block:upgradeDid
+        ```
+        <!--/codeinclude-->
+
+    === "Go"
+        <!--codeinclude-->
+        ```golang
+        [UpgradeDid](../../../go/services/provider_service_test.go) inside_block:upgradeDid
+        ```
+        <!--/codeinclude-->
+
+    === "Java"
+        <!--codeinclude-->
+        ```java
+        [UpgradeDid](../../../java/src/test/java/trinsic/ProviderServiceTest.java) inside_block:upgradeDid
+        ```
+        <!--/codeinclude-->
+
+{{ proto_method_tabs("services.provider.v1.Provider.UpgradeDID") }}
+
 <!-- 
 // This call is not yet implemented
 ## List Ecosystems

dotnet/Tests/Tests.cs

@@ -254,6 +254,27 @@ public async Task EcosystemTests() {
             var inviteStatus = await trinsic.Provider.InvitationStatusAsync(new() { InvitationId = invitationId });
             // }
         } catch (Exception) { } // This is expected as a doc sample
+
+
+        // Test upgrading account DID
+        var accountInfo = await trinsic.Account.InfoAsync();
+        var walletId = accountInfo.WalletId;
+
+        // Wrap in try-catch as this ecosystem will not presently have DID upgrade permissions
+        try {
+            // upgradeDid() {
+            var upgradeResponse = await trinsic.Provider.UpgradeDIDAsync(new() {
+                WalletId = walletId,
+                Method = SupportedDidMethod.Ion,
+                IonOptions = new() {
+                    Network = IonOptions.Types.IonNetwork.TestNet
+                }
+            });
+            // }
+        } catch (RpcException e)
+        {
+            e.StatusCode.Should().Be(StatusCode.PermissionDenied);
+        }
     }
 
     [Fact]

dotnet/Trinsic/Trinsic.xml

@@ -2,6 +2,7 @@ package services
 
 import (
 	"context"
+	"github.com/trinsic-id/sdk/go/proto/services/common/v1/common"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -88,6 +89,42 @@ func TestEcosystemUpdateInfo(t *testing.T) {
 	}
 }
 
+func TestUpgradeDid(t *testing.T) {
+	assert2 := assert.New(t)
+
+	trinsic, err := CreateTestTrinsicWithNewEcosystem()
+	if !assert2.Nil(err) {
+		return
+	}
+
+	info, err := trinsic.Account().Info(context.Background())
+	if !assert2.Nil(err) {
+		return
+	}
+
+	walletId := info.WalletId
+
+	// upgradeDid() {
+	upgradeResponse, err := trinsic.Provider().UpgradeDID(context.Background(), &provider.UpgradeDidRequest{
+		Account: &provider.UpgradeDidRequest_WalletId{
+			WalletId: walletId,
+		},
+		Method: common.SupportedDidMethod_ION,
+		Options: &provider.UpgradeDidRequest_IonOptions{
+			IonOptions: &provider.IonOptions{
+				Network: provider.IonOptions_TestNet,
+			},
+		},
+	})
+	// }
+
+	// Should error as ecosystems cannot upgrade by default ATM
+	if assert2.NotNil(err) || assert2.Nil(upgradeResponse) {
+		return
+	}
+
+}
+
 func TestProviderBase_InviteParticipant(t *testing.T) {
 	assert2 := assert.New(t)