Merge pull request #2192 from onflow/cf/support-import-aliasing

Support Cadence import aliasing in Dependency Manager

Author: chasefleming

internal/dependencymanager/dependencyinstaller.go

@@ -103,6 +103,7 @@ type DependencyFlags struct {
 	skipAlias         bool   `default:"false" flag:"skip-alias" info:"Skip prompting for an alias"`
 	skipUpdatePrompts bool   `default:"false" flag:"skip-update-prompts" info:"Skip prompting to update existing dependencies"`
 	deploymentAccount string `default:"" flag:"deployment-account,d" info:"Account name to use for deployments (skips deployment account prompt)"`
+	name              string `default:"" flag:"name" info:"Import alias name for the dependency (sets canonical field for Cadence import aliasing)"`
 }
 
 func (f *DependencyFlags) AddToCommand(cmd *cobra.Command) {
@@ -125,6 +126,7 @@ type DependencyInstaller struct {
 	SkipDeployments   bool
 	SkipAlias         bool
 	DeploymentAccount string
+	Name              string
 	logs              categorizedLogs
 	dependencies      map[string]config.Dependency
 	accountAliases    map[string]map[string]flowsdk.Address // network -> account -> alias
@@ -164,6 +166,7 @@ func NewDependencyInstaller(logger output.Logger, state *flowkit.State, saveStat
 		SkipDeployments:   flags.skipDeployments,
 		SkipAlias:         flags.skipAlias,
 		DeploymentAccount: flags.deploymentAccount,
+		Name:              flags.name,
 		dependencies:      make(map[string]config.Dependency),
 		logs:              categorizedLogs{},
 		accountAliases:    make(map[string]map[string]flowsdk.Address),
@@ -222,6 +225,13 @@ func (di *DependencyInstaller) AddBySourceString(depSource string) error {
 		},
 	}
 
+	// If a name is provided, use it as the import alias and set canonical for Cadence import aliasing
+	// This enables "import OriginalContract as AliasName from address" syntax
+	if di.Name != "" {
+		dep.Name = di.Name
+		dep.Canonical = depContractName
+	}
+
 	return di.Add(dep)
 }
 
@@ -257,6 +267,13 @@ func (di *DependencyInstaller) AddByCoreContractName(coreContractName string) er
 		},
 	}
 
+	// If a name is provided, use it as the import alias and set canonical for Cadence import aliasing
+	// This enables "import OriginalContract as AliasName from address" syntax
+	if di.Name != "" {
+		dep.Name = di.Name
+		dep.Canonical = depContractName
+	}
+
 	return di.Add(dep)
 }
 
@@ -275,6 +292,12 @@ func (di *DependencyInstaller) AddByDefiContractName(defiContractName string) er
 		return fmt.Errorf("contract %s not found in DeFi actions contracts", defiContractName)
 	}
 
+	// If a custom name is provided, use it as the dependency name and set canonical
+	if di.Name != "" {
+		targetDep.Name = di.Name
+		targetDep.Canonical = defiContractName
+	}
+
 	return di.Add(*targetDep)
 }
 
@@ -333,6 +356,11 @@ func (di *DependencyInstaller) AddMany(dependencies []config.Dependency) error {
 }
 
 func (di *DependencyInstaller) AddAllByNetworkAddress(sourceStr string) error {
+	// Check if name flag is set - not supported when installing all contracts at an address
+	if di.Name != "" {
+		return fmt.Errorf("--name flag is not supported when installing all contracts at an address (network://address). Please specify a specific contract using network://address.ContractName format")
+	}
+
 	network, address := ParseNetworkAddressString(sourceStr)
 
 	accountContracts, err := di.getContracts(network, flowsdk.HexToAddress(address))
@@ -495,16 +523,26 @@ func (di *DependencyInstaller) fetchDependenciesWithDepth(dependency config.Depe
 	if program.HasAddressImports() {
 		imports := program.AddressImportDeclarations()
 		for _, imp := range imports {
-			importContractName := imp.Imports[0].Identifier.Identifier
+
+			actualContractName := imp.Imports[0].Identifier.Identifier
 			importAddress := flowsdk.HexToAddress(imp.Location.String())
 
+			// Check if this import has an alias (e.g., "import FUSD as FUSD1 from 0xaddress")
+			// If aliased, use the alias as the dependency name so "import FUSD1" resolves correctly
+			dependencyName := actualContractName
+			if imp.Imports[0].Alias.Identifier != "" {
+				dependencyName = imp.Imports[0].Alias.Identifier
+			}
+
 			// Create a dependency for the import
+			// Name is the alias (or actual name if not aliased) - this is what gets resolved in imports
+			// ContractName is the actual contract name on chain - this is what gets fetched
 			importDependency := config.Dependency{
-				Name: importContractName,
+				Name: dependencyName,
 				Source: config.Source{
 					NetworkName:  networkName,
 					Address:      importAddress,
-					ContractName: importContractName,
+					ContractName: actualContractName,
 				},
 			}
 
@@ -567,13 +605,13 @@ func (di *DependencyInstaller) handleFoundContract(dependency config.Dependency,
 	program.ConvertAddressImports()
 	contractData := string(program.CodeWithUnprocessedImports())
 
-	existingDependency := di.State.Dependencies().ByName(contractName)
+	existingDependency := di.State.Dependencies().ByName(dependency.Name)
 
 	// If a dependency by this name already exists and its remote source network or address does not match,
 	// allow it only if an existing alias matches the incoming network+address; otherwise terminate.
 	if existingDependency != nil && (existingDependency.Source.NetworkName != networkName || existingDependency.Source.Address.String() != contractAddr) {
-		if !di.existingAliasMatches(contractName, networkName, contractAddr) {
-			di.Logger.Info(fmt.Sprintf("%s A dependency named %s already exists with a different remote source. Please fix the conflict and retry.", util.PrintEmoji("🚫"), contractName))
+		if !di.existingAliasMatches(dependency.Name, networkName, contractAddr) {
+			di.Logger.Info(fmt.Sprintf("%s A dependency named %s already exists with a different remote source. Please fix the conflict and retry.", util.PrintEmoji("🚫"), dependency.Name))
 			os.Exit(0)
 			return nil
 		}
@@ -588,7 +626,7 @@ func (di *DependencyInstaller) handleFoundContract(dependency config.Dependency,
 		// Find existing pending prompt for this contract or create new one
 		found := false
 		for i := range di.pendingPrompts {
-			if di.pendingPrompts[i].contractName == contractName {
+			if di.pendingPrompts[i].contractName == dependency.Name {
 				di.pendingPrompts[i].needsUpdate = true
 				di.pendingPrompts[i].updateHash = originalContractDataHash
 				found = true
@@ -597,7 +635,7 @@ func (di *DependencyInstaller) handleFoundContract(dependency config.Dependency,
 		}
 		if !found {
 			di.pendingPrompts = append(di.pendingPrompts, pendingPrompt{
-				contractName: contractName,
+				contractName: dependency.Name,
 				networkName:  networkName,
 				needsUpdate:  true,
 				updateHash:   originalContractDataHash,
@@ -607,7 +645,7 @@ func (di *DependencyInstaller) handleFoundContract(dependency config.Dependency,
 	}
 
 	// Check if this is a new dependency before updating state
-	isNewDep := di.State.Dependencies().ByName(contractName) == nil
+	isNewDep := di.State.Dependencies().ByName(dependency.Name) == nil
 
 	err := di.updateDependencyState(dependency, originalContractDataHash)
 	if err != nil {
@@ -618,7 +656,7 @@ func (di *DependencyInstaller) handleFoundContract(dependency config.Dependency,
 	// Handle additional tasks for new dependencies or when contract file doesn't exist
 	// This makes sure prompts are collected for new dependencies regardless of whether contract file exists
 	if isNewDep || !di.contractFileExists(contractAddr, contractName) {
-		err := di.handleAdditionalDependencyTasks(networkName, contractName)
+		err := di.handleAdditionalDependencyTasks(networkName, dependency.Name)
 		if err != nil {
 			di.Logger.Error(fmt.Sprintf("Error handling additional dependency tasks: %v", err))
 			return err
@@ -775,19 +813,29 @@ func (di *DependencyInstaller) updateDependencyAlias(contractName, aliasNetwork
 }
 
 func (di *DependencyInstaller) updateDependencyState(originalDependency config.Dependency, contractHash string) error {
-	// Create the dependency to save, preserving aliases from the original
+	// Create the dependency to save, preserving aliases and canonical from the original
 	dep := config.Dependency{
-		Name:    originalDependency.Name,
-		Source:  originalDependency.Source,
-		Hash:    contractHash,
-		Aliases: originalDependency.Aliases, // Preserve aliases from the original dependency
+		Name:      originalDependency.Name,
+		Source:    originalDependency.Source,
+		Hash:      contractHash,
+		Aliases:   originalDependency.Aliases,
+		Canonical: originalDependency.Canonical,
 	}
 
 	isNewDep := di.State.Dependencies().ByName(dep.Name) == nil
 
 	di.State.Dependencies().AddOrUpdate(dep)
 	di.State.Contracts().AddDependencyAsContract(dep, originalDependency.Source.NetworkName)
 
+	// If this is an aliased import (Name differs from ContractName), set the Canonical field on the contract
+	// This enables flowkit to generate the correct "import X as Y from address" syntax
+	if dep.Name != dep.Source.ContractName {
+		contract, err := di.State.Contracts().ByName(dep.Name)
+		if err == nil && contract != nil {
+			contract.Canonical = dep.Source.ContractName
+		}
+	}
+
 	if isNewDep {
 		msg := util.MessageWithEmojiPrefix("✅", fmt.Sprintf("%s added to flow.json", dep.Name))
 		di.logs.stateUpdates = append(di.logs.stateUpdates, msg)

internal/dependencymanager/dependencyinstaller_test.go

@@ -675,3 +675,178 @@ func TestDependencyFlagsIntegration(t *testing.T) {
 		assert.Nil(t, mainnetDeployment, "Should not create deployment on mainnet")
 	})
 }
+
+func TestAliasedImportHandling(t *testing.T) {
+	logger := output.NewStdoutLogger(output.NoneLog)
+	_, state, _ := util.TestMocks(t)
+
+	gw := mocks.DefaultMockGateway()
+
+	barAddr := flow.HexToAddress("0x0c")     // testnet address hosting Bar
+	fooTestAddr := flow.HexToAddress("0x0b") // testnet Foo address
+
+	t.Run("AliasedImportCreatesCanonicalMapping", func(t *testing.T) {
+		// Testnet GetAccount returns Bar at barAddr and Foo at fooTestAddr
+		gw.GetAccount.Run(func(args mock.Arguments) {
+			addr := args.Get(1).(flow.Address)
+			switch addr.String() {
+			case barAddr.String():
+				acc := tests.NewAccountWithAddress(addr.String())
+				// Bar imports Foo with an alias: import Foo as FooAlias from 0x0b
+				acc.Contracts = map[string][]byte{
+					"Bar": []byte("import Foo as FooAlias from 0x0b\naccess(all) contract Bar {}"),
+				}
+				gw.GetAccount.Return(acc, nil)
+			case fooTestAddr.String():
+				acc := tests.NewAccountWithAddress(addr.String())
+				acc.Contracts = map[string][]byte{
+					"Foo": []byte("access(all) contract Foo {}"),
+				}
+				gw.GetAccount.Return(acc, nil)
+			default:
+				gw.GetAccount.Return(nil, fmt.Errorf("not found"))
+			}
+		})
+
+		di := &DependencyInstaller{
+			Gateways: map[string]gateway.Gateway{
+				config.EmulatorNetwork.Name: gw.Mock,
+				config.TestnetNetwork.Name:  gw.Mock,
+				config.MainnetNetwork.Name:  gw.Mock,
+			},
+			Logger:          logger,
+			State:           state,
+			SaveState:       true,
+			TargetDir:       "",
+			SkipDeployments: true,
+			SkipAlias:       true,
+			dependencies:    make(map[string]config.Dependency),
+		}
+
+		err := di.AddBySourceString(fmt.Sprintf("%s://%s.%s", config.TestnetNetwork.Name, barAddr.String(), "Bar"))
+		assert.NoError(t, err)
+
+		barDep := state.Dependencies().ByName("Bar")
+		assert.NotNil(t, barDep, "Bar dependency should exist")
+
+		fooAliasDep := state.Dependencies().ByName("FooAlias")
+		assert.NotNil(t, fooAliasDep, "FooAlias dependency should exist")
+		assert.Equal(t, "Foo", fooAliasDep.Source.ContractName, "Source ContractName should be the actual contract name (Foo)")
+
+		fooAliasContract, err := state.Contracts().ByName("FooAlias")
+		assert.NoError(t, err, "FooAlias contract should exist")
+		assert.Equal(t, "Foo", fooAliasContract.Canonical, "Canonical should be set to Foo")
+
+		filePath := fmt.Sprintf("imports/%s/Foo.cdc", fooTestAddr.String())
+		fileContent, err := state.ReaderWriter().ReadFile(filePath)
+		assert.NoError(t, err, "Contract file should exist at imports/address/Foo.cdc")
+		assert.NotNil(t, fileContent)
+	})
+}
+
+func TestDependencyInstallerWithAlias(t *testing.T) {
+	logger := output.NewStdoutLogger(output.NoneLog)
+	_, state, _ := util.TestMocks(t)
+
+	serviceAcc, _ := state.EmulatorServiceAccount()
+	serviceAddress := serviceAcc.Address
+
+	t.Run("AddBySourceStringWithName", func(t *testing.T) {
+		gw := mocks.DefaultMockGateway()
+
+		gw.GetAccount.Run(func(args mock.Arguments) {
+			addr := args.Get(1).(flow.Address)
+			assert.Equal(t, addr.String(), serviceAddress.String())
+			acc := tests.NewAccountWithAddress(addr.String())
+			acc.Contracts = map[string][]byte{
+				"NumberFormatter": []byte("access(all) contract NumberFormatter {}"),
+			}
+			gw.GetAccount.Return(acc, nil)
+		})
+
+		di := &DependencyInstaller{
+			Gateways: map[string]gateway.Gateway{
+				config.EmulatorNetwork.Name: gw.Mock,
+			},
+			Logger:          logger,
+			State:           state,
+			SaveState:       true,
+			TargetDir:       "",
+			SkipDeployments: true,
+			SkipAlias:       true,
+			Name:            "NumberFormatterCustom",
+			dependencies:    make(map[string]config.Dependency),
+		}
+
+		err := di.AddBySourceString(fmt.Sprintf("%s://%s.%s", config.EmulatorNetwork.Name, serviceAddress.String(), "NumberFormatter"))
+		assert.NoError(t, err, "Failed to add dependency with import alias")
+
+		// Check that the dependency was added with the import alias name
+		dep := state.Dependencies().ByName("NumberFormatterCustom")
+		assert.NotNil(t, dep, "Dependency should exist with import alias name")
+		assert.Equal(t, "NumberFormatter", dep.Source.ContractName, "Source ContractName should be the actual contract name")
+		assert.Equal(t, "NumberFormatter", dep.Canonical, "Canonical should be set to the actual contract name for import aliasing")
+
+		// Check that the contract was added with canonical field for Cadence import aliasing
+		contract, err := state.Contracts().ByName("NumberFormatterCustom")
+		assert.NoError(t, err, "Contract should exist")
+		assert.Equal(t, "NumberFormatter", contract.Canonical, "Contract Canonical should be set for import aliasing")
+
+		// Check that the file was created with the actual contract name
+		filePath := fmt.Sprintf("imports/%s/NumberFormatter.cdc", serviceAddress.String())
+		fileContent, err := state.ReaderWriter().ReadFile(filePath)
+		assert.NoError(t, err, "Contract file should exist at imports/address/NumberFormatter.cdc")
+		assert.NotNil(t, fileContent)
+	})
+
+	t.Run("AddByCoreContractNameWithName", func(t *testing.T) {
+		// Mock the gateway to return FlowToken contract
+		gw := mocks.DefaultMockGateway()
+		gw.GetAccount.Run(func(args mock.Arguments) {
+			addr := args.Get(1).(flow.Address)
+			acc := tests.NewAccountWithAddress(addr.String())
+			acc.Contracts = map[string][]byte{
+				"FlowToken": []byte("access(all) contract FlowToken {}"),
+			}
+			gw.GetAccount.Return(acc, nil)
+		})
+
+		di := &DependencyInstaller{
+			Gateways: map[string]gateway.Gateway{
+				config.MainnetNetwork.Name: gw.Mock,
+			},
+			Logger:          logger,
+			State:           state,
+			SaveState:       true,
+			TargetDir:       "",
+			SkipDeployments: true,
+			SkipAlias:       true,
+			Name:            "FlowTokenCustom",
+			dependencies:    make(map[string]config.Dependency),
+		}
+
+		err := di.AddByCoreContractName("FlowToken")
+		assert.NoError(t, err, "Failed to add core contract with import alias")
+
+		// Check that the dependency was added with the import alias name
+		dep := state.Dependencies().ByName("FlowTokenCustom")
+		assert.NotNil(t, dep, "Dependency should exist with import alias name")
+		assert.Equal(t, "FlowToken", dep.Source.ContractName, "Source ContractName should be FlowToken")
+		assert.Equal(t, "FlowToken", dep.Canonical, "Canonical should be set to FlowToken for import aliasing")
+	})
+
+	t.Run("AddAllByNetworkAddressWithNameError", func(t *testing.T) {
+		// This test doesn't need gateways since it returns an error before making any gateway calls
+		di := &DependencyInstaller{
+			Logger:    logger,
+			State:     state,
+			SaveState: true,
+			TargetDir: "",
+			Name:      "SomeName",
+		}
+
+		err := di.AddAllByNetworkAddress(fmt.Sprintf("%s://%s", config.EmulatorNetwork.Name, serviceAddress.String()))
+		assert.Error(t, err, "Should error when using --name with network://address format")
+		assert.Contains(t, err.Error(), "--name flag is not supported when installing all contracts", "Error message should mention name flag limitation")
+	})
+}